Kontinuierliche Leistungsanalyse mit Lighthouse CI und GitHub Actions

Lighthouse ist ein kostenloses Open-Source-Tool zur Bewertung der Leistung, Barrierefreiheit, Progressive Web App-Metriken, SEO und vielem mehr Ihrer Website. Am einfachsten lässt es sich über das Chrome DevTools-Panel verwenden. Sobald Sie die DevTools öffnen, sehen Sie einen Tab „Lighthouse“. Wenn Sie auf die Schaltfläche „Bericht generieren“ klicken, werden eine Reihe von Tests auf der Webseite ausgeführt und die Ergebnisse direkt im Lighthouse-Tab angezeigt. Dies erleichtert das Testen jeder Webseite, egal ob öffentlich oder authentifizierungspflichtig.

Wenn Sie keine Chrome- oder Chromium-basierten Browser wie Microsoft Edge oder Brave verwenden, können Sie Lighthouse über die Weboberfläche ausführen, diese funktioniert jedoch nur mit öffentlich zugänglichen Webseiten. Für diejenigen, die Lighthouse-Audits von der Kommandozeile ausführen möchten, wird auch ein Node CLI-Tool bereitgestellt.

Alle oben genannten Optionen erfordern eine gewisse manuelle Intervention. Wäre es nicht großartig, wenn wir Lighthouse-Tests in den kontinuierlichen Integrationsprozess integrieren könnten, sodass die Auswirkungen unserer Codeänderungen inline mit jedem Pull-Request angezeigt werden und wir die Builds fehlschlagen lassen können, wenn bestimmte Leistungsschwellenwerte nicht erreicht werden? Nun, genau dafür gibt es Lighthouse CI!

Es ist eine Suite von Tools, die Ihnen helfen, die Auswirkungen spezifischer Codeänderungen auf Ihre Website zu identifizieren, nicht nur in Bezug auf die Leistung, sondern auch in Bezug auf SEO, Barrierefreiheit, Offline-Unterstützung und andere Best Practices. Es bietet eine großartige Möglichkeit, Leistungsbudgets durchzusetzen und hilft Ihnen auch, jede berichtete Metrik zu verfolgen, damit Sie sehen können, wie sie sich im Laufe der Zeit geändert hat.

In diesem Artikel werden wir uns ansehen, wie man Lighthouse CI einrichtet und lokal ausführt und wie man es als Teil eines CI-Workflows über GitHub Actions zum Laufen bringt. Beachten Sie, dass Lighthouse CI auch mit anderen CI-Anbietern wie Travis CI, GitLab CI und Circle CI funktioniert, falls Sie GitHub Actions nicht verwenden möchten.

Lighthouse CI lokal einrichten

In diesem Abschnitt konfigurieren und führen Sie das Lighthouse CI Kommandozeilentool lokal auf Ihrem Rechner aus. Stellen Sie vorab sicher, dass Node.js v10 LTS oder neuer und Google Chrome (stabil) auf Ihrem Rechner installiert sind, und fahren Sie dann mit der globalen Installation des Lighthouse CI-Tools fort.

$ npm install -g @lhci/cli

Nachdem die CLI erfolgreich installiert wurde, geben Sie lhci --help ein, um alle verfügbaren Befehle des Tools anzuzeigen. Zum Zeitpunkt der Erstellung sind acht Befehle verfügbar.

$ lhci --help
lhci <command> <options>

Commands:
  lhci collect      Run Lighthouse and save the results to a local folder
  lhci upload       Save the results to the server
  lhci assert       Assert that the latest results meet expectations
  lhci autorun      Run collect/assert/upload with sensible defaults
  lhci healthcheck  Run diagnostics to ensure a valid configuration
  lhci open         Opens the HTML reports of collected runs
  lhci wizard       Step-by-step wizard for CI tasks like creating a project
  lhci server       Run Lighthouse CI server

Options:
  --help             Show help  [boolean]
  --version          Show version number  [boolean]
  --no-lighthouserc  Disables automatic usage of a .lighthouserc file.  [boolean]
  --config           Path to JSON config file

