Comment ajouter des tests Playwright à votre CI de pull request avec GitHub Actions

Comme moi, vous appréciez sans doute d’intégrer une étape de test automatisé à la CI de vos pull requests (PR), pour gagner en confiance avant de fusionner du code. Je vais vous montrer comment ajouter des tests Playwright à vos PR et coordonner le tout avec un workflow CI GitHub Actions.

Si vous ne connaissez pas encore Playwright, le framework d’automatisation des tests Playwright a été lancé pour la première fois en 2017, mais il a récemment gagné en popularité parmi les outils de développement de Microsoft, aux côtés de Visual Studio Code et d’autres.

Le framework d’automatisation des tests Playwright est un excellent moyen d’écrire facilement des tests de bout en bout (E2E) et de vérifier la compatibilité entre navigateurs. J’ai utilisé Selenium et Cypress par le passé. Si vous avez une expérience similaire, Playwright vous rappellera certainement ce dernier. La prise en main est simple, l’écriture des tests aussi, et des mécanismes intégrés permettent d’éviter les tests instables.

Dans cet article, vous découvrirez :

• Les bases de l’écriture de tests de bout en bout avec Playwright

• Comment exécuter des tests Playwright dans votre CI GitHub Actions

• Comment exécuter des tests Playwright sur les URL d’aperçu Netlify de vos déploiements

• Comment conserver les traces de débogage Playwright et les mettre à disposition comme artefacts de build dans la CI GitHub Actions

Avant de commencer, une précision : ce tutoriel Playwright est axé sur JavaScript, mais vous pouvez facilement l’adapter à d’autres projets, comme un projet Playwright en Python. Il porte principalement sur l’intégration à la CI, et non sur l’écriture de tests Playwright avancés. Si vous développez en Java, il existe même un SDK Playwright Java.

Ajouter Playwright à un projet et le tester

Nous allons ajouter Playwright à un projet JavaScript existant. Voici les tâches à effectuer :

1. Installer le package npm Playwright : npm install @playwright/test --dev

2. Ajouter un hook de cycle de vie npm dédié aux tests de bout en bout Playwright

Ces modifications apparaîtront dans votre fichier package.json. Le code ci-dessous vous donne une idée de ce à quoi elles peuvent ressembler parmi les autres contenus et paramètres du manifeste de package :

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

Nous pouvons ensuite ajouter un nouveau fichier de test Playwright à l’emplacement ./e2e/home.spec.ts. Nous créons bien un nouveau répertoire e2e/ à la racine du projet, s’il n’existe pas déjà.

Ajoutez l’extrait de code suivant, un exemple Playwright fictif de test de bout en bout qui configure un cas de test, navigue vers l’URL http://localhost:3000 et vérifie que le titre du site (souvent défini avec l’entité HTML <title>) correspond à la chaîne Dogs security blog. Exemple 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 vous ajoutez l’automatisation Playwright à votre stack pour la première fois, la configuration package.json et l’extrait de code pour ./e2e/home.spec.ts ci-dessus devraient suffire pour démarrer avec un exemple Playwright fonctionnel.

Vérifiez que votre serveur ou application web écoute les requêtes. Vous pouvez ensuite exécuter la commande npm run test:e2e pour confirmer que les tests Playwright s’exécutent et se terminent correctement.

Le résultat des tests Playwright devrait ressembler à ceci :

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)

Hourra ! Notre test Playwright fonctionne !

Automatiser Playwright avec GitHub Actions

Passons à la configuration de notre intégration continue (CI), afin d’exécuter des tests lorsque de nouvelles contributions de code sont apportées à notre projet, par nous-mêmes ou par des contributeurs externes. Nous pourrons ainsi vérifier que ces contributions ne perturbent pas les fonctionnalités existantes.

Si vous gérez vos projets sur GitHub, utiliser GitHub Actions comme workflow CI/CD est très simple, car la plateforme l’intègre déjà. Configurons-le pour que les nouvelles contributions de code via des PR déclenchent notre workflow de tests Playwright et lancent un pipeline CI de bout en bout.

Commençons par configurer Playwright avec des paramètres prédéfinis qui lui indiquent d’exécuter en arrière-plan une commande pour démarrer notre serveur. Nous pouvons ensuite intégrer l’URL aux paramètres plutôt que de la coder en dur dans nos tests Playwright, comme précédemment.

