Cómo agregar pruebas de Playwright a la CI de tu pull request con GitHub Actions

Si eres como yo, seguramente valoras mucho incluir un paso de automatización de pruebas en la CI de tu pull request (PR) para tener más confianza antes de integrar el código. Quiero mostrarte cómo agregar pruebas de Playwright a tus PR y cómo conectar todo con un flujo de trabajo de CI en GitHub Actions.

Si nunca has oído hablar de Playwright, el framework de automatización de pruebas Playwright tuvo su primer lanzamiento en 2017, pero recientemente ganó popularidad como una de las herramientas para desarrolladores de Microsoft (junto con Visual Studio Code y otras).

El framework de automatización de pruebas Playwright es una excelente forma de escribir fácilmente pruebas de extremo a extremo (E2E) y también comprobar la compatibilidad entre navegadores. En el pasado usé Selenium y Cypress, y si tienes una experiencia similar, Playwright seguramente te recordará más a la segunda. Es fácil empezar, escribir pruebas y cuenta con medidas integradas para evitar que las pruebas tengan resultados inestables.

En este artículo aprenderás:

• Los conceptos básicos para escribir pruebas de extremo a extremo con Playwright

• Cómo ejecutar pruebas de Playwright en tu CI de GitHub Actions

• Cómo ejecutar pruebas de Playwright en las URL de vista previa de Netlify donde desplegaste tu proyecto

• Cómo conservar las trazas de depuración de Playwright y ponerlas a disposición como artefactos de compilación en la CI de GitHub Actions

Antes de empezar, una aclaración. Este tutorial de Playwright se centra en JavaScript, pero puedes adaptarlo fácilmente a otros proyectos, como uno de Playwright con Python, ya que se enfoca principalmente en integrarlo en la CI y no en escribir pruebas avanzadas con Playwright. Si eres desarrollador de Java, también hay un SDK de Playwright para Java.

Agregar Playwright a un proyecto y probarlo

Agregaremos Playwright a un proyecto de JavaScript existente. Esto implica las siguientes tareas:

1. Instalar el paquete npm de Playwright: npm install @playwright/test --dev

2. Agregar un hook del ciclo de vida de npm específico para las pruebas de extremo a extremo con Playwright

Estos cambios se reflejarán en tu archivo package.json, que debería verse más o menos como el siguiente fragmento de código, junto con el resto del contenido y la configuración del manifiesto del paquete:

1  “scripts”: {
2    "test:e2e": "playwright test"
3  },
4
5  "devDependencies": {
6    "@playwright/test": "^1.22.2",
7   }

Luego, podemos agregar un nuevo archivo de prueba de Playwright en esta ubicación: ./e2e/home.spec.ts. Para ello, crearemos un nuevo directorio e2e/ en la raíz del proyecto, si aún no existe.

Agrega el siguiente fragmento como ejemplo ilustrativo de una prueba de extremo a extremo con Playwright. Este configura un caso de prueba que navega a la URL http://localhost:3000 y valida que el título del sitio web (que suele definirse mediante la entidad HTML <title>) coincida con la cadena Dogs security blog. Ejemplo de Playwright:

1import { test, expect } from '@playwright/test';
2
3test('page should have title of "Dogs security blog"', async ({ page }) => {
4  await page.goto('http://localhost:3000/');
5  const title = await page.title();
6  expect(title).toBe(“Dogs security blog”);
7});

Si es la primera vez que agregas la automatización de Playwright a tu conjunto de herramientas, la configuración anterior de package.json y el fragmento de código de ./e2e/home.spec.ts deberían ser suficientes para empezar con un ejemplo funcional de Playwright.

Asegúrate de que el servidor o la aplicación web esté escuchando solicitudes. Luego, puedes ejecutar el comando npm run test:e2e para comprobar que las pruebas de Playwright se ejecuten y finalicen correctamente.

El resultado de las pruebas de Playwright debería verse así:

1npm run test:e2e
2
3> the-snyk-blog@0.1.0 test:e2e
4> playwright test
5
6Running 1 test using 1 worker
7
8  ✓  e2e/home.spec.ts:3:1 › page should have title of "Dogs security blog" (4s)
9
10  1 passed (14s)

¡Genial! Ya tenemos una prueba funcional de Playwright.

Automatización de Playwright con GitHub Actions

Ahora, configuremos la integración continua (CI) para ejecutar pruebas cuando se agreguen contribuciones de código a nuestro proyecto, ya sea de nuestra parte o de colaboradores externos. Así podremos comprobar que las contribuciones no rompan la funcionalidad existente.

