Surveillance des performances avec Lighthouse CI

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

Katie Hempenius
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 facilitent l'utilisation de Lighthouse pour la surveillance des 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. Vous pouvez l'utiliser pour identifier l'impact de modifications de code spécifiques ou pour vous assurer que les seuils de performances sont atteints lors 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, par exemple l'optimisation SEO 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 la CI Lighthouse soit principalement encapsulée dans la CLI Lighthouse CI, elle est généralement utilisée via 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 reposent sur la CLI Lighthouse CI.

Les alternatives à la CI Lighthouse incluent des services de surveillance des performances tiers ou la création de votre propre script pour collecter des données sur les performances pendant le processus de 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 ces fonctionnalités vous-même.

Utiliser l'intégration continue Lighthouse en local

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.

  1. 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.

  2. Dans la racine de votre dépôt, créez un fichier de configuration lighthouserc.js.

    touch lighthouserc.js
    
  3. Ajoutez le code suivant à lighthouserc.js. Ce code est une configuration de CI Lighthouse vide. Vous allez compléter cette configuration à des étapes ultérieures.

    module.exports = {
      ci: {
        collect: {
          /* Add configuration here */
        },
        upload: {
          /* Add configuration here */
        },
      },
    };
    
  4. 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 des tests 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',
    }
    
  5. 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']
    }
    
  6. Ajoutez la propriété target à l'objet ci.upload et définissez sa 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é.)

  7. 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 la sortie de la console. Un jeton GitHub n'est nécessaire que si vous souhaitez utiliser la CI Lighthouse avec une action GitHub. La procédure de 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 Lighthouse doivent être collectées chaque fois que autorun s'exécute.

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

    module.exports = {
        // ...
        collect: {
          numberOfRuns: 5
        },
      // ...
      },
    };
    
  9. 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 de CI de la documentation sur l'intégration continue Lighthouse contient des exemples de code montrant comment intégrer l'intégration continue Lighthouse aux fichiers de configuration d'outils d'intégration continue courants. Plus précisément, ces exemples de code montrent comment exécuter le contrôle continu Lighthouse pour collecter des mesures de performances pendant le processus de contrôle continu.

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 particuliers 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: imprime les échecs dans 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 exécutez à nouveau la CI Lighthouse.

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 sera généré chaque fois qu'une modification de code sera envoyée vers une branche d'un dépôt GitHub. Utilisez-le en conjonction avec une vérification de l'état pour afficher ces résultats sur chaque requête pull.

Capture d'écran d'une vérification de l'état sur GitHub
  1. À 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
    
  2. Dans .github/workflows, créez un fichier nommé lighthouse-ci.yaml. Ce fichier contiendra la configuration d'un nouveau workflow.

    touch lighthouse-ci.yaml
    
  3. 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:

    • Extrayez le dépôt sur lequel l'intégration continue 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.
  4. 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.

  5. 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.

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

    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.

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

    Vous venez de configurer une action GitHub pour exécuter la CI Lighthouse. 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 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 l'intégration continue Lighthouse.

  1. Accédez à la page de l'application GitHub Lighthouse CI, puis cliquez sur Configurer.

  2. (Facultatif) Si vous appartenez à plusieurs organisations sur GitHub, choisissez celle qui est propriétaire du dépôt pour lequel vous souhaitez utiliser Lighthouse CI.

  3. 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).

  4. Copiez le jeton qui s'affiche. Vous l'utiliserez à l'étape suivante.

  5. Pour ajouter le jeton, accédez à la page Settings (Paramètres) de votre dépôt GitHub, cliquez sur Secrets (Secrets), puis sur Add a new secret (Ajouter un secret).

    Capture d'écran de l'onglet "Settings" (Paramètres) de GitHub
  6. 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.

  7. 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: $
  1. La vérification de l'état est prête à l'emploi. Pour le tester, créez une demande d'extraction ou effectuez un push d'un commit vers 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 de CI Lighthouse
  1. Choisissez les commits à comparer.
  2. Modification du score Lighthouse entre les deux commits.
  3. Cette section n'affiche que les métriques qui ont changé entre les deux commits.
  4. Les régressions sont surlignées en rose.
  5. Les améliorations sont surlignées en bleu.

Lighthouse CI Server convient particulièrement 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