Saltar a contenido

Configurar Playwright

Estado del adapter: ✅ Completo. Lo usan lippia-neo-generate-test-suite (para escribir tests de UI y de API) y lippia-neo-run-and-heal (para ejecutarlos y repararlos).

Valor en qa-stack.yaml test_framework: playwright
Lenguaje javascript (tests .spec.js) o typescript (tests .spec.ts, requiere tsconfig.json)
Tipos de app web, api e hybrid
Autenticación google_sso, basic_auth, api_token o none
Carpeta de tests por defecto tests/playwright/

¿Querés escribir los tests en Gherkin (.feature)? Usá playwright-bdd o playwright-cucumberjs:

playwright playwright-bdd playwright-cucumberjs
Unidad de test Un .spec por caso, en una carpeta por historia Un Scenario en el .feature del flujo de negocio Igual que playwright-bdd
Quién ejecuta npx playwright test npx bddgen + npx playwright test npx cucumber-js (Playwright como librería)
Filtrar por historia o caso Por carpeta Por .feature, carpeta o tag Por .feature, carpeta o tag
Datos data-driven — ✅ ✅

1. Qué necesitás instalado

Herramienta Versión Para qué Cómo verificarlo
Node.js 18 o superior Ejecutar Playwright y los scripts node -v
@playwright/test La del package.json del proyecto El framework npx playwright --version
Navegadores de Playwright Los de tu versión de Playwright Ejecutar los tests de UI npx playwright install
dotenv Cualquiera Que playwright.config lea .env.tests Figura en package.json
Bash (Git Bash o WSL en Windows) — Ejecutar run.sh y parse-results.sh bash --version

Desde la raíz del proyecto (donde está el package.json):

npm install
npx playwright install

npx playwright install descarga los navegadores. Alcanza con ejecutarlo una vez por máquina, o cada vez que cambia la versión de Playwright.

Para las skills que navegan la aplicación en vivo (lippia-neo-run-manual-testing, lippia-neo-reproduce-bug) hace falta además el MCP de Playwright con su navegador:

npx @playwright/mcp install-browser chrome-for-testing

Si ese paso falla o el MCP no conecta, seguí Configuración del MCP de Playwright.


2. qa-stack.yaml de ejemplo

stack:
  test_framework: playwright
  language: typescript        # o javascript
  app_type: web               # web | api | hybrid
  auth: basic_auth            # google_sso | basic_auth | api_token | none
  pipeline_provider: github

environment:
  base_url: https://techstore-staging.com
  app_version: 2.4.1
  os: Windows 11

paths:
  user_stories_storage:
    type: local
    cloud_provider_mcp: null
    local_path: user-stories/
  test_plans_dir: test-plans/
  tests_dir: tests/playwright/
  reports_dir: test-results/reports/
  scripted_dir: execution/
  exploratory_dir: exploration/
  env_file: .env.tests

commands:
  run_tests: null        # usa el run.sh del adapter → npx playwright test
  install_deps: null     # usa npm ci

3. Configurar playwright.config

Este es el paso más importante: sin él, NEO genera los tests pero no puede ejecutarlos ni leer los resultados. lippia-neo-generate-test-suite te muestra el bloque que corresponde a tu tipo de app al terminar, pero conviene dejarlo listo antes.

Tu playwright.config.js (o .ts) tiene que tener:

Qué Por qué Valor
testDir Que Playwright busque los tests donde NEO los escribe El mismo valor de paths.tests_dir
Reporter JSON parse-results.sh lee ese archivo para saber qué falló ['json', { outputFile: 'test-results/results.json' }]
Carga de .env.tests Que los tests lean las credenciales sin tenerlas escritas require('dotenv').config({ path: '.env.tests' })
use.baseURL Que los tests usen rutas relativas (page.goto('/')) La URL del ambiente bajo prueba
testMatch con la extensión correcta Que Playwright encuentre los archivos generados **/tc-*.spec.ts si el proyecto es TypeScript, **/tc-*.spec.js si es JavaScript

Ejemplo mínimo para una app web:

const { defineConfig, devices } = require('@playwright/test');
require('dotenv').config({ path: '.env.tests' }); // = paths.env_file

module.exports = defineConfig({
  testDir: './tests/playwright',                  // = paths.tests_dir
  retries: process.env.CI ? 2 : 1,
  timeout: 60000,
  reporter: [
    ['json', { outputFile: 'test-results/results.json' }], // requerido por lippia-neo-run-and-heal
    ['html', { outputFolder: 'playwright-report', open: 'never' }],
    ['list'],
  ],
  use: {
    baseURL: process.env.APP_BASE_URL || 'https://techstore-staging.com',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] }, testMatch: '**/tc-*.spec.js' },
    { name: 'firefox',  use: { ...devices['Desktop Firefox'] }, testMatch: '**/tc-*.spec.js' },
  ],
});

Error típico en TypeScript: si el proyecto es typescript, NEO genera archivos .spec.ts. Si dejás testMatch en .spec.js, Playwright no encuentra ningún test. En TypeScript no es un caso raro: pasa siempre que no se cambia.

Según el tipo de app

app_type Qué agregar en projects
web Los proyectos de navegador (chromium, firefox) con testMatch: '**/tc-*.spec.<ext>'
api Un proyecto api sin navegador, con testMatch: '**/tc-*.api.spec.<ext>'
hybrid Los dos: navegadores para los tc-*.spec y api para los tc-*.api.spec

Los tests de UI se ejecutan en Chromium y Firefox a través de los projects del config. Los tests generados no tienen lógica propia para detectar el navegador.


