Come aggiungere Lighthouse a un sistema di integrazione continua, come GitHub Actions.
Lighthouse CI è una suite di strumenti per utilizzare 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:
- Utilizzo dell'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 datastore per i report Lighthouse.
Panoramica
Lighthouse CI è una suite di strumenti gratuiti 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. Sebbene il monitoraggio delle prestazioni sia il caso d'uso più comune per Lighthouse CI, può essere utilizzato per monitorare altri aspetti del report Lighthouse, ad esempio, SEO o 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 la gestione del server di monitoraggio delle prestazioni e dei dispositivi di test oppure se vuoi utilizzare funzionalità di notifica (come l'integrazione di email o Slack) senza dover creare personalmente queste funzionalità.
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/cliLighthouse CI viene configurato inserendo un file
lighthouserc.jsnella directory principale del repo 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.jsfile di configurazione.touch lighthouserc.jsAggiungi 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à
staticDistDirostartServerCommand.Se il tuo sito è statico, aggiungi la proprietà
staticDistDirall'oggettoci.collectper 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àstartServerCommandall'oggettoci.collectper 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à
urlall'oggettoci.collectper indicare gli URL su cui Lighthouse CI deve eseguire Lighthouse. Il valore della proprietàurldeve essere fornito come array di URL; questa 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.htmlQuesto 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 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 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..., si aprirà il report Lighthouse corrispondente alla corsa media di Lighthouse.I valori predefiniti utilizzati da
autorunpossono essere sostituiti tramite la riga di comando olighthouserc.js. Ad esempio, la configurazionelighthouserc.jsriportata di seguito indica che è necessario raccogliere cinque esecuzioni di Lighthouse ogni volta che vengono eseguiteautorun.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é 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 saperne di più sulle altre opzioni di configurazione, consulta la documentazione di configurazione di CI di Lighthouse.
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 le asserzioni per i punteggi delle categorie di prestazioni
e accessibilità di Lighthouse. Per fare una prova, aggiungi le asserzioni mostrate di seguito al tuo 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 è il seguente:
Per saperne di più sulle asserzioni di Lighthouse CI, consulta la documentazione.
Configura un'azione GitHub per eseguire CI di Lighthouse
È possibile utilizzare un'azione GitHub per eseguire CI con Lighthouse. 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 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 è 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 flusso di lavoro.touch lighthouse-ci.yamlAggiungi 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:
- Controlla il repository su cui verrà eseguita la CI di Lighthouse
- 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 a 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 CI di Lighthouse. Questa operazione sarà più utile se utilizzata insieme a 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 Secrets e poi su Aggiungi un nuovo secret.
Imposta il campo Name (Nome) su
LHCI_GITHUB_APP_TOKENe imposta il campo Value (Valore) sul token che hai copiato nell'ultimo passaggio, quindi fai clic sul pulsante Add secret (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 testarla, crea una nuova richiesta di pull o esegui il push di un commit a una richiesta di pull esistente.
Configurare il server CI Lighthouse
Il server CI Lighthouse 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 preferiscono 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.