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 integrato nei flussi di lavoro degli sviluppatori in molti modi diversi. Questa guida tratta i seguenti argomenti:
- Utilizzando l'interfaccia a riga di comando Lighthouse CI.
- Configurare il provider CI per eseguire Lighthouse CI.
- Configurazione di un'azione GitHub e di un controllo 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 data store 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 un'istantanea del rendimento 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 determinate modifiche al codice o per garantire il raggiungimento delle soglie di prestazioni durante i processi di integrazione continua. Anche se il monitoraggio del rendimento è il caso d'uso più comune per la CI di Lighthouse, 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 Lighthouse CI. Nota: si tratta di uno strumento diverso dal Lighthouse CLI. L'interfaccia a riga di comando 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 personalizzato in modo significativo passando flag aggiuntivi o personalizzando il file di configurazione lighthouserc.js
di Lighthouse CI.
Sebbene la funzionalità di base di Lighthouse CI sia incapsulata principalmente nell'interfaccia a riga di comando di Lighthouse CI, Lighthouse CI viene in genere utilizzato tramite uno dei seguenti approcci:
- Eseguire l'integrazione continua di Lighthouse nell'ambito dell'integrazione continua
- Utilizzo di un'azione GitHub Lighthouse CI che esegue e commenta ogni richiesta di pull
- Monitoraggio del rendimento nel tempo tramite la dashboard fornita da Lighthouse Server.
Tutti questi approcci si basano sulla CLI Lighthouse CI.
Le alternative al controllo qualità Lighthouse includono servizi di monitoraggio del rendimento di terze parti o la scrittura di uno script personalizzato per raccogliere i dati sul rendimento durante il processo di controllo qualità. Ti consigliamo di utilizzare un servizio di terze parti se preferisci lasciare che sia qualcun altro a gestire il server di monitoraggio del rendimento e i dispositivi di test oppure se vuoi funzionalità di notifica (come l'integrazione con email o Slack) senza doverle creare autonomamente.
Utilizzare Lighthouse CI localmente
Questa sezione spiega come eseguire e installare Lighthouse CI CLI localmente e come configurare lighthouserc.js
. Eseguire l'interfaccia a riga di comando Lighthouse CI localmente è il modo più semplice per assicurarti che lighthouserc.js
sia configurato correttamente.
Installa l'interfaccia a riga di comando Lighthouse CI.
npm install -g @lhci/cli
Lighthouse CI viene configurato inserendo un file
lighthouserc.js
nella directory principale del repository del progetto. Questo file è obbligatorio e conterrà le informazioni di configurazione relative al Lighthouse CI. Sebbene Lighthouse CI possa essere configurato per essere utilizzato senza un repo git, le istruzioni in questo articolo presuppongono che il repo del progetto sia configurato per l'utilizzo di git.Nella directory principale del repository, crea un
lighthouserc.js
file di configurazione.touch lighthouserc.js
Aggiungi il seguente codice 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, viene avviato 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, Lighthouse CI spegnerà automaticamente il server. Per assicurarti che la pubblicazione funzioni correttamente, devi configurare le proprietà
staticDistDir
ostartServerCommand
.Se il tuo sito è statico, aggiungi la proprietà
staticDistDir
all'oggettoci.collect
per indicare la posizione dei file statici. Lighthouse CI userà il proprio server per pubblicare questi file durante il test del tuo sito. Se il tuo sito non è statico, aggiungi la proprietàstartServerCommand
all'oggettoci.collect
per indicare il comando che avvia il server. Lighthouse CI avvierà una nuova procedura di server durante il test e la chiuderà al termine.// Static site example collect: { staticDistDir: './public', }
// Dynamic site example collect: { startServerCommand: 'npm run start', }
Aggiungi la proprietà
url
all'oggettoci.collect
per indicare gli URL su cui Lighthouse CI deve eseguire Lighthouse. Il valore della proprietàurl
deve essere fornito come 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à
target
all'oggettoci.upload
e 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 funziona perché il report è già stato eliminato.
Esegui la CLI Lighthouse CI dal terminale utilizzando il comando
autorun
. Verrà eseguito Lighthouse tre volte e verrà caricato il report Lighthouse mediano.lhci autorun
Se 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 set
nell'output della console. Un token GitHub è necessario solo se vuoi utilizzare Lighthouse CI con un'azione GitHub. La procedura per configurare un'azione GitHub è spiegata più avanti in questo articolo.Se fai clic sul link nell'output che inizia con
https://storage.googleapis.com...
, verrà visualizzato il report Lighthouse corrispondente alla corsa media di Lighthouse.I valori predefiniti utilizzati da
autorun
possono essere sostituiti tramite la riga di comando olighthouserc.js
. Ad esempio, la configurazionelighthouserc.js
riportata di seguito indica che devono essere raccolte cinque esecuzioni di Lighthouse ogni volta che viene eseguitoautorun
.Aggiorna
lighthouserc.js
per utilizzare la proprietànumberOfRuns
:module.exports = { // ... collect: { numberOfRuns: 5 }, // ... }, };
Esegui di nuovo il comando
autorun
:lhci autorun
L'output del terminale dovrebbe mostrare che Lighthouse è stato eseguito cinque volte anziché tre come per impostazione predefinita:
✅ .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 sulla configurazione di Lighthouse CI.
Configura il processo CI per eseguire Lighthouse CI
Lighthouse CI può essere utilizzato con il tuo strumento CI preferito. La sezione Configura il tuo fornitore CI della documentazione di Lighthouse CI contiene esempi di codice che mostrano come incorporare Lighthouse CI nei file di configurazione degli strumenti CI comuni. Nello specifico, questi esempi di codice mostrano come eseguire Lighthouse CI per raccogliere misurazioni del rendimento durante il processo di CI.
L'utilizzo di Lighthouse CI per raccogliere le misurazioni del rendimento è un buon punto di partenza per il monitoraggio del rendimento. Tuttavia, gli utenti esperti potrebbero voler fare un passo in più e utilizzare Lighthouse CI per interrompere le build se non soddisfano criteri predefiniti, ad esempio superare determinati controlli Lighthouse o soddisfare tutti i budget di rendimento. 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 su stderrerror
: stampa gli errori in stderr ed esci da Lighthouse CI con un codice di uscita diverso da zero
Di seguito è riportato un esempio di configurazione lighthouserc.js
che include assert. Imposta asserzioni per i punteggi delle categorie di rendimento e accessibilità di Lighthouse. Per provare questa funzionalità, aggiungi le asserzioni mostrate di seguito al
tuo file lighthouserc.js
, quindi esegui di nuovo Lighthouse CI.
module.exports = {
ci: {
collect: {
// ...
},
assert: {
assertions: {
'categories:performance': ['warn', {minScore: 1}],
'categories:accessibility': ['error', {minScore: 1}]
}
},
upload: {
// ...
},
},
};
L'output della console generato è il seguente:
Per saperne di più sulle asserzioni di Lighthouse CI, consulta la documentazione.
Configurare un'azione GitHub per eseguire il CI di Lighthouse
Per eseguire Lighthouse CI puoi utilizzare un'azione GitHub. Verrà generato un nuovo report Lighthouse ogni volta che viene eseguito il push di una modifica al codice in un ramo di un repository GitHub. Utilizza questa opzione insieme a un controllo dello stato per visualizzare questi risultati in ogni richiesta pull.
Nella directory principale del repository, crea una directory denominata
.github/workflows
. I workflow per il tuo progetto verranno inseriti in questa directory. Un flusso di lavoro è un processo che viene eseguito in un momento prestabilito (ad esempio quando viene eseguito il push del codice) ed è costituito da una o più azioni.mkdir .github mkdir .github/workflows
In
.github/workflows
crea un file denominatolighthouse-ci.yaml
. Questo file conterrà la configurazione di un nuovo flusso di lavoro.touch lighthouse-ci.yaml
Aggiungi il seguente testo 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 flusso di lavoro costituito da un singolo job che verrà eseguito ogni volta che viene eseguito il push di nuovo codice nel repository. Questo job prevede quattro passaggi:
- Esegui il check-out del repository in 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 flusso di lavoro appena aggiunto.
Per verificare che Lighthouse CI sia stato attivato e visualizzare il report generato, vai alla scheda Azioni del progetto. Dovresti vedere il flusso di lavoro Crea progetto ed esegui CI di Lighthouse elencato sotto il commit più recente.
Puoi accedere al report Lighthouse corrispondente a un determinato commit dalla scheda Azioni. Fai clic sul commit, poi sul passaggio del flusso di lavoro Lighthouse CI ed espandi i risultati del passaggio Esegui Lighthouse CI.
Hai appena configurato un'azione GitHub per eseguire il CI di Lighthouse. Questa operazione sarà più utile se utilizzata in combinazione con un controllo dello stato di GitHub.
Configurare un controllo dello stato di GitHub
Un controllo dello stato, se configurato, è un messaggio che viene visualizzato in ogni PR e solitamente include informazioni come i risultati di un test o l'esito positivo di una compilazione.
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 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 passaggio successivo.
Per aggiungere il token, vai alla pagina Impostazioni del tuo repository GitHub, fai clic su Segreti e poi su Aggiungi un nuovo segreto.
Imposta il campo Nome su
LHCI_GITHUB_APP_TOKEN
e il campo Valore sul token che hai copiato nell'ultimo passaggio, quindi fai clic sul pulsante Aggiungi segreto.Vai al file
lighthouse-ci.yaml
e 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 pull request o esegui push di un commit in una pull request esistente.
Configurare il server CI Lighthouse
Il server Lighthouse CI fornisce una dashboard per esplorare i report Lighthouse storici. Può anche fungere da archivio dati privato a lungo termine per i report Lighthouse.
- Scegli i commit da confrontare.
- L'importo in cui il punteggio Lighthouse è cambiato 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.
Lighthouse CI Server è più adatto agli utenti che si sentono a proprio agio a eseguire il deployment e gestire la propria infrastruttura.
Per informazioni sulla configurazione del server Lighthouse CI, incluse le ricette per l'utilizzo di Heroku e Docker per il deployment, consulta queste istruzioni.