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

| Flag | Qué hace |

|------|----------|

| --headed | Muestra la ventana del navegador |

| --debug | Pausa y abre el inspector |

| --ui | Abre el modo UI interactivo |

| --slow-mo=N | Añade Nms de retraso entre acciones |

| --grep "pattern" | Filtra tests por nombre |

| --grep-invert "pattern" | Excluye tests por nombre |

| --project=name | Ejecuta un proyecto específico (navegador) |

| --workers=N | Número de workers en paralelo |

| --retries=N | Reintenta tests fallidos N veces |

| --shard=X/Y | Ejecuta el shard X de Y |

| --reporter=type | Elige el formato de output |

| --timeout=N | Sobreescribe el timeout del test (ms) |

| --max-failures=N | Detiene después de N fallos |

| --list | Lista todos los tests sin ejecutar |

| --config=file | Usa un archivo de config diferente |

| --pass-with-no-tests | No 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.

→ See also: 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