Ejecutar npx playwright test corre todo, pero npx playwright test tests/login.spec.ts --grep "payment fails" --debug corre un solo test en el inspector, pausado antes de la primera acción. La diferencia entre conocer la CLI y no conocerla es la diferencia entre volver a ejecutar toda la suite para perseguir un fallo y localizarlo en 30 segundos. Este artículo cubre los flags que usarás a diario: filtrar por archivo, nombre y etiqueta; modos headed y debug; cantidad de workers; reporters; y las combinaciones que resuelven los problemas de configuración de ejecución más comunes.

El comando básico

npx playwright test

Ejecuta todos los tests en tu testDir (generalmente ./tests) en todos los proyectos definidos en playwright.config.ts.

Filtrar qué tests se ejecutan

Por archivo o carpeta

# Ejecutar todos los tests en un archivo específico
npx playwright test tests/login.spec.ts

# Ejecutar todos los tests en una carpeta
npx playwright test tests/api/

# Ejecutar múltiples archivos
npx playwright test tests/login.spec.ts tests/dashboard.spec.ts

Por nombre de test (--grep)

# Ejecutar tests cuyo nombre contenga "login"
npx playwright test --grep "login"

# Ejecutar tests que coincidan con una regex
npx playwright test --grep "login|registration"

# Invertir: ejecutar tests que NO coincidan
npx playwright test --grep-invert "flaky"

El string se hace coincidir contra el título completo del test, que incluye el nombre del bloque describe. "Login page > shows error" coincidiría con --grep "error" o --grep "Login page".

Por etiqueta

Si tus tests usan etiquetas:

test('smoke test @smoke', async ({ page }) => { ... });
npx playwright test --grep "@smoke"

Por proyecto (navegador)

# Solo ejecutar en Chrome
npx playwright test --project=chromium

# Solo ejecutar en Firefox y WebKit
npx playwright test --project=firefox --project=webkit

Modos de UI y navegador

Headed (navegador visible)

npx playwright test --headed

Abre una ventana real del navegador. Útil para ver qué está pasando durante un test.

Cámara lenta

npx playwright test --headed --slow-mo=500

Añade 500ms de retraso entre acciones. Útil para grabar demos o depurar problemas de timing.

Modo UI (interactivo)

npx playwright test --ui

Abre la UI interactiva de Playwright, un depurador de viaje en el tiempo que te permite:

  • Navegar todos los tests en una barra lateral
  • Ejecutar tests individuales
  • Ver una línea de tiempo de cada acción
  • Ver snapshots del DOM en cada paso
  • Inspeccionar llamadas de red

Es la mejor herramienta de depuración que tiene Playwright. Úsala siempre que estés rastreando un fallo confuso.

Modo debug

npx playwright test --debug

Pausa antes de la primera acción y abre el Playwright Inspector. Avanza por las acciones de a una. También puedes escribir comandos de Playwright en la consola del inspector para probar cosas de forma interactiva.

Para un test específico:

npx playwright test tests/login.spec.ts --debug

Codegen (grabar un test nuevo)

npx playwright codegen https://lab.becomeqa.com

Abre un navegador donde tus acciones se graban. El código de Playwright generado aparece en la ventana del inspector. Cópialo a tu archivo de test.

Ejecución paralela

Establecer número de workers

# 4 workers en paralelo
npx playwright test --workers=4

# Secuencial (1 worker)
npx playwright test --workers=1

Sharding (para CI con múltiples máquinas)

# Dividir tests en 4 shards — ejecutar el shard 1 en la máquina 1
npx playwright test --shard=1/4

# Ejecutar el shard 2 en la máquina 2
npx playwright test --shard=2/4

Cada shard ejecuta un subconjunto de tests. El tiempo total dividido por el número de shards (aproximadamente).

Reintentos

# Reintentar tests fallidos hasta 3 veces
npx playwright test --retries=3

Generalmente configuras los reintentos en playwright.config.ts, pero el flag de CLI lo sobreescribe.

Reportes

Elegir reporter

# List (output en consola en vivo)
npx playwright test --reporter=list

# Reporte HTML
npx playwright test --reporter=html

# Dot (output mínimo)
npx playwright test --reporter=dot

# Múltiples reporters
npx playwright test --reporter=html,list

Abrir el último reporte HTML

npx playwright show-report

Abre playwright-report/index.html en tu navegador. Es el reporte visual con todos los resultados de tests, capturas de pantalla, trazas y videos.

Combinar reportes de shards

Después de ejecutar tests con sharding, combina los reportes:

npx playwright merge-reports --reporter html ./blob-reports

Trace Viewer

Ver una traza grabada (el archivo .zip de un test fallido):

npx playwright show-trace trace.zip

O desde el reporte HTML: haz clic en "Trace" en cualquier test fallido.

Combinaciones útiles

# Depurar un test fallido específico
npx playwright test tests/checkout.spec.ts --grep "payment fails" --debug

# Ejecutar solo smoke tests en Chrome, con navegador visible
npx playwright test --grep "@smoke" --project=chromium --headed

# Ejecutar todos los tests pero reintentar los fallos una vez, con output detallado
npx playwright test --retries=1 --reporter=list

# Verificación rápida: solo el primer worker, primeros 5 tests
npx playwright test --workers=1 --max-failures=5

# Ejecutar sin el archivo de config (útil para scripts puntuales)
npx playwright test --config=minimal.config.ts

# Listar todos los tests sin ejecutarlos
npx playwright test --list

Variables de entorno con la CLI

Puedes pasar variables de entorno directamente:

BASE_URL=https://staging.myapp.com npx playwright test

O configurar múltiples:

BASE_URL=https://staging.myapp.com ENV=staging npx playwright test

Están disponibles en tu config y tests via process.env.BASE_URL.

Referencia de flags comunes

FlagQué hace
--headedMuestra la ventana del navegador
--debugPausa y abre el inspector
--uiAbre el modo UI interactivo
--slow-mo=NAñade Nms de retraso entre acciones
--grep "pattern"Filtra tests por nombre
--grep-invert "pattern"Excluye tests por nombre
--project=nameEjecuta un proyecto específico (navegador)
--workers=NNúmero de workers en paralelo
--retries=NReintenta tests fallidos N veces
--shard=X/YEjecuta el shard X de Y
--reporter=typeElige el formato de output
--timeout=NSobreescribe el timeout del test (ms)
--max-failures=NDetiene después de N fallos
--listLista todos los tests sin ejecutar
--config=fileUsa un archivo de config diferente
--pass-with-no-testsNo falla si no se encuentran tests

Scripts en package.json

Añade los comandos comunes como scripts de npm para que los compañeros de equipo no tengan que recordar los flags:

{
  "scripts": {
    "test": "npx playwright test",
    "test:headed": "npx playwright test --headed",
    "test:debug": "npx playwright test --debug",
    "test:ui": "npx playwright test --ui",
    "test:smoke": "npx playwright test --grep @smoke",
    "test:chrome": "npx playwright test --project=chromium",
    "test:report": "npx playwright show-report",
    "test:ci": "npx playwright test --reporter=list,junit"
  }
}

Después cualquiera puede ejecutar npm run test:smoke sin necesitar saber el flag grep.

→ Ver también: Archivo de Configuración de Playwright Explicado: Todas las Opciones | Playwright Trace Viewer: Depura Tests Fallidos Como un Pro | Configuración de VS Code para Playwright: Extensiones, Ajustes y Productividad