4. Autenticación

basic_auth y api_token

Completá los valores en .env.tests (el archivo lo crea lippia-neo-bootstrap-stack con las claves vacías y queda fuera de git):

# .env.tests
APP_USER=usuario-de-prueba
APP_PASSWORD=contraseña-de-prueba
# si app_type es api o hybrid:
API_BASE_URL=https://api.techstore-staging.com
API_TOKEN_MANAGER=...
API_TOKEN_VIEWER=...

Los tests generados leen esos valores con process.env.NOMBRE y nunca los escriben literales.

google_sso

El login con Google no se automatiza (Google lo detecta y lo bloquea). En su lugar:

  1. Una sola vez, abrís un navegador visible con el script del proyecto (scripts/save-auth.sh o npm run auth:save) y hacés login a mano.
  2. Playwright guarda la sesión (cookies y localStorage) en un archivo JSON.
  3. playwright.config apunta a ese archivo con storageState, y cada test arranca ya logueado.
  4. Cuando la sesión vence, volvés a ejecutar el script.

⚠️ Revisá que la ruta del archivo de sesión coincida en los dos lugares. Las plantillas de configuración usan playwright/.auth/user.json. En cambio, run.sh valida por defecto .auth/auth-state.json, y si no lo encuentra se detiene con Auth state no encontrado. Si tu proyecto usa otra ruta, definí la variable QA_AUTH_STATE_PATH con la ruta real antes de ejecutar.

Nunca subas el archivo de sesión a git. Contiene tokens válidos. Agregá su carpeta (.auth/ o playwright/.auth/) al .gitignore.


5. Qué genera NEO

Un archivo por caso de prueba, dentro de una carpeta por historia:

tests/playwright/              ← paths.tests_dir
└── US-002/
    ├── tc-001-agregar-producto-al-carrito.spec.ts
    ├── tc-002-carrito-vacio.spec.ts
    └── tc-003-crear-orden.api.spec.ts     ← test de API (app_type api / hybrid)

Reglas que siguen los tests generados:

  • Selectores, en este orden de preferencia: rol + nombre (getByRole), label, data-testid, texto visible y, como último recurso, clase CSS o id. Si no se conoce un selector, queda un TODO explícito.
  • Esperas por condición (waitForURL, expect(...).toBeVisible()), nunca pausas fijas como waitForTimeout(2000).
  • Imports con require (CommonJS), salvo que el package.json tenga "type": "module".

6. Cómo lo ejecuta lippia-neo-run-and-heal

lippia-neo-run-and-heal usa el run.sh del adapter, que:

  1. Verifica que exista node_modules y que Playwright esté instalado. Si falta algo, sale con código 2.
  2. Si auth es google_sso, verifica que exista el archivo de sesión.
  3. Borra el resultado de la ejecución anterior, para no confundir resultados viejos con nuevos.
  4. Ejecuta npx playwright test --reporter=json <tests_dir>.
  5. Verifica que se haya generado test-results/results.json.

Variables que podés usar para ajustar la ejecución:

Variable Por defecto Para qué
QA_TESTS_DIR paths.tests_dir Carpeta o carpetas a ejecutar, separadas por espacio (ej. "tests/playwright/US-001 tests/playwright/US-002")
QA_EXCLUDE_DIRS vacío Subcarpetas a excluir, separadas por espacio (ej. "api-contract-v1")
PLAYWRIGHT_FLAGS vacío Flags extra, por ejemplo --project=chromium
PLAYWRIGHT_CONFIG vacío Usar otro archivo de config (ej. playwright.config.ci.ts)
PLAYWRIGHT_JSON_OUTPUT test-results/results.json Dónde se guarda el reporte JSON
QA_AUTH_STATE_PATH .auth/auth-state.json Archivo de sesión que se valida si auth es google_sso

Para ejecutar solo algunas carpetas, usá QA_TESTS_DIR o QA_EXCLUDE_DIRS, que filtran por la ruta real. --grep-invert filtra por el título del test, no por la carpeta.


7. Checklist rápido

node -v                       # 18 o superior
npx playwright --version      # Playwright instalado
ls node_modules > /dev/null && echo "dependencias OK"
grep -n "results.json" playwright.config.*   # reporter JSON configurado
ls .env.tests                 # credenciales (si auth es basic_auth / api_token)

Si todo responde bien, pedile al asistente: "Ejecutá la suite con lippia-neo-run-and-heal".


8. Problemas comunes (y qué hacer)

Lo que ves Por qué puede pasar Qué hacer
node_modules no encontrado No se instalaron las dependencias npm ci (o npm install)
@playwright/test no encontrado Playwright no está en package.json npm install -D @playwright/test
Playwright no escribió el JSON en 'test-results/results.json' El runner falló antes de terminar (config con errores, carpeta inexistente) Revisar la salida que aparece arriba del error
Auth state no encontrado La sesión de Google SSO no existe o está en otra ruta Ejecutar scripts/save-auth.sh, o definir QA_AUTH_STATE_PATH con la ruta real
"No tests found" testDir o testMatch no coinciden con la carpeta o la extensión generadas Alinear testDir con paths.tests_dir y testMatch con .js / .ts
Browser "chrome-for-testing" is not installed al explorar El MCP de Playwright se actualizó y espera otra versión del navegador npx @playwright/mcp@latest install-browser chrome-for-testing (ver Configuración del MCP de Playwright)
Tests que fallan con errores 5xx o de red El ambiente está caído, no es un problema del test NEO lo marca como environment y no lo repara: revisar el ambiente