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:
playwrightplaywright-bddplaywright-cucumberjsUnidad de test Un .specpor caso, en una carpeta por historiaUn Scenarioen el.featuredel flujo de negocioIgual que playwright-bdd Quién ejecuta npx playwright testnpx bddgen+npx playwright testnpx cucumber-js(Playwright como librería)Filtrar por historia o caso Por carpeta Por .feature, carpeta o tagPor .feature, carpeta o tagDatos 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 installdescarga 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,NEOgenera archivos.spec.ts. Si dejástestMatchen.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:
- Una sola vez, abrís un navegador visible con el script del proyecto (
scripts/save-auth.shonpm run auth:save) y hacés login a mano. - Playwright guarda la sesión (cookies y
localStorage) en un archivo JSON. playwright.configapunta a ese archivo constorageState, y cada test arranca ya logueado.- 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.shvalida por defecto.auth/auth-state.json, y si no lo encuentra se detiene conAuth state no encontrado. Si tu proyecto usa otra ruta, definí la variableQA_AUTH_STATE_PATHcon la ruta real antes de ejecutar.Nunca subas el archivo de sesión a git. Contiene tokens válidos. Agregá su carpeta (
.auth/oplaywright/.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 unTODOexplícito. - Esperas por condición (
waitForURL,expect(...).toBeVisible()), nunca pausas fijas comowaitForTimeout(2000). - Imports con
require(CommonJS), salvo que elpackage.jsontenga"type": "module".
6. Cómo lo ejecuta lippia-neo-run-and-heal
lippia-neo-run-and-heal usa el run.sh del adapter, que:
- Verifica que exista
node_modulesy que Playwright esté instalado. Si falta algo, sale con código2. - Si
authesgoogle_sso, verifica que exista el archivo de sesión. - Borra el resultado de la ejecución anterior, para no confundir resultados viejos con nuevos.
- Ejecuta
npx playwright test --reporter=json <tests_dir>. - 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_DIRoQA_EXCLUDE_DIRS, que filtran por la ruta real.--grep-invertfiltra 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 |