Cette page a été traduite par l'API Cloud Translation.

Surveillance des performances avec Lighthouse CI

Ajouter Lighthouse à un système d'intégration continue, tel que GitHub Actions

Katie Hempenius

Lighthouse CI est une suite d'outils permettant d'utiliser Lighthouse lors de l'intégration continue. La CI Lighthouse peut être intégrée aux workflows de développement de différentes manières. Ce guide couvre les sujets suivants:

En utilisant la CLI Lighthouse CI.
Configurer votre fournisseur de CI pour exécuter la CI Lighthouse
Configurer une action GitHub et une vérification de l'état pour la CI Lighthouse Les résultats Lighthouse s'affichent automatiquement dans les requêtes pull GitHub.
Créer un tableau de bord des performances et un datastore pour les rapports Lighthouse

Présentation

Lighthouse CI est une suite d'outils sans frais qui facilite l'utilisation de Lighthouse pour surveiller les performances. Un seul rapport Lighthouse fournit un instantané des performances d'une page Web au moment de son exécution. La CI Lighthouse montre comment ces résultats ont évolué au fil du temps. Cela permet d'identifier l'impact de modifications particulières du code ou de s'assurer que les seuils de performances sont atteints au cours des processus d'intégration continue. Bien que la surveillance des performances soit le cas d'utilisation le plus courant de l'intégration continue Lighthouse, elle peut être utilisée pour surveiller d'autres aspects du rapport Lighthouse, comme le référencement naturel ou l'accessibilité.

La fonctionnalité de base de Lighthouse CI est fournie par l'interface de ligne de commande Lighthouse CI. (Remarque: Il s'agit d'un outil distinct de la CLI Lighthouse.) La CLI Lighthouse CI fournit un ensemble de commandes pour utiliser Lighthouse CI. Par exemple, la commande autorun exécute plusieurs exécutions Lighthouse, identifie le rapport Lighthouse médian et importe le rapport pour le stocker. Ce comportement peut être fortement personnalisé en transmettant des options supplémentaires ou en personnalisant le fichier de configuration de Lighthouse CI, lighthouserc.js.

Bien que la fonctionnalité de base de Lighthouse CI soit principalement encapsulée dans la CLI Lighthouse CI, elle est généralement utilisée par le biais de l'une des approches suivantes:

Exécuter l'intégration continue Lighthouse
Utiliser une action GitHub Lighthouse CI qui s'exécute et commente chaque demande d'extraction
Suivre les performances au fil du temps via le tableau de bord fourni par Lighthouse Server

Toutes ces approches sont basées sur la CLI Lighthouse CI.

