Come aggiungere Lighthouse a un sistema di integrazione continua, come GitHub Actions.
Lighthouse CI è una suite di strumenti per l'utilizzo di Lighthouse durante l'integrazione continua. Lighthouse CI può essere incorporato nei flussi di lavoro degli sviluppatori in molti modi diversi. Questa guida tratta i seguenti argomenti:
- Utilizzando l'interfaccia a riga di comando di Lighthouse CI.
- Configurare il provider CI per l'esecuzione di Lighthouse CI.
- Configurazione di un'azione GitHub e di un controllo dello stato per Lighthouse CI. In questo modo, i risultati di Lighthouse verranno visualizzati automaticamente nelle richieste di pull di GitHub.
- Creazione di una dashboard sul rendimento e di un datastore per i report Lighthouse.
Panoramica
Lighthouse CI è una suite di strumenti senza costi che semplificano l'utilizzo di Lighthouse per il monitoraggio delle prestazioni. Un singolo report Lighthouse fornisce uno snapshot delle prestazioni di una pagina web al momento dell'esecuzione; Lighthouse CI mostra come questi risultati sono cambiati nel tempo. Questo può essere utilizzato per identificare l'impatto di particolari modifiche al codice o per garantire che le soglie di prestazioni siano soddisfatte durante i processi di integrazione continua. Sebbene il monitoraggio delle prestazioni sia il caso d'uso più comune per Lighthouse CI, può essere utilizzato per monitorare altri aspetti del report di Lighthouse, ad esempio la SEO o l'accessibilità.
La funzionalità di base di Lighthouse CI è fornita dall'interfaccia a riga di comando di Lighthouse CI. (Nota: si tratta di uno strumento diverso dall'interfaccia a riga di comando di Lighthouse.) L'interfaccia a riga di comando di Lighthouse CI fornisce un insieme di comandi per l'utilizzo di Lighthouse CI. Ad esempio, il comando autorun esegue più esecuzioni di Lighthouse, identifica il report Lighthouse mediano e lo carica per l'archiviazione. Questo comportamento può essere ampiamente personalizzato passando flag aggiuntivi o personalizzando il file di configurazione di Lighthouse CI, lighthouserc.js.
Sebbene la funzionalità di base di Lighthouse CI sia principalmente incapsulata nell'interfaccia a riga di comando di Lighthouse CI, Lighthouse CI viene in genere utilizzato tramite uno dei seguenti approcci:
- Esecuzione di Lighthouse CI nell'ambito dell'integrazione continua
- Utilizzo di un'azione GitHub di Lighthouse CI che viene eseguita e commenta ogni richiesta di pull
- Monitoraggio del rendimento nel tempo tramite la dashboard fornita da Lighthouse Server.
Tutti questi approcci si basano sull'interfaccia a riga di comando di Lighthouse CI.
Le alternative a Lighthouse CI includono servizi di monitoraggio delle prestazioni di terze parti o la scrittura di uno script personalizzato per raccogliere i dati sul rendimento durante il processo di CI. Ti consigliamo di utilizzare un servizio di terze parti se preferisci che qualcun altro gestisca il server di monitoraggio delle prestazioni e i dispositivi di test o se vuoi funzionalità di notifica (come l'integrazione con email o Slack) senza dover creare queste funzionalità in autonomia.
Utilizza Lighthouse CI localmente
Questa sezione spiega come eseguire e installare l'interfaccia a riga di comando di Lighthouse CI localmente e come configurare lighthouserc.js. L'esecuzione locale della CLI di Lighthouse CI è il modo più semplice per assicurarti che lighthouserc.js sia configurato correttamente.
Installa l'interfaccia a riga di comando di Lighthouse CI.
npm install -g @lhci/cliLighthouse CI viene configurato inserendo un file
lighthouserc.jsnella directory principale del repository del progetto. Questo file è obbligatorio e conterrà le informazioni di configurazione relative a Lighthouse CI. Sebbene Lighthouse CI possa essere configurato per essere utilizzato senza un repository Git, le istruzioni riportate in questo articolo presuppongono che il repository del progetto sia configurato per l'utilizzo di Git.Nella directory principale del repository, crea un file di configurazione
lighthouserc.js.touch lighthouserc.jsAggiungi il codice seguente a
lighthouserc.js. Questo codice è una configurazione Lighthouse CI vuota. Aggiungerai elementi a questa configurazione nei passaggi successivi.module.exports = { ci: { collect: { /* Add configuration here */ }, upload: { /* Add configuration here */ }, }, };Ogni volta che viene eseguito, Lighthouse CI avvia un server per pubblicare il tuo sito. Questo server consente a Lighthouse di caricare il tuo sito anche quando non sono in esecuzione altri server. Al termine dell'esecuzione di Lighthouse CI, il server verrà arrestato automaticamente. Per assicurarti che la pubblicazione funzioni correttamente, devi configurare le proprietà
staticDistDirostartServerCommand.Se il tuo sito è statico, aggiungi la proprietà
staticDistDirall'oggettoci.collectper indicare dove si trovano i file statici. Lighthouse CI utilizzerà il proprio server per pubblicare questi file durante il test del tuo sito. Se il tuo sito non è statico, aggiungi la proprietàstartServerCommandall'oggettoci.collectper indicare il comando che avvia il server. Lighthouse CI avvierà un nuovo processo del server durante i test e lo arresterà al termine.// Static site example collect: { staticDistDir: './public', }// Dynamic site example collect: { startServerCommand: 'npm run start', }Aggiungi la proprietà
urlall'oggettoci.collectper indicare gli URL su cui Lighthouse CI deve eseguire Lighthouse. Il valore della proprietàurldeve essere fornito come un array di URL; questo array può contenere uno o più URL. Per impostazione predefinita, Lighthouse CI eseguirà Lighthouse tre volte per ogni URL.collect: { // ... url: ['http://localhost:8080'] }Aggiungi la proprietà
targetall'oggettoci.uploade imposta il valore su'temporary-public-storage'. I report Lighthouse raccolti da Lighthouse CI verranno caricati in uno spazio di archiviazione pubblico temporaneo. Il report rimarrà lì per sette giorni, dopodiché verrà eliminato automaticamente. Questa guida alla configurazione utilizza l'opzione di caricamento "Spazio di archiviazione pubblico temporaneo" perché è rapida da configurare. Per informazioni su altri modi per archiviare i report di Lighthouse, consulta la documentazione.upload: { target: 'temporary-public-storage', }La posizione di archiviazione del report sarà simile alla seguente:
https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1580152437799-46441.report.html(Questo URL non funzionerà perché la segnalazione è già stata eliminata).
Esegui l'interfaccia a riga di comando di Lighthouse CI dal terminale utilizzando il comando
autorun. In questo modo, Lighthouse verrà eseguito tre volte e verrà caricato il report Lighthouse mediano.lhci autorunSe hai configurato correttamente Lighthouse CI, l'esecuzione di questo comando dovrebbe produrre un output simile al seguente:
✅ .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.Puoi ignorare il messaggio
GitHub token not setnell'output della console. Un token GitHub è necessario solo se vuoi utilizzare Lighthouse CI con un'azione GitHub. La configurazione di un'azione GitHub viene spiegata più avanti in questo articolo.Se fai clic sul link nell'output che inizia con
https://storage.googleapis.com..., verrà visualizzato il report di Lighthouse corrispondente all'esecuzione mediana di Lighthouse.I valori predefiniti utilizzati da
autorunpossono essere sostituiti tramite la riga di comando olighthouserc.js. Ad esempio, la configurazionelighthouserc.jsdi seguito indica che devono essere raccolte cinque esecuzioni di Lighthouse ogni volta che viene eseguitoautorun.Aggiorna
lighthouserc.jsper utilizzare la proprietànumberOfRuns:module.exports = { // ... collect: { numberOfRuns: 5 }, // ... }, };Esegui di nuovo il comando
autorun:lhci autorunL'output del terminale dovrebbe mostrare che Lighthouse è stato eseguito cinque volte anziché le tre predefinite:
✅ .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.Per scoprire altre opzioni di configurazione, consulta la documentazione di configurazione di Lighthouse CI.
Configura il processo CI per eseguire Lighthouse CI
Lighthouse CI può essere utilizzato con il tuo strumento di CI preferito. La sezione Configura il tuo provider CI della documentazione di Lighthouse CI contiene esempi di codice che mostrano come incorporare Lighthouse CI nei file di configurazione degli strumenti CI più comuni. In particolare, questi esempi di codice mostrano come eseguire Lighthouse CI per raccogliere misurazioni delle prestazioni durante il processo di CI.
L'utilizzo di Lighthouse CI per raccogliere le misurazioni delle prestazioni è un buon punto di partenza per il monitoraggio delle prestazioni. Tuttavia, gli utenti avanzati potrebbero voler fare un ulteriore passo avanti e utilizzare Lighthouse CI per interrompere le build se non soddisfano criteri predefiniti, come il superamento di determinati controlli di Lighthouse o il rispetto di tutti i budget delle prestazioni. Questo comportamento viene configurato tramite la proprietà assert del file lighthouserc.js.
Lighthouse CI supporta tre livelli di asserzioni:
off: ignora le asserzioniwarn: stampa gli errori in stderrerror: stampa gli errori in stderr ed esce da Lighthouse CI con un codice di uscita diverso da zero
Di seguito è riportato un esempio di configurazione lighthouserc.js che include
asserzioni. Imposta le asserzioni per i punteggi delle categorie di prestazioni e accessibilità di Lighthouse. Per provarlo, aggiungi le asserzioni mostrate di seguito al file lighthouserc.js, quindi esegui nuovamente Lighthouse CI.
module.exports = {
ci: {
collect: {
// ...
},
assert: {
assertions: {
'categories:performance': ['warn', {minScore: 1}],
'categories:accessibility': ['error', {minScore: 1}]
}
},
upload: {
// ...
},
},
};
L'output della console generato è simile al seguente:
Per saperne di più sulle asserzioni di Lighthouse CI, consulta la documentazione.
Configura un'azione GitHub per eseguire Lighthouse CI
È possibile utilizzare un'azione GitHub per eseguire Lighthouse CI. In questo modo, verrà generato un nuovo report Lighthouse ogni volta che viene eseguito il push di una modifica al codice in qualsiasi ramo di un repository GitHub. Utilizza questa opzione insieme a un controllo dello stato per visualizzare questi risultati in ogni richiesta di pull.
Nella directory root del repository, crea una directory denominata
.github/workflows. I workflow del tuo progetto verranno inseriti in questa directory. Un workflow è un processo che viene eseguito in un momento predeterminato (ad esempio, quando viene eseguito il push del codice) ed è composto da una o più azioni.mkdir .github mkdir .github/workflowsIn
.github/workflowscrea un file denominatolighthouse-ci.yaml. Questo file conterrà la configurazione di un nuovo workflow.touch lighthouse-ci.yamlAggiungi il testo seguente a
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!"Questa configurazione imposta un workflow composto da un singolo job che verrà eseguito ogni volta che viene eseguito il push di un nuovo codice nel repository. Questo job prevede quattro passaggi:
- Controlla il repository su cui verrà eseguito Lighthouse CI
- Installa e configura Node
- Installa i pacchetti npm richiesti
- Esegui Lighthouse CI e carica i risultati in uno spazio di archiviazione pubblico temporaneo.
Esegui il commit di queste modifiche e inviale a GitHub. Se hai seguito correttamente i passaggi precedenti, il push del codice su GitHub attiverà l'esecuzione del workflow che hai appena aggiunto.
Per confermare che Lighthouse CI è stato attivato e visualizzare il report generato, vai alla scheda Actions (Azioni) del progetto. Dovresti vedere il flusso di lavoro Build project and Run Lighthouse CI elencato sotto il commit più recente.
Puoi accedere al report di Lighthouse corrispondente a un determinato commit dalla scheda Azioni. Fai clic sul commit, poi sul passaggio del workflow Lighthouse CI, quindi espandi i risultati del passaggio Esegui Lighthouse CI.
Hai appena configurato un'azione GitHub per eseguire Lighthouse CI. Questo è particolarmente utile se utilizzato insieme a un controllo dello stato di GitHub.
Configura un controllo dello stato di GitHub
Un controllo dello stato, se configurato, è un messaggio che viene visualizzato su ogni PR e in genere include informazioni come i risultati di un test o l'esito positivo di una build.
I passaggi riportati di seguito spiegano come configurare un controllo dello stato per Lighthouse CI.
Vai alla pagina dell'app GitHub Lighthouse CI e fai clic su Configura.
(Facoltativo) Se fai parte di più organizzazioni su GitHub, scegli l'organizzazione proprietaria del repository per cui vuoi utilizzare Lighthouse CI.
Seleziona Tutti i repository se vuoi attivare Lighthouse CI in tutti i repository o seleziona Solo repository selezionati se vuoi utilizzarlo solo in repository specifici, quindi seleziona i repository. Poi fai clic su Installa e autorizza.
Copia il token visualizzato. Lo utilizzerai nel prossimo passaggio.
Per aggiungere il token, vai alla pagina Impostazioni del tuo repository GitHub, fai clic su Secret, quindi su Aggiungi un nuovo secret.
Imposta il campo Nome su
LHCI_GITHUB_APP_TOKENe il campo Valore sul token che hai copiato nell'ultimo passaggio, quindi fai clic sul pulsante Aggiungi secret.Vai al file
lighthouse-ci.yamle aggiungi il nuovo secret dell'ambiente al comando "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: $
- Il controllo dello stato è pronto per l'uso. Per testarlo, crea una nuova richiesta di pull o esegui il push di un commit in una richiesta di pull esistente.
Configura il server Lighthouse CI
Il server Lighthouse CI fornisce una dashboard per esplorare i report Lighthouse storici. Può anche fungere da datastore privato a lungo termine per i report di Lighthouse.
- Scegli i commit da confrontare.
- La variazione del punteggio Lighthouse tra i due commit.
- Questa sezione mostra solo le metriche che sono cambiate tra i due commit.
- Le regressioni sono evidenziate in rosa.
- I miglioramenti sono evidenziati in blu.
Il server Lighthouse CI è più adatto agli utenti che hanno dimestichezza con il deployment e la gestione della propria infrastruttura.
Per informazioni sulla configurazione del server Lighthouse CI, incluse le formule per l'utilizzo di Heroku e Docker per il deployment, consulta queste istruzioni.