Maestro de guionistas: YAML para GitHub Actions en ejecuciones de pruebas CI

Una vez que el conjunto de herramientas Playwright se encuentra en GitHub, el siguiente paso es hacer que cada solicitud de push y pull request ejecute automáticamente dicho conjunto. GitHub Actions proporciona esa plataforma de integración continua, y el flujo de trabajo en YAML que Playwright puede generar sirve como contrato para convertir los eventos del repositorio en pruebas de navegador en los servidores cloud runners. Los equipos que omiten este paso suelen descubrir regresiones solo en una computadora portátil, horas después de la fusión de cambios, cuando resulta más difícil identificar la causa del fallo.

Esta guía abarca:

• cómo GitHub Actions se integra con los proyectos Playwright
• qué decide el bloque on
• cómo está organizado el bloque jobs
• qué hace cada paso en un flujo de trabajo típico de Playwright

Al final, la estructura de un archivo Playwright CI debe ser lo suficientemente legible como para poder editarse cuando cambien las versiones de Node, los navegadores o las ramas. Considere el ejemplo como una plantilla y no como algo desconocido: una vez que se entienda cada elemento, cambiar los ejecutores o agregar una prueba de funcionamiento es sencillo.

Introducción a GitHub Actions y los archivos YAML en Playwright

GitHub Actions es un servicio CI/CD alojado dentro de GitHub. Puede compilar, probar e implementar cambios cada vez que se modifica el repositorio. Para los frameworks de automatización, esto significa una acción inmediata: las mismas órdenes de Playwright se ejecutan en una imagen de ejecutor conocida sin que nadie tenga que abrir un portátil y hacer clic en “ejecutar”.

Las instalaciones nuevas mediante npm init playwright@latest preguntan si se desea agregar un flujo de trabajo de GitHub Actions. Al aceptar esa solicitud, se crea un archivo YAML en la carpeta .github/workflows. Ese archivo especifica la versión de Node, instala las dependencias y ejecuta Playwright cada vez que se realizan envíos o solicitudes de pull a máquinas alojadas en GitHub.

Si se rechaza la solicitud, se puede añadir esa misma estructura más tarde: basta con crear la carpeta .github/workflows e insertar manualmente un archivo YAML con el flujo de trabajo.

La documentación de Playwright incluye un ejemplo listo para usar en la guía de introducción a CI en https://playwright.dev/docs/ci-intro. Ese archivo es el punto de partida habitual para instalar dependencias, preparar navegadores y ejecutar pruebas en cada envío o solicitud de pull relevante.

Comprensión del archivo YAML en GitHub Actions

La muestra a continuación representa un flujo de trabajo típico de Playwright. Cada sección determina cuándo comienza el proceso y qué debe hacer el ejecutor antes de que aparezca un color verde o rojo en la solicitud de fusión.

name: Playwright Tests
on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: lts/*
    - name: Install dependencies
      run: npm ci
    - name: Install Playwright Browsers
      run: npx playwright install --with-deps
    - name: Run Playwright tests
      run: npx playwright test
    - uses: actions/upload-artifact@v4
      if: ${{ !cancelled() }}
      with:
        name: playwright-report
        path: playwright-report/
        retention-days: 30

On Section

La clave on enumera los eventos que inician el flujo de trabajo. Es la puerta de entrada: sin un evento correspondiente, nada se ejecuta.

En la muestra, están conectadas dos familias de eventos:

1. Eventos de push: Un push a main o master inicia el proceso, de modo que los commits directos en las ramas predeterminadas se prueban de inmediato.
2. Eventos de solicitud de fusión: Abrir o actualizar una PR dirigida a main o master también inicia el proceso, por lo que las fusiones propuestas se verifican antes de aplicarse.

Juntos, estos desencadenantes abarcan tanto los commits integrados como las solicitudes de revisión, que constituyen la red de seguridad en la que confían los frameworks de automatización.

Resumen de la sección de trabajos

El bloque jobs es el plan de trabajo que se ejecuta después de que un desencadenante coincide. Cada trabajo generalmente declara:

1. Nombre del trabajo: Una etiqueta como test que identifica la unidad de trabajo.
2. Entorno del ejecutor: La imagen de la máquina, comúnmente ubuntu-latest.
3. Tiempo de espera y condiciones: Límites como timeout-minutes que determinan cuánto tiempo puede ejecutarse el trabajo.
4. Pasos: Acciones ordenadas: retirada de código, instalación, preparación de navegadores, ejecución de pruebas y carga de artefactos.

Esa sección es la columna vertebral del flujo de trabajo: la preparación del entorno, la ejecución de Playwright y el almacenamiento de resultados dependen todos de ella. Si un trabajo falla, GitHub muestra primero el nombre del paso que falló, por lo que etiquetas claras aquí son útiles durante la revisión de incidentes.

Desglose de los pasos

Retirada del código

El ejecutor debe contar con los archivos del repositorio. El proceso de descarga es casi siempre el primero; sin él, los pasos posteriores no tienen nada que instalar o ejecutar. La mayoría de los flujos de trabajo de Playwright utilizan la acción oficial de descarga para que el árbol de trabajo coincida con el commit que inició la ejecución.

Configuración de Node.js

Playwright funciona sobre Node. Al fijar node-version: lts/* se utiliza la última versión de soporte a largo plazo en el ejecutor, de modo que los scripts de instalación y pruebas tengan un entorno estable. También es aceptable fijar explícitamente una versión mayor cuando el proyecto ya utiliza de forma estándar una línea LTS localmente.

Instalación de dependencias

npm ci instala desde package-lock.json en un árbol limpio. Se prefiere sobre npm install en entornos CI porque la instalación basada en el archivo de bloqueo es reproducible entre ejecuciones y genera errores claros cuando el archivo de bloqueo está desactualizado con respecto a package.json.

Instalar los navegadores de Playwright

Las pruebas necesitan binarios de Chromium, Firefox y WebKit, además de paquetes del sistema relacionados. Este paso descarga esos navegadores para que el ejecutor pueda iniciarlos realmente. Omitirlo es una causa común de fallos con resultado positivo en entorno local y negativo en CI, cuando los desarrolladores ya tienen los navegadores almacenados en caché en sus máquinas.

Ejecutar pruebas de Playwright

Esto es lo que ocurre: Playwright ejecuta las pruebas del proyecto en los navegadores configurados e informa si se superan o no. Los fallos se detectan como un código de salida distinto de cero, por lo que la verificación de GitHub bloquea la fusión cuando las reglas de protección de ramas lo exigen.

Subir el informe de pruebas

El flujo de trabajo conserva el informe generado por Playwright mediante upload-artifact, a menudo con la configuración retention-days: 30 para que los fallos permanezcan inspeccionables durante un mes. Una condición como if: ${{ !cancelled() }} omite la carga cuando la ejecución fue cancelada en lugar de completarse. Mantener el informe HTML como un artefacto suele ser más rápido para depurar que volver a ejecutar todo el conjunto de pruebas solo para reproducir una afirmación defectuosa.