Les alternatives à la CI Lighthouse incluent des services tiers de surveillance des performances ou l'écriture de votre propre script pour collecter des données sur les performances au cours du processus CI. Envisagez d'utiliser un service tiers si vous préférez laisser quelqu'un d'autre gérer votre serveur de surveillance des performances et vos appareils de test, ou si vous souhaitez disposer de fonctionnalités de notification (telles que l'intégration par e-mail ou Slack) sans avoir à créer vous-même ces fonctionnalités.

Utiliser Lighthouse CI localement

Cette section explique comment exécuter et installer la CLI Lighthouse CI localement, et comment configurer lighthouserc.js. Exécuter la CLI Lighthouse CI localement est le moyen le plus simple de vous assurer que votre lighthouserc.js est correctement configurée.

Installez la CLI Lighthouse CI.
```
npm install -g @lhci/cli
```
La CI Lighthouse est configurée en plaçant un fichier lighthouserc.js à la racine du dépôt de votre projet. Ce fichier est obligatoire et contient des informations de configuration liées à l'intégration continue Lighthouse. Bien que la CI Lighthouse puisse être configurée pour être utilisée sans dépôt Git, les instructions de cet article supposent que le dépôt de votre projet est configuré pour utiliser Git.
Dans la racine de votre dépôt, créez un fichier de configuration lighthouserc.js.
```
touch lighthouserc.js
```
Ajoutez le code suivant à lighthouserc.js. Ce code est une configuration Lighthouse CI vide. Vous ajouterez des éléments à cette configuration lors des prochaines étapes.
```
module.exports = {
  ci: {
    collect: {
      /* Add configuration here */
    },
    upload: {
      /* Add configuration here */
    },
  },
};
```
Chaque fois que Lighthouse CI s'exécute, il démarre un serveur pour diffuser votre site. Ce serveur permet à Lighthouse de charger votre site même lorsqu'aucun autre serveur n'est en cours d'exécution. Une fois l'exécution de Lighthouse CI terminée, le serveur s'arrête automatiquement. Pour vous assurer que la diffusion fonctionne correctement, vous devez configurer les propriétés staticDistDir ou startServerCommand.

Si votre site est statique, ajoutez la propriété staticDistDir à l'objet ci.collect pour indiquer l'emplacement de vos fichiers statiques. Lighthouse CI utilisera son propre serveur pour diffuser ces fichiers lors du test de votre site. Si votre site n'est pas statique, ajoutez la propriété startServerCommand à l'objet ci.collect pour indiquer la commande qui démarre votre serveur. Lighthouse CI démarre un nouveau processus serveur pendant les tests et l'arrête ensuite.
```
// Static site example
collect: {
  staticDistDir: './public',
}
```
```
// Dynamic site example
collect: {
  startServerCommand: 'npm run start',
}
```
Ajoutez la propriété url à l'objet ci.collect pour indiquer l'URL ou les URL sur lesquelles Lighthouse CI doit exécuter Lighthouse. La valeur de la propriété url doit être fournie sous la forme d'un tableau d'URL. Ce tableau peut contenir une ou plusieurs URL. Par défaut, Lighthouse CI exécute Lighthouse trois fois pour chaque URL.
```
collect: {
  // ...
  url: ['http://localhost:8080']
}
```
Remarque :Ces URL doivent être disponibles sur le serveur que vous avez configuré à l'étape précédente. Ainsi, si vous exécutez Lighthouse CI localement, ces URL devraient probablement inclure localhost plutôt que votre hôte de production.
Ajoutez la propriété target à l'objet ci.upload et définissez la valeur sur 'temporary-public-storage'. Le ou les rapports Lighthouse collectés par la CI Lighthouse seront importés dans un espace de stockage public temporaire. Le rapport y restera sept jours, puis sera automatiquement supprimé. Ce guide de configuration utilise l'option d'importation "Stockage public temporaire", car elle est rapide à configurer. Pour en savoir plus sur d'autres façons de stocker les rapports Lighthouse, consultez la documentation.
```
upload: {
  target: 'temporary-public-storage',
}
```
L'emplacement de stockage du rapport se présente comme suit:
```
https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1580152437799-46441.report.html
```
(Cette URL ne fonctionnera pas, car le rapport a déjà été supprimé.)
Exécutez la CLI Lighthouse CI à partir du terminal à l'aide de la commande autorun. Lighthouse s'exécutera trois fois et importera le rapport Lighthouse médian.
```
lhci autorun
```
Si vous avez correctement configuré Lighthouse CI, l'exécution de cette commande devrait produire un résultat semblable à celui-ci :
```
✅  .lighthouseci/ directory writable
✅  Configuration file found
✅  Chrome installation found
⚠️   GitHub token not set
Healthcheck passed!

Started a web server on port 65324...
Running Lighthouse 3 time(s) on http://localhost:65324/index.html
Run #1...done.
Run #2...done.
Run #3...done.
Done running Lighthouse!

Uploading median LHR of http://localhost:65324/index.html...success!
Open the report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1591720514021-82403.report.html
No GitHub token set, skipping GitHub status check.

Done running autorun.
```
Vous pouvez ignorer le message GitHub token not set dans le résultat de la console. Un jeton GitHub n'est nécessaire que si vous souhaitez utiliser la CI Lighthouse avec une action GitHub. La configuration d'une action GitHub est expliquée plus loin dans cet article.

Cliquez sur le lien commençant par https://storage.googleapis.com... dans la sortie pour accéder au rapport Lighthouse correspondant à l'exécution médiane de Lighthouse.

Les valeurs par défaut utilisées par autorun peuvent être remplacées via la ligne de commande ou lighthouserc.js. Par exemple, la configuration lighthouserc.js ci-dessous indique que cinq exécutions de Lighthouse doivent être collectées chaque fois que autorun s'exécute.

Mettez à jour lighthouserc.js pour utiliser la propriété numberOfRuns :

module.exports = {
    // ...
    collect: {
      numberOfRuns: 5
    },
  // ...
  },
};

Exécutez à nouveau la commande autorun:

lhci autorun

La sortie du terminal doit indiquer que Lighthouse a été exécuté cinq fois au lieu de trois par défaut :