Si administras tus proyectos en GitHub, es muy fácil usar GitHub Actions como flujo de trabajo de CI/CD, ya que viene integrado en la plataforma. Configurémoslo para que las nuevas contribuciones de código mediante PR activen nuestro flujo de trabajo de pruebas de Playwright y ejecuten un pipeline de CI de extremo a extremo.

Primero, configuraremos Playwright con una configuración predefinida que le indique que ejecute un comando en segundo plano para iniciar nuestro servidor. Luego, podremos incluir la URL en la configuración en lugar de codificarla directamente en el código de las pruebas de Playwright, como hicimos antes.

Agrega el siguiente contenido a un archivo nuevo llamado playwright.config.ts en el directorio raíz de tu proyecto de JavaScript (donde está el archivo package.json):

1import { PlaywrightTestConfig } from '@playwright/test';
2
3const config: PlaywrightTestConfig = {
4  webServer: {
5    command: 'npm run start',
6    url: 'http://localhost:3000',
7  },
8};
9
10export default config;

Si tu servidor web local usa otro puerto, debes ajustar la configuración url anterior para que coincida y asegurarte de que Playwright pueda acceder a él en el entorno de CI.

Ten en cuenta también que, según cómo esté compilado tu proyecto, quizá debas actualizar el hook del ciclo de vida de npm start en package.json para que incluya un npm run build antes de iniciar el servidor:

1    "start": "npm run build && next start",

Luego, podemos crear un flujo de trabajo de GitHub Actions para Playwright.

Agrega el siguiente contenido a un archivo nuevo en esta ruta: .github/workflows/e2e-ci.yml:

1name: "Tests: E2E"
2on: [pull_request]
3jobs:
4  tests_e2e:
5    name: Run end-to-end tests
6    runs-on: ubuntu-latest
7    steps:
8      - uses: actions/checkout@v3
9      - uses: actions/setup-node@v3
10      - name: install dependencies
11        run: npm ci
12      - name: install playwright browsers
13        run: npx playwright install --with-deps
14      - name: npm run test:e2e
15        run: npm run test:e2e=

¡Eso es todo!

Abre un PR nuevo en tu repositorio de GitHub y confirma que este flujo de trabajo tests_e2e se ejecute como se espera y que todas las pruebas pasen.