An diesem Punkt sind Sie bereit, die CLI für Ihr Projekt zu konfigurieren. Die Lighthouse CI-Konfiguration kann verwaltet werden über (in aufsteigender Reihenfolge der Priorität): eine Konfigurationsdatei, Umgebungsvariablen oder CLI-Flags. Sie verwendet die Yargs API, um ihre Konfigurationsoptionen zu lesen, was bedeutet, dass sie auf vielfältige Weise konfiguriert werden kann. Die vollständige Dokumentation deckt alles ab. In diesem Beitrag werden wir die Konfigurationsdateioption nutzen.

Erstellen Sie eine Datei namens lighthouserc.js im Stammverzeichnis Ihres Projektverzeichnisses. Stellen Sie sicher, dass das Projekt mit Git verfolgt wird, da Lighthouse CI die Build-Kontexteinstellungen automatisch aus dem Git-Repository ableitet. Wenn Ihr Projekt Git nicht verwendet, können Sie die Build-Kontexteinstellungen stattdessen über Umgebungsvariablen steuern.

touch lighthouserc.js

Hier ist die einfachste Konfiguration, die Lighthouse-Berichte für ein statisches Website-Projekt ausführt und sammelt und sie in einem temporären öffentlichen Speicher hochlädt.

// lighthouserc.js
module.exports = {
  ci: {
    collect: {
      staticDistDir: './public',
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
};

Das Objekt ci.collect bietet mehrere Optionen, um zu steuern, wie Lighthouse CI Testberichte sammelt. Die Option staticDistDir wird verwendet, um den Speicherort Ihrer statischen HTML-Dateien anzugeben — zum Beispiel kompiliert Hugo in ein public-Verzeichnis, Jekyll platziert seine Build-Dateien in ein _site-Verzeichnis usw. Alles, was Sie tun müssen, ist, die Option staticDistDir auf den Speicherort Ihres Builds zu aktualisieren. Wenn Lighthouse CI ausgeführt wird, startet es einen Server, der die Tests entsprechend ausführen kann. Sobald der Test abgeschlossen ist, schaltet sich der Server automatisch ab.

Wenn Ihr Projekt die Verwendung eines benutzerdefinierten Servers erfordert, können Sie den Befehl zum Starten des Servers über die Eigenschaft startServerCommand eingeben. Wenn diese Option verwendet wird, müssen Sie auch die zu testenden URLs über die Option url angeben. Diese URL sollte vom angegebenen benutzerdefinierten Server bedient werden können.

module.exports = {
  ci: {
    collect: {
      startServerCommand: 'npm run server',
      url: ['https://:4000/'],
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
};

Wenn Lighthouse CI ausgeführt wird, führt es den Befehl server aus und überwacht die Zeichenfolge listen oder ready, um festzustellen, ob der Server gestartet wurde. Wenn es diese Zeichenfolge nach 10 Sekunden nicht erkennt, geht es davon aus, dass der Server gestartet wurde und fährt mit dem Test fort. Anschließend führt es Lighthouse dreimal gegen jede URL im Array url aus. Sobald der Test abgeschlossen ist, wird der Serverprozess beendet.

Sie können sowohl das Muster der zu überwachenden Zeichenfolge als auch die Timeout-Dauer über die Optionen startServerReadyPattern und startServerReadyTimeout konfigurieren. Wenn Sie die Anzahl der Ausführungen von Lighthouse für jede URL ändern möchten, verwenden Sie die Eigenschaft numberOfRuns.

// lighthouserc.js
module.exports = {
  ci: {
    collect: {
      startServerCommand: 'npm run server',
      url: ['https://:4000/'],
      startServerReadyPattern: 'Server is running on PORT 4000',
      startServerReadyTimeout: 20000 // milliseconds
      numberOfRuns: 5,
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
};

Die Eigenschaft target innerhalb des Objekts ci.upload wird verwendet, um zu konfigurieren, wohin Lighthouse CI die Ergebnisse nach Abschluss eines Tests hochlädt. Die Option temporary-public-storage zeigt an, dass der Bericht in den Google Cloud Storage hochgeladen und für einige Tage aufbewahrt wird. Er wird auch für jeden verfügbar sein, der den Link hat, ohne dass eine Authentifizierung erforderlich ist. Wenn Sie mehr Kontrolle darüber haben möchten, wie die Berichte gespeichert werden, lesen Sie die Dokumentation.

An diesem Punkt sollten Sie bereit sein, das Lighthouse CI-Tool auszuführen. Verwenden Sie den folgenden Befehl, um die CLI zu starten. Er führt Lighthouse dreimal gegen die angegebenen URLs aus (sofern nicht über die Option numberOfRuns geändert) und lädt das Medianergebnis auf das konfigurierte Ziel hoch.

lhci autorun

Die Ausgabe sollte der unten gezeigten ähneln

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

Started a web server on port 52195...
Running Lighthouse 3 time(s) on https://:52195/web-development-with-go/
Run #1...done.
Run #2...done.
Run #3...done.
Running Lighthouse 3 time(s) on https://:52195/custom-html5-video/
Run #1...done.
Run #2...done.
Run #3...done.
Done running Lighthouse!

Uploading median LHR of https://:52195/web-development-with-go/...success!
Open the report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1606403407045-45763.report.html
Uploading median LHR of https://:52195/custom-html5-video/...success!
Open the report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1606403400243-5952.report.html
Saving URL map for GitHub repository ayoisaiah/freshman...success!
No GitHub token set, skipping GitHub status check.

Done running autorun.

Die Meldung zum GitHub-Token kann vorerst ignoriert werden. Wir werden sie konfigurieren, wenn es an der Zeit ist, Lighthouse CI mit einem GitHub-Action einzurichten. Sie können den Lighthouse-Berichtslink in Ihrem Browser öffnen, um die mittleren Testergebnisse für jede URL anzuzeigen.

Assertionen konfigurieren

Die Verwendung des Lighthouse CI-Tools zum Ausführen und Sammeln von Lighthouse-Berichten funktioniert gut genug, aber wir können noch einen Schritt weiter gehen und das Tool so konfigurieren, dass ein Build fehlschlägt, wenn die Testergebnisse bestimmten Kriterien nicht entsprechen. Die Optionen, die dieses Verhalten steuern, können über die assert-Eigenschaft konfiguriert werden. Hier ist ein Ausschnitt, der eine Beispielkonfiguration zeigt.

// lighthouserc.js
module.exports = {
  ci: {
    assert: {
      preset: 'lighthouse:no-pwa',
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }],
        'categories:accessibility': ['warn', { minScore: 0.9 }],
      },
    },
  },
};

Die Option preset ist eine schnelle Möglichkeit, Lighthouse-Assertionen zu konfigurieren. Es gibt drei Optionen:

• lighthouse:all: Stellt sicher, dass jede Prüfung eine perfekte Punktzahl erhalten hat.
• lighthouse:recommended: Stellt sicher, dass jede Prüfung außer der Leistung eine perfekte Punktzahl erhalten hat, und gibt eine Warnung aus, wenn Metrikwerte unter einer Punktzahl von 90 fallen.
• lighthouse:no-pwa: Dasselbe wie lighthouse:recommended, aber ohne die PWA-Prüfungen.

Sie können das Objekt assertions verwenden, um Presets zu überschreiben oder zu erweitern, oder um ein benutzerdefiniertes Set von Assertionen von Grund auf neu zu erstellen. Die obige Konfiguration besagt eine Basispunktzahl von 90 für die Kategorien performance und accessibility. Der Unterschied besteht darin, dass ein Fehler in der ersteren zu einem ungleich Null-Exit-Code führt, während der letztere dies nicht tut. Das Ergebnis jeder Prüfung in Lighthouse kann assertiert werden, sodass hier viel möglich ist. Konsultieren Sie die Dokumentation, um alle verfügbaren Optionen zu entdecken.

Sie können Assertionen auch gegen eine budget.json-Datei konfigurieren. Diese kann manuell erstellt oder über performancebudget.io generiert werden. Sobald Sie Ihre Datei haben, übergeben Sie sie dem assert-Objekt, wie unten gezeigt.

// lighthouserc.js
module.exports = {
  ci: {
    collect: {
      staticDistDir: './public',
      url: ['/'],
    },
    assert: {
      budgetFile: './budget.json',
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
};

Lighthouse CI mit GitHub Actions ausführen

Eine nützliche Methode, Lighthouse CI in Ihren Entwicklungs-Workflow zu integrieren, ist die Generierung neuer Berichte für jeden Commit oder Pull-Request zum GitHub-Repository des Projekts. Hier kommen GitHub Actions ins Spiel.

Um es einzurichten, müssen Sie ein Verzeichnis .github/workflow im Stammverzeichnis Ihres Projekts erstellen. Hier werden alle Workflows für Ihr Projekt platziert. Wenn Sie neu bei GitHub Actions sind, können Sie sich einen Workflow als eine Sammlung von einer oder mehreren Aktionen vorstellen, die ausgeführt werden, sobald ein Ereignis ausgelöst wird (z. B. wenn ein neuer Pull-Request an das Repo gesendet wird). Sarah Drasner hat eine gute Einführung in die Verwendung von GitHub Actions.

mkdir -p .github/workflow

Erstellen Sie als Nächstes eine YAML-Datei im Verzeichnis .github/workflow. Sie können sie beliebig benennen, solange sie mit der Endung .yml oder .yaml abschließt. Diese Datei wird die Workflow-Konfiguration für Lighthouse CI enthalten.

cd .github/workflow
touch lighthouse-ci.yaml

Der Inhalt der Datei lighthouse-ci.yaml variiert je nach Projekttyp. Ich werde beschreiben, wie ich sie für meine Hugo-Website eingerichtet habe, damit Sie sie für andere Projekttypen anpassen können. Hier ist meine vollständige Konfigurationsdatei:

# .github/workflow/lighthouse-ci.yaml
name: Lighthouse
on: [push]
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
        with:
          token: ${{ secrets.PAT }}
          submodules: recursive

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "0.76.5"
          extended: true

      - name: Build site
        run: hugo

      - name: Use Node.js 15.x
        uses: actions/setup-node@v2
        with:
          node-version: 15.x
      - name: Run the Lighthouse CI
        run: |
          npm install -g @lhci/[email protected]
          lhci autorun

Die obige Konfiguration erstellt einen Workflow namens Lighthouse, der aus einem einzigen Job (ci) besteht, der auf einer Ubuntu-Instanz ausgeführt wird und ausgelöst wird, wenn Code in einen beliebigen Branch des Repositorys gepusht wird. Der Job besteht aus den folgenden Schritten:

• Checkout des Repositorys, gegen das Lighthouse CI ausgeführt werden soll. Hugo verwendet Submodule für seine Themes, daher ist es notwendig, sicherzustellen, dass alle Submodule im Repo ausgecheckt werden. Wenn ein Submodul in einem privaten Repository liegt, müssen Sie ein neues Personal Access Token mit der aktivierten repo-Berechtigung erstellen und es dann als Repository-Geheimnis unter https://github.com/<username>/<repo>/settings/secret hinzufügen. Ohne dieses Token schlägt dieser Schritt fehl, wenn er auf ein privates Repository stößt.

• Installieren Sie Hugo auf der GitHub Action virtuellen Maschine, damit es zum Erstellen der Website verwendet werden kann. Diese Hugo Setup Action ist die, die ich hier verwendet habe. Weitere Setup-Aktionen finden Sie im GitHub Actions Marketplace.
• Erstellen Sie die Website in einem public-Ordner über den Befehl hugo.
• Installieren und konfigurieren Sie Node.js auf der virtuellen Maschine über die setup-node Action.
• Installieren Sie das Lighthouse CI-Tool und führen Sie den Befehl lhci autorun aus.

Nachdem Sie die Konfigurationsdatei eingerichtet haben, können Sie die Änderungen an Ihrem GitHub-Repository committen und pushen. Dies löst den gerade hinzugefügten Workflow aus, vorausgesetzt, Ihre Konfiguration wurde korrekt eingerichtet. Gehen Sie zum Tab „Actions“ im Projekt-Repository, um den Status des Workflows unter Ihrem letzten Commit zu sehen.

Wenn Sie darauf klicken und den Job ci erweitern, sehen Sie die Protokolle für jeden Schritt im Job. In meinem Fall lief alles erfolgreich, aber meine Assertionen schlugen fehl – daher der Fehlerstatus. Genau wie beim lokalen Testen werden die Ergebnisse in den temporären öffentlichen Speicher hochgeladen und Sie können sie anzeigen, indem Sie auf den entsprechenden Link in den Protokollen klicken.

GitHub Status-Checks einrichten

Derzeit ist Lighthouse CI so konfiguriert, dass es ausgeführt wird, sobald Code in das Repo gepusht wird, sei es direkt in einen Branch oder über einen Pull-Request. Der Status des Tests wird auf der Commit-Seite angezeigt, aber Sie müssen darauf klicken und die Protokolle erweitern, um die vollständigen Details anzuzeigen, einschließlich der Links zum Bericht.

Sie können einen GitHub Status-Check einrichten, damit Build-Berichte direkt im Pull-Request angezeigt werden. Um dies einzurichten, gehen Sie zur Lighthouse CI GitHub App-Seite, klicken Sie auf die Option „Configure“ und installieren und autorisieren Sie sie dann für Ihr GitHub-Konto oder die Organisation, der das GitHub-Repository gehört, das Sie verwenden möchten. Kopieren Sie als Nächstes den App-Token, der auf der Bestätigungsseite angezeigt wird, und fügen Sie ihn Ihren Repository-Geheimnissen hinzu, wobei das Feld mit dem Namen LHCI_GITHUB_APP_TOKEN gesetzt ist.

Der Status-Check ist nun einsatzbereit. Sie können ihn testen, indem Sie einen neuen Pull-Request öffnen oder einen Commit zu einem bereits bestehenden Pull-Request pushen.

Historische Berichte und Vergleiche über den Lighthouse CI Server

Die Verwendung des temporären öffentlichen Speicherplatzes zum Speichern von Lighthouse-Berichten ist eine großartige Möglichkeit, um loszulegen, aber sie reicht nicht aus, wenn Sie Ihre Daten privat oder länger aufbewahren möchten. Hier hilft der Lighthouse CI Server. Er bietet ein Dashboard zur Erkundung historischer Lighthouse-Daten und eine großartige Vergleichs-UI, um Unterschiede zwischen Builds aufzudecken.

Um den Lighthouse CI Server zu nutzen, müssen Sie ihn auf Ihrer eigenen Infrastruktur bereitstellen. Detaillierte Anleitungen und Rezepte für die Bereitstellung auf Heroku und Docker finden Sie auf GitHub.

Fazit

Beim Einrichten Ihrer Konfiguration ist es ratsam, einige verschiedene URLs einzuschließen, um eine gute Testabdeckung zu gewährleisten. Für einen typischen Blog möchten Sie auf jeden Fall die Homepage, einen oder zwei Beiträge, die repräsentativ für die Art des Inhalts auf der Website sind, und alle anderen wichtigen Seiten einschließen.

Obwohl wir nicht den vollen Umfang dessen abgedeckt haben, was das Lighthouse CI Tool leisten kann, hoffe ich, dass dieser Artikel Ihnen nicht nur den Einstieg erleichtert, sondern Ihnen auch eine gute Vorstellung davon gibt, was es noch tun kann. Danke fürs Lesen und viel Spaß beim Codieren!