✅  .lighthouseci/ directory writable
✅  Configuration file found
✅  Chrome installation found
⚠️   GitHub token not set
Healthcheck passed!

Automatically determined ./dist as `staticDistDir`.
Set it explicitly in lighthouserc.json if incorrect.

Started a web server on port 64444...
Running Lighthouse 5 time(s) on http://localhost:64444/index.html
Run #1...done.
Run #2...done.
Run #3...done.
Run #4...done.
Run #5...done.
Done running Lighthouse!

Uploading median LHR of http://localhost:64444/index.html...success!
Open the report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1591716944028-6048.report.html
No GitHub token set, skipping GitHub status check.

Done running autorun.

Pour en savoir plus sur les autres options de configuration, consultez la documentation de configuration de Lighthouse CI.

Configurer votre processus CI pour exécuter la CI Lighthouse

La CI Lighthouse peut être utilisée avec votre outil de CI préféré. La section Configurer votre fournisseur CI de la documentation de Lighthouse CI contient des exemples de code montrant comment intégrer Lighthouse CI dans les fichiers de configuration des outils CI courants. Plus précisément, ces exemples de code montrent comment exécuter la CI Lighthouse pour collecter des mesures de performances pendant le processus de CI.

L'utilisation de la CI Lighthouse pour collecter des mesures de performances est un bon point de départ pour la surveillance des performances. Toutefois, les utilisateurs expérimentés peuvent aller plus loin et utiliser l'intégration continue Lighthouse pour échouer les builds s'ils ne répondent pas à des critères prédéfinis, tels que la réussite d'audits Lighthouse spécifiques ou le respect de tous les budgets de performances. Ce comportement est configuré via la propriété assert du fichier lighthouserc.js.

Lighthouse CI accepte trois niveaux d'assertions :

off : ignorer les assertions
warn: échecs d'impression sur stderr
error: imprime les échecs dans stderr et quitte l'intégration continue Lighthouse avec un code de sortie non nul.

Vous trouverez ci-dessous un exemple de configuration lighthouserc.js incluant des assertions. Il définit des assertions pour les scores des catégories de performances et d'accessibilité de Lighthouse. Pour essayer, ajoutez les assertions ci-dessous à votre fichier lighthouserc.js, puis réexécutez Lighthouse CI.

module.exports = {
  ci: {
    collect: {
      // ...
    },
    assert: {
      assertions: {
        'categories:performance': ['warn', {minScore: 1}],
        'categories:accessibility': ['error', {minScore: 1}]
      }
    },
    upload: {
      // ...
    },
  },
};

Le résultat de la console qu'il génère se présente comme suit :

Capture d'écran d'un message d'avertissement généré par Lighthouse CI

Pour en savoir plus sur les assertions de contrôle qualité Lighthouse, consultez la documentation.

Configurer une action GitHub pour exécuter l'intégration continue Lighthouse

Vous pouvez utiliser une action GitHub pour exécuter la CI Lighthouse. Un nouveau rapport Lighthouse est généré chaque fois qu'une modification de code est appliquée à une branche d'un dépôt GitHub. Utilisez-le conjointement avec une vérification de l'état pour afficher ces résultats sur chaque demande d'extraction.

Capture d'écran d'une vérification d'état GitHub

À la racine de votre dépôt, créez un répertoire nommé .github/workflows. Les workflows de votre projet seront placés dans ce répertoire. Un workflow est un processus qui s'exécute à un moment prédéterminé (par exemple, lors du transfert de code) et est composé d'une ou de plusieurs actions.
```
mkdir .github
mkdir .github/workflows
```
Dans .github/workflows, créez un fichier nommé lighthouse-ci.yaml. Ce fichier contiendra la configuration d'un nouveau workflow.
```
touch lighthouse-ci.yaml
```

Ajoutez le texte suivant à lighthouse-ci.yaml.

name: Build project and run Lighthouse CI
on: [push]
jobs:
  lhci:
    name: Lighthouse CI
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - name: Use Node.js 10.x
        uses: actions/setup-node@v1
        with:
          node-version: 10.x
      - name: npm install
        run: |
          npm install
      - name: run Lighthouse CI
        run: |
          npm install -g @lhci/cli@0.3.x
          lhci autorun --upload.target=temporary-public-storage || echo "LHCI failed!"