Ajoutez le contenu suivant dans un nouveau fichier appelé playwright.config.ts, à la racine de votre projet JavaScript (là où se trouve votre fichier 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 votre serveur web local utilise un autre port, vous devez modifier le paramètre url ci-dessus en conséquence et vérifier que Playwright peut y accéder dans l’environnement CI.

Notez également que, selon la manière dont votre projet est compilé, vous devrez peut-être modifier votre hook de cycle de vie npm start dans package.json comme suit, afin d’exécuter npm run build avant le démarrage du serveur :

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

Nous pouvons ensuite créer un workflow GitHub Actions pour Playwright.

Ajoutez le contenu suivant dans un nouveau fichier à l’emplacement .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=

Et voilà !

Ouvrez une nouvelle PR dans votre dépôt GitHub et vérifiez que le workflow tests_e2e s’exécute comme prévu et que tous les tests réussissent.

Notez que vous avez peut-être vu des tutoriels ou des articles Playwright mentionnant le dépôt GitHub Actions de Playwright (https://github.com/microsoft/playwright-github-action) ou l’action microsoft/playwright-github-action@v1. Ce n’est toutefois plus nécessaire : cette action GitHub officielle est obsolète. Il est désormais recommandé d’installer et d’utiliser l’interface en ligne de commande playwright, comme nous l’avons fait avec npm ci-dessus.

Comment exécuter des tests Playwright sur les URL d’aperçu Netlify de vos déploiements

Si vous utilisez Netlify pour compiler votre projet frontend et déployer le build côté client sur un site web en ligne, les aperçus Netlify offrent un avantage supplémentaire : ils s’intègrent à vos PR. Chaque fois qu’une pull request est créée ou modifiée, Netlify déploie le projet à une URL. Vous pouvez ainsi inspecter visuellement et tester l’état et la qualité du build frontend associé à cette PR.

Une intégration native à GitHub avec le bot Netlify ressemble à ceci :

Pour exécuter notre test Playwright sur une URL d’aperçu Netlify, nous devons :

1. Mettre à jour l’URL de base de la configuration Playwright afin qu’elle puisse être définie dynamiquement, ou revenir à la valeur par défaut localhost:3000 pour un test Playwright local (dans notre environnement de développement ou dans la CI).

2. Récupérer le numéro de la PR, utilisé par Netlify pour identifier le build frontend et créer une URL unique.

3. Attendre que l’URL d’aperçu Netlify soit disponible.

4. Exécuter notre test Playwright de bout en bout sur l’URL d’aperçu Netlify.

Commençons par mettre à jour le fichier de configuration 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;

Grâce à cette configuration, nous pouvons désormais définir dynamiquement la variable d’environnement PLAYWRIGHT_TEST_BASE_URL dans notre environnement ou dans la CI.

Ensuite, le cas de test Playwright lui-même doit être mis à jour pour ne plus utiliser une URL codée en dur et utiliser à la place la valeur baseURL du fichier de configuration ci-dessus. Modifiez votre fichier de test ./e2e/home.spec.ts comme suit :

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});

Enfin, modifiez le fichier .github/workflows/e2e-ci.yml en y ajoutant deux étapes : l’une utilise une action GitHub pour attendre que l’URL déployée soit disponible, l’autre exécute les tests correspondants. Voici le workflow complet à titre d’exemple :

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

Notez que la deuxième étape, identifiée par tests_e2e_netlify_prepare, peut être configurée avec le délai d’expiration de votre choix. Ici, je l’ai fixé à 3 minutes.

La troisième étape, identifiée par tests_e2e_netlify, est similaire au test Playwright exécuté localement (conservé comme première étape de ce workflow), mais comporte un paramètre supplémentaire : la variable d’environnement PLAYWRIGHT_TEST_BASE_URL, que nous définissons et formatons dynamiquement pour qu’elle corresponde à l’URL de déploiement de l’aperçu Netlify.

J’ai également activé explicitement les fonctionnalités de débogage de Playwright pour obtenir des informations plus détaillées, en ajoutant la variable d’environnement DEBUG: pw:api à cette dernière étape du workflow.

Ouvrez une nouvelle PR et vérifiez que votre workflow de tests de bout en bout se termine correctement :

Félicitations ! Vous avez mis en place une automatisation robuste des tests Playwright de bout en bout, parfaitement intégrée à l’intégration continue de votre projet avec GitHub Actions.

Comment activer le débogage Playwright dans la CI

Playwright facilite le débogage des tests grâce à plusieurs fonctionnalités intégrées. Il propose notamment Playwright Inspector, une interface graphique qui permet d’inspecter les éléments HTML et de parcourir pas à pas les cas de test Playwright. Il intègre également Playwright Trace Viewer, qui permet de revoir un test enregistré.

Playwright Trace Viewer est particulièrement utile lorsque vous rencontrez des tests instables, c’est-à-dire dont les résultats ne sont pas déterministes et qui sont difficiles à reproduire. Face à ce type de problème dans vos tests de bout en bout, vous pouvez activer une fonctionnalité de débogage Playwright qui conserve une trace de toutes les interactions et l’enregistre dans un fichier. Vous pouvez ensuite charger ce fichier dans Playwright Trace Viewer pour comprendre pourquoi le test Playwright a échoué.