Ten en cuenta que quizá hayas visto tutoriales o artículos de Playwright que mencionan el repositorio de GitHub Actions de Playwright (https://github.com/microsoft/playwright-github-action) o hacen referencia directa a la acción microsoft/playwright-github-action@v1. Sin embargo, ya no se necesitan; esa GitHub Action oficial está obsoleta y se recomienda instalar y usar la CLI de playwright, como hicimos antes con npm.

Cómo ejecutar pruebas de Playwright en las URL de vista previa de Netlify donde desplegaste tu proyecto

Si usas Netlify para compilar tu proyecto de frontend y desplegar la compilación del lado del cliente en un sitio web público, una ventaja adicional son las vistas previas de Netlify, que se integran con tus PR. Cada vez que se crea o modifica un pull request, Netlify despliega el proyecto en una URL para que puedas inspeccionar visualmente e interactuar con el estado y la calidad de la compilación del frontend de ese PR.

Una integración nativa con el bot de Netlify en GitHub se ve así:

Para ejecutar nuestra prueba de Playwright en una URL de vista previa de Netlify, debemos hacer lo siguiente:

1. Actualizar la URL base de la configuración de Playwright para que podamos definirla dinámicamente o volver al valor predeterminado localhost:3000 para ejecutar una prueba local de Playwright (en nuestro entorno de desarrollo o en CI).

2. Extraer el número del PR, que es la forma en que Netlify identifica la compilación del frontend y crea una URL única para ella.

3. Esperar a que la URL de vista previa de Netlify esté disponible.

4. Ejecutar nuestra prueba de extremo a extremo con Playwright en la URL de vista previa de Netlify.

Empecemos por actualizar el archivo de configuración de Playwright:

1import { PlaywrightTestConfig } from '@playwright/test';
2
3const config: PlaywrightTestConfig = {
4    use: {
5        baseURL: process.env.PLAYWRIGHT_TEST_BASE_URL || 'http://localhost:3000'
6    },
7    webServer: {
8        command: "npm run start"
9    }
10};
11
12export default config;

Con esta configuración, ahora podemos definir dinámicamente la variable de entorno PLAYWRIGHT_TEST_BASE_URL en nuestro entorno o en la CI.

A continuación, también debemos actualizar el caso de prueba de Playwright para evitar la URL codificada directamente y usar baseURL, que se obtiene del archivo de configuración anterior. Actualiza el archivo de prueba ./e2e/home.spec.ts así:

1import { test, expect } from '@playwright/test';
2
3test('page should have title of "Dogs security blog"', async ({page, baseURL}) => {
4  await page.goto(baseURL);
5  const title = await page.title();
6  expect(title).toBe(“Dogs security blog”);
7});

Por último, actualiza el archivo .github/workflows/e2e-ci.yml con dos pasos nuevos: uno que use una GitHub Action para esperar a que la URL desplegada esté disponible y otro que ejecute las pruebas. Para que lo tengas como referencia, aquí está el archivo completo del flujo de trabajo:

1name: "Tests: E2E"
2
3on: [pull_request]
4
5env:
6  GITHUB_PR_NUMBER: ${{github.event.pull_request.number}}
7
8jobs:
9  tests_e2e:
10    name: Run end-to-end tests
11    runs-on: ubuntu-latest
12    steps:
13      - uses: actions/checkout@v3
14      - uses: actions/setup-node@v3
15      - name: install dependencies
16        run: npm ci
17      - name: install playwright browsers
18        run: npx playwright install --with-deps
19      - name: npm run test:e2e
20        run: npm run test:e2e
21
22  tests_e2e_netlify_prepare:
23    name: Wait for deployment on Netlify
24    runs-on: ubuntu-latest
25    steps:
26      - name: Waiting for Netlify Preview
27        uses: josephduffy/wait-for-netlify-action@v1
28        id: wait-for-netflify-preview
29        with:
30          site_name: "pull-request"
31          max_timeout: 180
32
33  tests_e2e_netlify:
34    needs: tests_e2e_netlify_prepare
35    name: Run end-to-end tests on Netlify PR preview
36    runs-on: ubuntu-latest
37    timeout-minutes: 5
38    steps:
39      - uses: actions/checkout@v3
40      - uses: actions/setup-node@v3
41      - name: install dependencies
42        run: npm ci
43      - name: install playwright browsers
44        run: npx playwright install --with-deps
45      - name: npm run test:e2e
46        run: npm run test:e2e
47        env:
48          PLAYWRIGHT_TEST_BASE_URL: "https://deploy-preview-${{env.GITHUB_PR_NUMBER}}--pull-request.netlify.app/"
49          DEBUG: pw:api

Ten en cuenta que puedes configurar el tiempo de espera del segundo paso, identificado como tests_e2e_netlify_prepare. En este caso, lo configuré en 3 minutos.

A continuación, el tercer paso, identificado como tests_e2e_netlify, es similar a la prueba de Playwright que se ejecuta localmente (que conservamos como primer paso de este flujo de trabajo), pero incluye una configuración adicional con la variable de entorno PLAYWRIGHT_TEST_BASE_URL, que definimos dinámicamente y damos formato para la URL de vista previa de Netlify que esperamos.

También activé explícitamente las funciones de depuración de Playwright para obtener resultados más detallados, usando DEBUG: pw:api como nueva variable de entorno en ese último paso del flujo de trabajo.

Abre un PR nuevo y comprueba que el flujo de trabajo de pruebas de extremo a extremo finalice correctamente:

¡Felicitaciones! Creaste correctamente una sólida automatización de pruebas de extremo a extremo con Playwright, muy bien integrada en la integración continua de tu proyecto con GitHub Actions.

Cómo agregar la depuración de Playwright en CI

Playwright facilita la depuración de pruebas gracias a varias de sus funciones integradas. Para empezar, incluye Playwright Inspector, una interfaz gráfica que te permite inspeccionar elementos HTML y depurar paso a paso tus casos de prueba de Playwright. Otra función integrada es Playwright Trace Viewer, que te permite reproducir una prueba grabada.

Playwright Trace Viewer es especialmente útil cuando tienes pruebas inestables, es decir, que no son deterministas y son difíciles de reproducir. Cuando surgen este tipo de problemas en tus pruebas de extremo a extremo, puedes activar una función de depuración de Playwright que conserva una traza de todas las interacciones y la guarda en un archivo. Luego, puedes cargar ese archivo en Playwright Trace Viewer e investigar por qué falló la prueba de Playwright.

Retomemos desde donde nos quedamos y configuremos el flujo de trabajo de CI para activar el registro de trazas de Playwright, de modo que podamos acceder a esos archivos más adelante.

Podemos usar la GitHub Action oficial de GitHub actions/upload-artifact para conservar archivos o el contenido de directorios de las compilaciones y guardarlos como artefactos. Ten cuidado de no usar esta técnica para guardar archivos de registro u otros datos que puedan incluir información confidencial, ya que quedan disponibles públicamente para que cualquiera los vea.

Agregaremos el siguiente paso a las pruebas locales de extremo a extremo existentes, identificadas por el ID de trabajo tests_e2e:

1      - name: Upload test results
2        if: always()
3        uses: actions/upload-artifact@v2
4        with:
5          name: playwright-report
6          path: test-results

Si quieres, puedes agregarlo a otros pasos de depuración de Playwright en otros flujos de trabajo de CI, como el que prueba la URL de vista previa de Netlify.

Luego, actualiza el archivo .gitignore para asegurarte de que esas trazas no se confirmen en el repositorio. Agrega lo siguiente al archivo:

1test-results/

Por último, actualiza el archivo de configuración de Playwright playwright.config.ts para activar el registro de trazas. Así debería verse con la actualización:

1import { PlaywrightTestConfig } from '@playwright/test';
2
3const config: PlaywrightTestConfig = {
4  webServer: {
5    command: 'npm run start'
6  },
7  use: {
8    trace: 'on',
9  },
10};
11
12export default config;

Eso es todo. Pero quizá te preguntes dónde puedes ver el artefacto de depuración.

Puedes acceder a los artefactos de CI en la pestaña Summary de una ejecución de GitHub Actions. En la siguiente captura de pantalla, puedes ver que aparece en la parte inferior del trabajo que finalizó correctamente en mi CI:

En este punto, quiero señalar que generamos el archivo de traza de depuración de Playwright para cada compilación, tanto si finaliza correctamente como si no. Le indicamos a la configuración de CI que lo hiciera mediante la directiva if: always() en el paso anterior, identificado como el trabajo tests_e2e.

Para ver el archivo de traza, ahora puedes descargar el artefacto, extraerlo en una carpeta local y encontrar dentro el archivo con la información de depuración de Playwright. Puedes abrirlo fácilmente con la CLI de Playwright así:

1npx playwright show-trace <my-directory>/my-trace.zip

Playwright frente a Cypress

Si ya usaste Cypress, la herramienta de automatización Playwright te resultará muy familiar y cómoda en cuanto a lo que esperarías de la CLI, una interfaz gráfica en vivo para inspeccionar y depurar pruebas de Playwright y la sintaxis general del lenguaje.

¿Cómo funciona Playwright?

A diferencia de Cypress, otra herramienta de automatización de pruebas que se inyecta como biblioteca en el DOM de la página web para controlar el navegador, Playwright usa las API nativas del navegador para controlar la automatización. Por ejemplo, usa el protocolo CDP de Chrome para la depuración remota y comunicarse con un navegador Chrome. Además, Playwright es compatible con los principales navegadores, como Chrome, Firefox, Edge y WebKit, y ofrece capacidades similares a las de Cypress, como la resiliencia de las pruebas, una función útil que espera automáticamente a que aparezcan los elementos y se completen las acciones para evitar pruebas inestables.

¿Qué es la automatización con Playwright?

Playwright es un proyecto de código abierto de Microsoft que ofrece un framework de pruebas de extremo a extremo compatible con varios navegadores. Usa las API del framework nativo de automatización del navegador para controlarlo e interactuar con él, y ofrece SDK multilenguaje para la API de Playwright. Además de ser de código abierto y gratuito, sus principales ventajas son la resiliencia (reduce las pruebas inestables), la automatización completa del navegador, el rastreo y la depuración.

Sigue aprendiendo sobre la automatización de pruebas con Playwright

Si te gustó este artículo y quieres ampliar tus conocimientos sobre Playwright, te recomiendo estos recursos:

• La documentación de Playwright en https://playwright.dev es excelente. Incluye secciones específicas, como la depuración con Playwright, y presenta ejemplos de Playwright para que quienes recién comienzan con este framework de pruebas puedan empezar rápidamente.

• Para conocer novedades, tutoriales y otros contenidos para desarrolladores sobre Playwright, te recomiendo seguir a Debbie O'Brien en Twitter. Es la gerente de programa de Playwright en Microsoft y suele hablar sobre el tema en eventos.

Recursos adicionales

• Cómo crear un pipeline de CI/CD seguro con GitHub Actions

• 10 prácticas recomendadas de seguridad para GitHub

• Pruebas de seguridad de aplicaciones

• Agrega seguridad a los flujos de trabajo de GitHub con Snyk