Cette configuration configure un workflow composé d'une seule tâche qui s'exécute chaque fois qu'un nouveau code est transféré vers le dépôt. Cette tâche comporte quatre étapes :

Consultez le dépôt sur lequel la CI Lighthouse sera exécutée
Installer et configurer Node
Installer les packages npm requis
Exécutez l'intégration continue Lighthouse et importez les résultats dans un espace de stockage public temporaire.

Validez ces modifications et transférez-les vers GitHub. Si vous avez correctement suivi les étapes ci-dessus, le transfert de code vers GitHub déclenchera l'exécution du workflow que vous venez d'ajouter.
Pour vérifier que l'intégration continue Lighthouse s'est déclenchée et pour afficher le rapport qu'elle a généré, accédez à l'onglet Actions de votre projet. Le workflow Build project and Run Lighthouse CI (Créer un projet et exécuter la CI Lighthouse) doit s'afficher sous votre commit le plus récent.

Vous pouvez accéder au rapport Lighthouse correspondant à un commit particulier depuis l'onglet Actions. Cliquez sur le commit, puis sur l'étape du workflow Lighthouse CI, puis développez les résultats de l'étape Exécuter Lighthouse CI.

Vous venez de configurer une action GitHub pour exécuter Lighthouse CI. Cette option est particulièrement utile lorsqu'elle est utilisée avec une vérification de l'état GitHub.

Configurer une vérification de l'état GitHub

Si elle est configurée, une vérification de l'état est un message qui s'affiche sur chaque PR et qui inclut généralement des informations telles que les résultats d'un test ou la réussite d'un build.

Capture d'écran de l'onglet "Settings" (Paramètres) de GitHub

Les étapes ci-dessous expliquent comment configurer une vérification de l'état pour Lighthouse CI.

Accédez à la page GitHub de l'application Lighthouse CI, puis cliquez sur Configurer.
(Facultatif) Si vous appartenez à plusieurs organisations sur GitHub, choisissez l'organisation propriétaire du dépôt pour lequel vous souhaitez utiliser la CI Lighthouse.
Sélectionnez Tous les dépôts si vous souhaitez activer le CI Lighthouse dans tous les dépôts, ou Sélectionner uniquement les dépôts si vous ne souhaitez l'utiliser que dans des dépôts spécifiques, puis sélectionnez les dépôts. Cliquez ensuite sur Install & Authorize (Installer et autoriser).
Copiez le jeton qui s'affiche. Vous l'utiliserez à l'étape suivante.
Pour ajouter le jeton, accédez à la page Paramètres de votre dépôt GitHub, cliquez sur Secrets, puis sur Add a new secret (Ajouter un nouveau secret).
Définissez le champ Nom sur LHCI_GITHUB_APP_TOKEN et le champ Valeur sur le jeton que vous avez copié à l'étape précédente, puis cliquez sur le bouton Ajouter un secret.
Accédez au fichier lighthouse-ci.yaml et ajoutez le nouveau secret d'environnement à la commande "run Lighthouse CI".

-           name: run Lighthouse CI
            run: |
              npm install -g @lhci/cli@0.3.x
              lhci autorun --upload.target=temporary-public-storage || echo "LHCI failed!"
+            env:
+              LHCI_GITHUB_APP_TOKEN: $

La vérification de l'état est prête à l'emploi. Pour le tester, créez une nouvelle demande d'extraction ou transmettez un commit à une demande d'extraction existante.

Configurer le serveur CI Lighthouse

Le serveur de CI Lighthouse fournit un tableau de bord permettant d'explorer l'historique des rapports Lighthouse. Il peut également servir de datastore privé à long terme pour les rapports Lighthouse.

Capture d'écran du tableau de bord du serveur CI Lighthouse

Capture d'écran montrant la comparaison de deux rapports Lighthouse dans le serveur Lighthouse CI

Choisissez les commits à comparer.
Modification du score Lighthouse entre les deux commits.
Cette section n'affiche que les métriques qui ont changé entre les deux commits.
Les régressions sont surlignées en rose.
Les améliorations sont surlignées en bleu.

Le serveur CI Lighthouse est le plus adapté aux utilisateurs qui savent déployer et gérer leur propre infrastructure.

Pour en savoir plus sur la configuration du serveur de CI Lighthouse, y compris des recettes pour utiliser Heroku et Docker pour le déploiement, consultez ces instructions.

En savoir plus

Dépôt GitHub de Lighthouse CI