Mcube333/playwright-java-test-writer

Playwright Java Test Writer

Convierte casos de prueba manuales en pruebas mantenibles de Playwright Java que parecen escritas por alguien que es dueño del framework: seguro para paralelismo, sin sleeps inestables, page objects que ocultan localizadores, y reportes Allure que trazan hasta los IDs originales de los casos de prueba.

Flujo de trabajo

1. Analizar los casos de prueba manuales

Extrae de cada caso: ID, título, prioridad/severidad, precondiciones, datos de prueba, pasos, resultado esperado por paso. Las entradas varían (filas de Excel, exportaciones de Jira, Gherkin, texto libre), así que normalízalas a esta forma antes de escribir código.

Si un caso no es automatizable tal como está escrito (necesita OTP de un teléfono real, juicio visual como "se ve correcto", pago de terceros con dinero real), no lo finjas. Ponlo bajo No automatizado en la salida, con la razón y una sugerencia (mockear la API, usar un OTP de prueba, comparación instantánea visual).

2. Detectar primero las convenciones del framework existente

Si el usuario comparte archivos del repositorio (BaseTest, una clase de página, testng.xml, pom.xml), reflejalos exactamente: nombres de paquetes, nombres de clases base, estilo de nombres, estilo de aserciones, cómo se lee la configuración. La consistencia con su código base prevalece sobre el estilo de referencia a continuación.

Si no se comparte nada, usa el scaffold en references/framework-scaffold.md. Solo genera los archivos del scaffold (BaseTest, PlaywrightFactory, BasePage, config) cuando el usuario pida un framework o claramente no tenga uno; de lo contrario, asume que existen y genera solo page objects y tests.

3. Diseñar page objects

• Una clase por página o componente reutilizable (cabecera, carrito de compras, panel de filtros). Los componentes reciben su propia clase y se componen en las páginas.
• Los localizadores son campos private final Locator inicializados en el constructor. Los tests nunca llaman a page.locator(...) directamente.
• Los métodos de página describen intención del usuario (login(user, pass), addToCart(nombreProducto)), no mecánica (hacerClickBoton2). Anótalos con Allure @Step("...") usando placeholders de parámetros, para que el reporte se lea como el caso manual.
• Las acciones que navegan devuelven el siguiente page object (flujo fluido). Los métodos que permanecen en la página devuelven this o void.
• Reutiliza métodos de página existentes antes de agregar nuevos. Si dos pasos se mapean a la misma intención, usa un método.
• Expón estado para aserciones mediante getters con nombre de intención que devuelvan Locator (ej. mensajeError()), para que los tests puedan usar aserciones web-first.

Prioridad de localizadores (de más a menos estable):

1. getByTestId (configura el nombre del atributo una vez si la app usa data-test, data-qa, etc.)
2. getByRole con nombre accesible
3. getByLabel / getByPlaceholder / getByText para texto visible al usuario
4. CSS con atributos estables
5. XPath, solo como último recurso, con un comentario explicando por qué

Si el usuario no proporcionó DOM, HTML o capturas de pantalla, estás adivinando localizadores. Escribe la mejor suposición y márcala con // TODO-VERIFY locator para que nada se envíe silenciosamente con selectores inventados. Menciona la cantidad de localizadores no verificados en el resumen.

4. Escribir los tests