Reprenons là où nous en étions et configurons le workflow CI pour activer le traçage Playwright, afin de pouvoir consulter ces fichiers plus tard.

Nous pouvons utiliser l’action GitHub officielle actions/upload-artifact pour conserver des fichiers ou le contenu de répertoires générés lors des builds et les enregistrer comme artefacts. Attention toutefois : n’utilisez pas cette méthode pour enregistrer des fichiers journaux ou d’autres données susceptibles de contenir des informations sensibles, car elles seront accessibles publiquement à tous.

Nous allons ajouter l’étape suivante aux tests de bout en bout locaux existants, identifiés par l’ID de tâche 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

Vous pouvez aussi l’ajouter à d’autres étapes de débogage Playwright d’autres workflows CI, par exemple pour tester l’URL d’aperçu Netlify.

Modifiez ensuite votre fichier .gitignore pour éviter que ces fichiers de trace soient ajoutés au dépôt. Ajoutez-y la ligne suivante :

1test-results/

Enfin, modifiez le fichier de configuration Playwright playwright.config.ts pour activer le traçage. Voici à quoi il devrait ressembler après cette modification :

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;

Et voilà. Mais où trouver l’artefact de débogage ?

Les artefacts CI sont accessibles dans l’onglet Summary d’une exécution GitHub Actions. Dans la capture d’écran suivante, vous pouvez voir l’artefact en bas de la tâche qui s’est terminée correctement dans ma CI :

Je tiens à préciser qu’à ce stade, nous générons le fichier de trace de débogage Playwright pour chaque build, qu’il se termine correctement ou non. Nous avons demandé à la configuration CI de le faire en utilisant la directive if: always() dans l’étape ci-dessus, identifiée par la tâche tests_e2e.

Pour consulter le fichier de trace, téléchargez l’artefact, extrayez-le dans un dossier local et recherchez les informations de débogage Playwright dans le fichier d’archive qu’il contient. Vous pouvez facilement l’ouvrir avec l’interface en ligne de commande Playwright :

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

Playwright ou Cypress ?

Si vous avez déjà utilisé Cypress, l’outil d’automatisation Playwright vous semblera très similaire et familier, que ce soit pour l’interface en ligne de commande, l’interface graphique en direct permettant d’inspecter et de déboguer les tests Playwright ou les mécanismes généraux du langage.

Comment fonctionne Playwright ?

Contrairement à Cypress, un autre outil d’automatisation des tests qui s’injecte dans le DOM de la page Web sous la forme d’une bibliothèque pour contrôler le navigateur, Playwright s’appuie sur les API natives du navigateur pour automatiser les interactions. Par exemple, il utilise le protocole CDP de Chrome pour communiquer avec un navigateur Chrome via le débogage à distance. Playwright prend également en charge tous les principaux navigateurs, notamment Chrome, Firefox, Edge et WebKit. Il offre des fonctionnalités similaires à celles de Cypress, comme la résilience des tests, qui permet d’attendre automatiquement le chargement des éléments et l’exécution des actions afin d’éviter les tests instables.

Qu’est-ce que l’automatisation avec Playwright ?

Playwright est un projet open source de Microsoft qui fournit un framework de tests de bout en bout compatible avec plusieurs navigateurs. Il utilise les API du framework natif d’automatisation des navigateurs pour les contrôler et interagir avec eux, et propose des SDK multilingues pour l’API Playwright. Ses principaux atouts, outre son caractère open source et sa gratuité, sont sa résilience (qui limite les tests instables), l’automatisation complète des navigateurs, le traçage et le débogage.

Poursuivez votre apprentissage de l’automatisation des tests avec Playwright

Si cet article vous a plu et que vous souhaitez approfondir vos connaissances sur Playwright, voici quelques ressources que je vous recommande :

• La documentation de Playwright sur https://playwright.dev est excellente. Elle propose des sections dédiées, comme le débogage avec Playwright, ainsi que des exemples Playwright pour aider les développeurs qui découvrent ce framework de test à se lancer rapidement.

• Pour suivre l’actualité, les tutoriels et les autres contenus destinés aux développeurs sur Playwright, je vous recommande vivement de suivre Debbie O'Brien sur Twitter. Responsable du programme Playwright chez Microsoft, elle intervient régulièrement lors d’événements à ce sujet.

Ressources complémentaires

• Créer un pipeline CI/CD sécurisé avec GitHub Actions

• 10 bonnes pratiques de sécurité pour GitHub

• Tests de sécurité des applications

• Renforcer la sécurité des workflows GitHub avec Snyk