Como adicionar o Lighthouse a um sistema de integração contínua, como o GitHub Actions.
O Lighthouse CI é um pacote de ferramentas para usar o Lighthouse durante a integração contínua. O Lighthouse CI pode ser incorporado nos fluxos de trabalho do desenvolvedor de várias maneiras diferentes. Este guia abrange os seguintes tópicos:
- Como usar a CLI CI do Lighthouse.
- Como configurar o provedor de CI para executar a CI do Lighthouse.
- Como configurar uma ação do GitHub e uma verificação de status para a CI do Lighthouse. Isso exibirá automaticamente os resultados do Lighthouse nas solicitações de envio do GitHub.
- Criação de um painel de desempenho e um repositório de dados para os relatórios do Lighthouse.
Visão geral
O Lighthouse CI é um pacote de ferramentas sem custo financeiro que facilita o uso do Lighthouse para monitorar o desempenho. Um único relatório do Lighthouse fornece um resumo do desempenho de uma página da Web no momento em que ela é executada. O Lighthouse CI mostra como essas descobertas mudaram ao longo do tempo. Isso pode ser usado para identificar o impacto de determinadas mudanças de código ou garantir que os limites de desempenho sejam atendidos durante os processos de integração contínua. Embora o monitoramento de desempenho seja o caso de uso mais comum do Lighthouse CI, ele pode ser usado para monitorar outros aspectos do relatório do Lighthouse, por exemplo, SEO ou acessibilidade.
A funcionalidade principal do Lighthouse CI é fornecida pela interface de linha de comando
do Lighthouse CI. Observação: essa é uma ferramenta separada da CLI
Lighthouse. A
CLI do Lighthouse CI oferece um conjunto de
comandos
para usar o Lighthouse CI. Por exemplo, o comando autorun executa várias
execuções do Lighthouse, identifica o relatório médio do Lighthouse e faz upload dele
para armazenamento. Esse comportamento pode ser altamente personalizado ao transmitir outras flags
ou personalizar o arquivo de configuração do Lighthouse CI, lighthouserc.js.
Embora a funcionalidade principal do Lighthouse CI seja encapsulada principalmente na CLI do Lighthouse CI, o Lighthouse CI normalmente é usado por uma das seguintes abordagens:
- Como executar o Lighthouse CI como parte da integração contínua
- Uso de uma ação do GitHub para CI do Lighthouse que é executada e comenta em todas as solicitações de envio
- Rastreamento do desempenho ao longo do tempo por meio do painel fornecido pelo servidor do Lighthouse.
Todas essas abordagens são baseadas na CLI do Lighthouse CI.
As alternativas ao Lighthouse CI incluem serviços de monitoramento de desempenho de terceiros ou escrever seu próprio script para coletar dados de desempenho durante o processo de CI. Considere usar um serviço de terceiros se preferir deixar outra pessoa cuidar do gerenciamento do servidor de monitoramento de desempenho e dos dispositivos de teste ou se quiser recursos de notificação (como e-mail ou integração com o Slack) sem precisar criar esses recursos por conta própria.
Usar o Lighthouse CI localmente
Esta seção explica como executar e instalar a CLI CI do Lighthouse localmente e
como configurar lighthouserc.js. Executar a CLI de CI do Lighthouse localmente é a
maneira mais fácil de garantir que seu lighthouserc.js esteja configurado corretamente.
Instale a CLI CI do Lighthouse.
npm install -g @lhci/cliO Lighthouse CI é configurado colocando um arquivo
lighthouserc.jsna raiz do repositório do seu projeto. Este arquivo é obrigatório e contém informações de configuração relacionadas ao Lighthouse CI. Embora o Lighthouse CI possa ser configurado para ser usado sem um repositório git, as instruções neste artigo pressupõem que seu repositório do projeto esteja configurado para usar o git.Na raiz do repositório, crie um arquivo de configuração
lighthouserc.js.touch lighthouserc.jsAdicione o código abaixo a
lighthouserc.js. Este código é uma configuração de CI do Lighthouse vazia. Você adicionará a essa configuração nas etapas posteriores.module.exports = { ci: { collect: { /* Add configuration here */ }, upload: { /* Add configuration here */ }, }, };Sempre que o Lighthouse CI é executado, ele inicia um servidor para exibir seu site. Esse servidor permite que o Lighthouse carregue seu site mesmo quando nenhum outro servidor estiver em execução. Quando a execução do Lighthouse CI terminar, ele encerrará o servidor automaticamente. Para garantir que a exibição funcione corretamente, configure as propriedades
staticDistDiroustartServerCommand.Caso o site seja estático, adicione a propriedade
staticDistDirao objetoci.collectpara indicar onde os arquivos estáticos estão localizados. O Lighthouse CI usará o próprio servidor para exibir esses arquivos ao testar seu site. Se o site não for estático, adicione a propriedadestartServerCommandao objetoci.collectpara indicar o comando que inicia o servidor. O Lighthouse CI inicia um novo processo do servidor durante o teste e o encerra em seguida.// Static site example collect: { staticDistDir: './public', }// Dynamic site example collect: { startServerCommand: 'npm run start', }Adicione a propriedade
urlao objetoci.collectpara indicar URLs em que a CI do Lighthouse precisa executar o Lighthouse. O valor da propriedadeurlprecisa ser fornecido como uma matriz de URLs, que pode conter um ou mais URLs. Por padrão, o Lighthouse CI executará o Lighthouse três vezes em cada URL.collect: { // ... url: ['http://localhost:8080'] }Adicione a propriedade
targetao objetoci.uploade defina o valor como'temporary-public-storage'. Os relatórios do Lighthouse coletados pelo Lighthouse CI serão enviados para o armazenamento público temporário. O relatório permanece lá por sete dias e depois é excluído automaticamente. Este guia de configuração usa a opção de upload "Armazenamento público temporário" porque ela é rápida de configurar. Para informações sobre outras maneiras de armazenar relatórios do Lighthouse, consulte a documentação.upload: { target: 'temporary-public-storage', }O local de armazenamento do relatório será semelhante a este:
https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1580152437799-46441.report.htmlEsse URL não funciona porque o relatório já foi excluído.
Execute a CLI CI do Lighthouse pelo terminal usando o comando
autorun. Isso executará o Lighthouse três vezes e fará upload do relatório médio do Lighthouse.lhci autorunSe você configurou corretamente o Lighthouse CI, a execução deste comando produz uma saída semelhante a esta:
✅ .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.É possível ignorar a mensagem
GitHub token not setna saída do console. Um token do GitHub só será necessário se você quiser usar o Lighthouse CI com uma ação do GitHub. Mais adiante neste artigo, explicamos como configurar uma ação do GitHub.Clique no link na saída que começa com
https://storage.googleapis.com...para acessar o relatório do Lighthouse correspondente à execução média.Os padrões usados por
autorunpodem ser substituídos por meio da linha de comando oulighthouserc.js. Por exemplo, a configuraçãolighthouserc.jsabaixo indica que cinco execuções do Lighthouse precisam ser coletadas sempre que oautoruné executado.Atualize
lighthouserc.jspara usar a propriedadenumberOfRuns:module.exports = { // ... collect: { numberOfRuns: 5 }, // ... }, };Execute novamente o comando
autorun:lhci autorunA saída do terminal mostrará que o Lighthouse foi executado cinco vezes em vez dos três padrão:
✅ .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.Para saber mais sobre outras opções de configuração, consulte a documentação de configuração do Lighthouse CI.
Configure seu processo de CI para executar a CI do Lighthouse
O Lighthouse CI pode ser usado com sua ferramenta de CI favorita. A seção Configurar seu provedor de CI da documentação de CI do Lighthouse contém exemplos de código que mostram como incorporar o Lighthouse CI aos arquivos de configuração de ferramentas de CI comuns. Mais especificamente, estes exemplos de código mostram como executar o Lighthouse CI para coletar medidas de desempenho durante o processo de CI.
Usar o Lighthouse CI para coletar medições de desempenho é um bom lugar para começar
com o monitoramento de desempenho. No entanto, usuários avançados podem ir além e usar o Lighthouse CI para falhar nas versões se não atenderem aos critérios predefinidos, como passar em auditorias específicas do Lighthouse ou atender a todos os orçamentos de desempenho. Esse comportamento é configurado pela propriedade
assert
do arquivo lighthouserc.js.
O Lighthouse CI é compatível com três níveis de declarações:
off: ignora declaraçõeswarn: falhas de impressão em stderrerror: falhas de impressão em stderr e sai do Lighthouse CI com um código de saída diferente de zero.
Veja abaixo um exemplo de uma configuração de lighthouserc.js que inclui
declarações. Ele define declarações para as pontuações das categorias de desempenho e
acessibilidade do Lighthouse. Para testar isso, adicione as declarações abaixo ao
seu arquivo lighthouserc.js e execute novamente o Lighthouse CI.
module.exports = {
ci: {
collect: {
// ...
},
assert: {
assertions: {
'categories:performance': ['warn', {minScore: 1}],
'categories:accessibility': ['error', {minScore: 1}]
}
},
upload: {
// ...
},
},
};
A saída do console é semelhante a esta:
Para mais informações sobre as declarações de CI do Lighthouse, consulte a documentação.
Configure uma ação do GitHub para executar a CI do Lighthouse
Uma ação do GitHub pode ser usada para executar a CI do Lighthouse. Isso gera um novo relatório do Lighthouse sempre que uma alteração de código é enviada para qualquer ramificação de um repositório do GitHub. Use isso em conjunto com uma verificação de status para exibir esses resultados em cada solicitação de envio.
Na raiz do repositório, crie um diretório chamado
.github/workflows. Os fluxos de trabalho do projeto ficarão nesse diretório. Um fluxo de trabalho é um processo executado em um momento predeterminado (por exemplo, quando o código é enviado) e composto por uma ou mais ações.mkdir .github mkdir .github/workflowsEm
.github/workflows, crie um arquivo chamadolighthouse-ci.yaml. Esse arquivo terá a configuração de um novo fluxo de trabalho.touch lighthouse-ci.yamlAdicione o texto abaixo 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!"Essa configuração define um fluxo de trabalho que consiste em um único job que será executado sempre que um novo código for enviado ao repositório. Esse job tem quatro etapas:
- Confira o repositório em que o Lighthouse CI será executado
- Instalar e configurar o Node
- Instalar os pacotes npm necessários
- Executar o Lighthouse CI e fazer upload dos resultados no armazenamento público temporário.
Confirme essas alterações e envie-as por push ao GitHub. Se você tiver seguido corretamente as etapas acima, enviar o código para o GitHub acionará a execução do fluxo de trabalho que você acabou de adicionar.
Para confirmar que o Lighthouse CI foi acionado e visualizar o relatório gerado, acesse a guia Actions do seu projeto. Você verá o fluxo de trabalho Build project and Run Lighthouse CI listado na confirmação mais recente.
É possível navegar até o relatório do Lighthouse correspondente a um commit específico na guia Ações. Clique na confirmação e na etapa do fluxo de trabalho Lighthouse CI. Em seguida, expanda os resultados da etapa run Lighthouse CI.
Você acabou de configurar uma ação do GitHub para executar o Lighthouse CI. Isso será mais útil quando usado com uma verificação de status do GitHub.
Configurar uma verificação de status do GitHub
Uma verificação de status, se configurada, é uma mensagem que aparece em todos os PRs e geralmente inclui informações como os resultados de um teste ou o sucesso de um build.
As etapas abaixo explicam como configurar uma verificação de status para o Lighthouse CI.
Acesse a página do app GitHub de CI do Lighthouse e clique em Configurar.
(Opcional) Se você faz parte de várias organizações no GitHub, escolha a organização proprietária do repositório em que você quer usar a CI do Lighthouse.
Selecione Todos os repositórios, se você quiser ativar o Lighthouse CI em todos os repositórios, ou selecione Somente selecionar repositórios se quiser usá-lo apenas em repositórios específicos. Depois, selecione os repositórios. Em seguida, clique em Instalar e autorizar.
Copie o token exibido. Ela será usada na próxima etapa.
Para adicionar o token, navegue até a página Settings do seu repositório do GitHub, clique em Secrets e em Add a new secret.
Defina o campo Nome como
LHCI_GITHUB_APP_TOKEN, configure o campo Valor como o token que você copiou na última etapa e clique no botão Adicionar chave secreta.Acesse o arquivo
lighthouse-ci.yamle adicione o novo secret do ambiente ao comando "executar o 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: $
- A verificação de status está pronta para uso. Para testá-la, crie uma nova solicitação de envio ou envie uma confirmação para uma solicitação de envio existente.
Configurar o servidor de CI do Lighthouse
O servidor de CI do Lighthouse fornece um painel para explorar os relatórios históricos do Lighthouse. Ele também pode atuar como um repositório de dados particular de longo prazo para os relatórios do Lighthouse.
- Escolha quais confirmações serão comparadas.
- O valor em que a pontuação do Lighthouse mudou entre as duas confirmações.
- Esta seção mostra apenas as métricas que foram alteradas entre as duas confirmações.
- As regressões estão destacadas em rosa.
- As melhorias estão destacadas em azul.
O Lighthouse CI Server é ideal para usuários que se sentem à vontade para implantar e gerenciar a própria infraestrutura.
Para informações sobre como configurar o servidor CI do Lighthouse, incluindo receitas para usar o Heroku e o Docker para implantação, consulte instructions.
Saiba mais
- Repositório do Lighthouse CI no GitHub (em inglês)