• Un método @Test por caso manual. El nombre del método = comportamiento (deberiaMostrarErrorParaUsuarioBloqueado), no el ID.
• Trazabilidad: coloca el ID del caso en @TmsLink("TC-012") y en description. Agrega @Epic, @Feature, @Story, @Severity mapeados desde la prioridad del caso (P0/Crítico → BLOCKER/CRITICAL, P1 → NORMAL, P2+ → MINOR).
• Cada resultado esperado se convierte en una aserción. Un paso sin aserción significa que la comprobación manual se omitió, así que verifica antes de terminar.
• Las precondiciones van en helpers de configuración o llamadas API, no en largas cadenas de clics en la UI, cuando exista una API o enlace profundo. Para precondiciones de inicio de sesión (especialmente OTP/SSO), prefiere un inicio de sesión por API una vez y reutilízalo mediante context.storageState() / Browser.NewContextOptions().setStorageStatePath(...).
• Casos repetidos con diferentes datos → un test con un @DataProvider de TestNG. @TmsLink es estático, así que pasa el ID del caso como la primera columna de datos y llama a Allure.link(caseId, "tms", caseId) dentro del test para mantener la trazabilidad por fila. Mantén los datos de prueba fuera del cuerpo del test (data provider, JSON o clase de constantes). Nunca uses datos reales de clientes.
• Los tests deben ser independientes: sin dependencia del orden de ejecución, contexto nuevo por test, limpia todo lo creado.

5. Esperas: solo basadas en condiciones

Esta es la principal fuente de inestabilidad, así que trátala como una regla estricta:

• Nunca uses Thread.sleep o page.waitForTimeout.
• Prefiere aserciones web-first: assertThat(locator).isVisible(), hasText, hasCount, assertThat(page).hasURL(...). Reintentan automáticamente.
• Las acciones ya esperan automáticamente a que el elemento sea accionable; no agregues esperas redundantes antes de click()/fill().
• Cuando una acción desencadena una llamada de red cuyo resultado importa, envuélvela: page.waitForResponse(r -> r.url().contains("/cart") && r.ok(), () -> botonAgregar.click()).
• Para spinners/loaders: assertThat(loader).isHidden().
• Para navegación: page.waitForURL("**/checkout**").
• Los tiempos de espera personalizados provienen de la configuración, nunca números mágicos en línea.

Consulta references/framework-scaffold.md → "Patrones de espera" para fragmentos.

6. Seguridad en paralelo

Todos los objetos de Playwright (Playwright, Browser, BrowserContext, Page) viven en ThreadLocals gestionados por la clase base/factory y se crean y cierran por método de test. Nunca los almacenes en campos estáticos ni compartas una Page entre tests. Los page objects reciben la Page mediante el constructor. No se permite estado estático en los page objects.

Formato de salida

Responde con, en este orden:

1. Archivos: cada archivo en su propio bloque de código con su ruta completa como encabezado (ej. src/test/java/com/ejemplo/pages/LoginPage.java). Archivos completos y compilables con imports, no fragmentos, a menos que el usuario haya pedido un snippet. Si son más de ~3 archivos o el usuario quiere descargarlos, escríbelos también en disco como carpeta de proyecto.
2. Tabla de trazabilidad: ID del caso | Método de test | Pasos automatizados | Notas.
3. No automatizado / brechas: casos o pasos omitidos y por qué.
4. Necesita verificación: cantidad y lista de localizadores TODO-VERIFY, suposiciones sobre datos de prueba o entorno.

Mantén la prosa breve; el código es el entregable.

Confidencialidad

Cuando el usuario está construyendo un portafolio público o la solicitud menciona una aplicación demo pública, mantén todo genérico: paquete com.ejemplo (o lo que especifiquen), sin nombres de empresa, URLs internas, endpoints internos, datos reales de usuario o nombres de eventos propietarios. Si los casos manuales pegados contienen esos datos, cámbialos por equivalentes neutros y dílo en una línea.

Archivos de referencia

• references/framework-scaffold.md: dependencias de pom.xml, PlaywrightFactory con ThreadLocals, BaseTest con trazado y adjuntos de Allure en fallo, BasePage, ConfigReader, testng.xml para ejecuciones en paralelo, fragmentos de patrones de espera. Léelo al hacer scaffolding o cuando necesites la forma exacta de la API.
• references/example-saucedemo.md: un ejemplo completo trabajado (casos manuales → page objects → tests → tabla de trazabilidad) en la aplicación pública saucedemo.com. Léelo para calibrar el estilo de salida.