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 incorporato nei flussi di lavoro degli sviluppatori in molti modi diversi. Questa guida tratta i seguenti argomenti:
- Utilizzo dell'interfaccia a riga di comando CI di Lighthouse.
- Configurazione del provider CI per l'esecuzione di Lighthouse CI.
- Configurazione di un'azione GitHub e di un controllo dello stato per Lighthouse CI. Verranno visualizzati automaticamente i risultati di Lighthouse nelle richieste di pull di GitHub.
- Creazione di una dashboard sulle prestazioni e di un datastore per i report Lighthouse.
Panoramica
Lighthouse CI è una suite di strumenti senza costi che facilita l'utilizzo di Lighthouse per il monitoraggio delle prestazioni. Un singolo report Lighthouse fornisce un'istantanea delle prestazioni di una pagina web al momento dell'esecuzione; Lighthouse CI mostra come questi risultati sono cambiati nel tempo. Può essere utilizzato per identificare l'impatto di specifiche modifiche al codice o 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 la SEO o l'accessibilità.
La funzionalità di base di Lighthouse CI è fornita dall'interfaccia a riga di comando di Lighthouse CI. Nota: questo è uno strumento separato dall'interfaccia a riga di comando di Lighthouse. L'interfaccia a riga di comando CI di Lighthouse fornisce un set di comandi per l'utilizzo di Lighthouse CI. Ad esempio, il comando autorun esegue più esecuzioni di Lighthouse, identifica il report Lighthouse mediano e carica il report per l'archiviazione. Questo comportamento può essere notevolmente personalizzato passando ulteriori flag
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, Lighthouse CI viene in genere utilizzato tramite uno dei seguenti approcci:
- Esecuzione di Lighthouse CI nell'ambito dell'integrazione continua
- usando un'azione GitHub CI Lighthouse che viene eseguita e commenta ogni richiesta di pull
- Monitorare le prestazioni nel tempo tramite la dashboard fornita da Lighthouse Server.
Tutti questi approcci sono basati sull'interfaccia a riga di comando CI di Lighthouse.
Le alternative a Lighthouse CI includono servizi di monitoraggio delle prestazioni di terze parti o la scrittura di un proprio script per raccogliere dati sulle prestazioni durante il processo di CI. Considera l'utilizzo di un servizio di terze parti se preferisci lasciare che sia qualcun altro a gestire la gestione del tuo server di monitoraggio delle prestazioni e dei dispositivi di test oppure se vuoi funzionalità di notifica (come l'integrazione di email o Slack) senza dover creare personalmente queste funzionalità.
Utilizza Lighthouse CI localmente
Questa sezione spiega come eseguire e installare l'interfaccia a riga di comando CI di Lighthouse in locale e come configurare lighthouserc.js. L'esecuzione dell'interfaccia a riga di comando CI di Lighthouse in locale è il modo più semplice per verificare che lighthouserc.js sia configurato correttamente.
Installa l'interfaccia a riga di comando CI di Lighthouse.
npm install -g @lhci/cliLighthouse CI viene configurato inserendo un file
lighthouserc.jsnella directory principale del repository del progetto. Questo file è obbligatorio e conterrà informazioni di configurazione relative a Lighthouse CI. Sebbene Lighthouse CI possa essere configurato per l'utilizzo senza un repository Git, le istruzioni in questo articolo presuppongono che il repository del progetto sia configurato per l'utilizzo di Git.Nella directory radice del repository, crea un file di configurazione
lighthouserc.js.touch lighthouserc.jsAggiungi il seguente codice a
lighthouserc.js. Questo codice è una configurazione Lighthouse CI vuota. Aggiungerai a questa configurazione nei passaggi successivi.module.exports = { ci: { collect: { /* Add configuration here */ }, upload: { /* Add configuration here */ }, }, };Ogni volta che Lighthouse CI viene eseguito, avvia un server per la pubblicazione del sito. È questo server che 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 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 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 il test e lo chiuderà in seguito.// 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 sotto forma di array di URL. Questo array può contenere uno o più URL. Per impostazione predefinita, Lighthouse CI eseguirà Lighthouse tre volte su 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à in questa pagina per sette giorni, dopodiché verrà eliminato automaticamente. Questa guida alla configurazione utilizza l'opzione di caricamento "archiviazione pubblica temporanea" perché è veloce da configurare. Per informazioni su altri modi di archiviare i report Lighthouse, consulta la documentazione.upload: { target: 'temporary-public-storage', }La posizione di archiviazione del report sarà simile a questa:
https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1580152437799-46441.report.html(Questo URL non funziona perché il report è già stato eliminato.)
Esegui l'interfaccia a riga di comando CI di Lighthouse dal terminale utilizzando il comando
autorun. Verrà eseguito Lighthouse per 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 a questo:
✅ .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 viene descritta più avanti in questo articolo.Se fai clic sul link nell'output che inizia con
https://storage.googleapis.com..., visualizzerai il report Lighthouse corrispondente all'esecuzione mediana di Lighthouse.È possibile eseguire l'override dei valori predefiniti utilizzati da
autoruntramite la riga di comando olighthouserc.js. Ad esempio, la configurazionelighthouserc.jsriportata di seguito indica che devono essere raccolte cinque esecuzioni di Lighthouse ogni volta che vengono eseguiteautorun.Aggiorna
lighthouserc.jsper utilizzare la proprietànumberOfRuns:module.exports = { // ... collect: { numberOfRuns: 5 }, // ... }, };Esegui nuovamente il comando
autorun:lhci autorunL'output del terminale dovrebbe indicare 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 di più sulle altre opzioni di configurazione, consulta la documentazione sulla configurazione dell'CI di Lighthouse.
Configura il processo di CI per eseguire Lighthouse CI
Lighthouse CI può essere utilizzato con il tuo strumento 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 comuni. In particolare, questi esempi di codice mostrano come eseguire Lighthouse CI per raccogliere le 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 passo avanti e utilizzare Lighthouse CI per non riuscire le build se non soddisfano criteri predefiniti, come il superamento di determinati controlli 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: errori di stampa in stderrerror: errori di stampa in stderr e uscita 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 affermazioni per i punteggi delle
categorie di prestazioni e accessibilità di Lighthouse. Per provare questa funzionalità, 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 che genera è simile al seguente:
Per ulteriori informazioni sulle asserzioni Lighthouse CI, consulta la documentazione.
Configura un'azione GitHub per eseguire Lighthouse CI
È possibile usare 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 a qualsiasi ramo di un repository GitHub. Da utilizzare in combinazione con un controllo dello stato per visualizzare questi risultati in ogni richiesta di pull.
Nella directory radice del repository, crea una directory denominata
.github/workflows. I flussi di lavoro per il 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/workflowsCrea un file denominato
lighthouse-ci.yamlin.github/workflows. Questo file conserverà la configurazione per 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:
- Dai un'occhiata al repository su cui verrà eseguita Lighthouse CI
- Installa e configura il nodo
- 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 ed eseguine il push su GitHub. Se hai seguito correttamente i passaggi precedenti, il push del codice in GitHub attiverà l'esecuzione del flusso di lavoro appena aggiunto.
Per confermare l'attivazione di Lighthouse CI e visualizzare il report generato, vai alla scheda Azioni del tuo progetto. Dovresti vedere il flusso di lavoro Crea progetto ed esegui Lighthouse CI elencato sotto il commit più recente.
Puoi accedere al report Lighthouse corrispondente a un determinato commit dalla scheda Azioni. Fai clic sul commit, fai clic sul passaggio del flusso di lavoro Lighthouse CI, quindi espandi i risultati del passaggio Esegui Lighthouse CI.
Hai appena configurato un'azione GitHub per eseguire Lighthouse CI. Questa opzione sarà particolarmente utile se utilizzata insieme a un controllo dello stato GitHub.
Configura un controllo dello stato GitHub
Un controllo dello stato, se configurato, è un messaggio che viene visualizzato su ogni PR e che 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 CI di Lighthouse 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 abilitare CI Lighthouse in tutti i repository oppure seleziona Seleziona solo repository se vuoi utilizzarlo solo in repository specifici, quindi seleziona i repository. Quindi, fai clic su Installa e autorizza.
Copia il token visualizzato. Lo utilizzerai nel passaggio successivo.
Per aggiungere il token, vai alla pagina Impostazioni del repository GitHub, fai clic su Secret, quindi fai clic su Aggiungi un nuovo secret.
Imposta il campo Nome su
LHCI_GITHUB_APP_TOKEN, imposta 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 di 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 CI Lighthouse
Il server Lighthouse CI fornisce una dashboard per esplorare i report storici di Lighthouse. Può anche fungere da datastore privato a lungo termine per i report Lighthouse.
- Scegli gli impegni da confrontare.
- L'importo del punteggio Lighthouse è cambiato tra i due commit.
- In questa sezione vengono mostrate 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 sanno eseguire il deployment e gestire la propria infrastruttura.
Per informazioni sulla configurazione del server CI Lighthouse, incluse le formule per l'utilizzo di Heroku e Docker per il deployment, consulta queste instructions.