O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Monitoramento de desempenho com o Lighthouse CI

Como adicionar o Lighthouse a um sistema de integração contínua, como o GitHub Actions.

Katie Hempenius

O Lighthouse CI é um conjunto de ferramentas para usar o Lighthouse durante a integração contínua. O Lighthouse CI pode ser incorporado aos fluxos de trabalho do desenvolvedor de várias maneiras. Neste guia, abordamos os seguintes tópicos:

Usando a CLI do Lighthouse CI.
Configurar seu provedor de CI para executar o Lighthouse CI.
Configurar uma ação do GitHub e uma verificação de status para o Lighthouse CI. Isso vai mostrar automaticamente os resultados do Lighthouse nas solicitações de pull do GitHub.
Criar um painel de desempenho e um repositório de dados para relatórios do Lighthouse.

Visão geral

O Lighthouse CI é um pacote de ferramentas sem custo financeiro que facilita o uso do Lighthouse para monitoramento de desempenho. Um único relatório do Lighthouse fornece um resumo do desempenho de uma página da Web no momento em que é executado. A CI do Lighthouse 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, como SEO ou acessibilidade.

A funcionalidade principal do Lighthouse CI é fornecida pela interface de linha de comando do Lighthouse CI. Observação: essa é uma ferramenta diferente da CLI do 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 mediano do Lighthouse e faz o upload do relatório para armazenamento. Esse comportamento pode ser bastante personalizado transmitindo outras flags ou personalizando o arquivo de configuração do Lighthouse CI, lighthouserc.js.

Embora a funcionalidade principal do Lighthouse CI esteja encapsulada principalmente na CLI do Lighthouse CI, ele normalmente é usado por uma das seguintes abordagens:

Como executar a CI do Lighthouse como parte da integração contínua
Usar uma ação do GitHub de CI do Lighthouse que é executada e comenta em cada solicitação de pull
Monitorar o desempenho ao longo do tempo usando o 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 a criação de um script próprio para coletar dados de performance durante o processo de CI. Considere usar um serviço de terceiros se preferir que outra pessoa gerencie o servidor de monitoramento de desempenho e os dispositivos de teste ou se quiser recursos de notificação (como integração com e-mail ou Slack) sem precisar criar esses recursos por conta própria.

Usar o Lighthouse CI localmente

Nesta seção, explicamos como executar e instalar a CLI do Lighthouse CI localmente e como configurar o lighthouserc.js. Executar a CLI do Lighthouse CI localmente é a maneira mais fácil de garantir que o lighthouserc.js esteja configurado corretamente.

Instale a CLI do Lighthouse CI.
```
npm install -g @lhci/cli
```
Para configurar o Lighthouse CI, coloque um arquivo lighthouserc.js na raiz do repositório do projeto. Esse arquivo é obrigatório e vai conter informações de configuração relacionadas ao Lighthouse CI. Embora a CI do Lighthouse possa ser configurada para ser usada sem um repositório git, as instruções neste artigo pressupõem que o 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.js
```

Adicione o seguinte código a lighthouserc.js: Esse código é uma configuração vazia da CI do Lighthouse. Você vai adicionar elementos a essa configuração nas próximas etapas.

module.exports = {
  ci: {
    collect: {
      /* Add configuration here */
    },
    upload: {
      /* Add configuration here */
    },
  },
};

Sempre que a CI do Lighthouse é executada, ela inicia um servidor para disponibilizar seu site. Esse servidor é o que permite que o Lighthouse carregue seu site mesmo quando nenhum outro servidor está em execução. Quando a CI do Lighthouse terminar de ser executada, ela vai encerrar o servidor automaticamente. Para garantir que a veiculação funcione corretamente, configure as propriedades staticDistDir ou startServerCommand.

Se o site for estático, adicione a propriedade staticDistDir ao objeto ci.collect para indicar onde os arquivos estáticos estão localizados. O Lighthouse CI vai usar o próprio servidor para disponibilizar esses arquivos enquanto testa seu site. Se o site não for estático, adicione a propriedade startServerCommand ao objeto ci.collect para indicar o comando que inicia o servidor. O Lighthouse CI vai iniciar um novo processo de servidor durante o teste e o encerrará depois.
```
// Static site example
collect: {
  staticDistDir: './public',
}
```
```
// Dynamic site example
collect: {
  startServerCommand: 'npm run start',
}
```
Adicione a propriedade url ao objeto ci.collect para indicar os URLs em que a CI do Lighthouse precisa executar o Lighthouse. O valor da propriedade url precisa ser fornecido como uma matriz de URLs, que pode conter um ou mais URLs. Por padrão, o Lighthouse CI executa o Lighthouse três vezes em cada URL.
```
collect: {
  // ...
  url: ['http://localhost:8080']
}
```
Observação: esses URLs precisam ser disponibilizados pelo servidor que você configurou na etapa anterior. Portanto, se você estiver executando a CI do Lighthouse localmente, esses URLs provavelmente vão incluir localhost em vez do host de produção.
Adicione a propriedade target ao objeto ci.upload e defina o valor como 'temporary-public-storage'. Os relatórios do Lighthouse coletados pela CI do Lighthouse serão enviados para o armazenamento público temporário. O relatório vai permanecer lá por sete dias e depois será excluído automaticamente. Este guia de configuração usa a opção de upload "armazenamento público temporário" porque é rápida de configurar. Para saber mais 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.html
```
Esse URL não vai funcionar porque o relatório já foi excluído.
Execute a CLI do Lighthouse CI no terminal usando o comando autorun. Isso vai executar o Lighthouse três vezes e fazer upload do relatório mediano do Lighthouse.
```
lhci autorun
```
Se você tiver configurado corretamente a CI do Lighthouse, a execução desse comando vai produzir 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.
```
Ignore a mensagem GitHub token not set na saída do console. Um token do GitHub só é necessário se você quiser usar o Lighthouse CI com uma ação do GitHub. Como configurar uma ação do GitHub é explicado mais adiante neste artigo.

Clique no link na saída que começa com https://storage.googleapis.com... para acessar o relatório do Lighthouse correspondente à execução mediana do Lighthouse.

Os padrões usados por autorun podem ser substituídos pela linha de comando ou por lighthouserc.js. Por exemplo, a configuração lighthouserc.js abaixo indica que cinco execuções do Lighthouse precisam ser coletadas sempre que autorun for executado.

Atualize lighthouserc.js para usar a propriedade numberOfRuns:

module.exports = {
    // ...
    collect: {
      numberOfRuns: 5
    },
  // ...
  },
};

Execute novamente o comando autorun:

lhci autorun

A saída do terminal vai mostrar que o Lighthouse foi executado cinco vezes, em vez das três vezes 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 da CI do Lighthouse.

Configure seu processo de CI para executar o Lighthouse CI

O Lighthouse CI pode ser usado com sua ferramenta de CI favorita. A seção Configure Your CI Provider (em inglês) da documentação do Lighthouse CI contém exemplos de código que mostram como incorporar o Lighthouse CI aos arquivos de configuração de ferramentas de CI comuns. Especificamente, esses exemplos de código mostram como executar o Lighthouse CI para coletar medições de desempenho durante o processo de CI.

Usar a CI do Lighthouse para coletar medições de desempenho é um bom ponto de partida para o monitoramento de desempenho. No entanto, os usuários avançados podem ir além e usar a CI do Lighthouse para falhar em builds que não atendem a critérios predefinidos, como passar em auditorias específicas do Lighthouse ou atender a todos os montantes de desempenho. Esse comportamento é configurado pela propriedade assert do arquivo lighthouserc.js.

O Lighthouse CI aceita três níveis de declarações:

off: ignorar declarações
warn: imprime falhas em stderr
error: imprime falhas no stderr e sai do Lighthouse CI com um código de saída diferente de zero.

Veja abaixo um exemplo de 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 mostradas abaixo ao arquivo lighthouserc.js e execute novamente a CI do Lighthouse.

module.exports = {
  ci: {
    collect: {
      // ...
    },
    assert: {
      assertions: {
        'categories:performance': ['warn', {minScore: 1}],
        'categories:accessibility': ['error', {minScore: 1}]
      }
    },
    upload: {
      // ...
    },
  },
};

A saída do console gerada é assim:

Captura de tela de uma mensagem de aviso gerada pela CI do Lighthouse

Para mais informações sobre as declarações de CI do Lighthouse, consulte a documentação.

Configurar uma ação do GitHub para executar a CI do Lighthouse

Uma ação do GitHub pode ser usada para executar o Lighthouse CI. Isso vai gerar um novo relatório do Lighthouse sempre que uma mudança de código for 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 pull.

Captura de tela de uma verificação de status do GitHub

Na raiz do repositório, crie um diretório chamado .github/workflows. Os fluxos de trabalho do projeto vão para esse diretório. Um fluxo de trabalho é um processo que é executado em um horário predeterminado (por exemplo, quando o código é enviado) e é composto por uma ou mais ações.
```
mkdir .github
mkdir .github/workflows
```
Em .github/workflows, crie um arquivo chamado lighthouse-ci.yaml. Esse arquivo vai conter a configuração de um novo fluxo de trabalho.
```
touch lighthouse-ci.yaml
```

Adicione o texto a seguir ao 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:

Verifique o repositório em que a CI do Lighthouse será executada.
Instalar e configurar o Node
Instalar os pacotes npm necessários
Execute a CI do Lighthouse e faça upload dos resultados para o armazenamento público temporário.

Confirme essas mudanças e envie-as para o GitHub. Se você seguiu corretamente as etapas acima, o envio do código para o GitHub vai acionar a execução do fluxo de trabalho que você acabou de adicionar.
Para confirmar que a CI do Lighthouse foi acionada e conferir o relatório gerado, acesse a guia Actions do projeto. O fluxo de trabalho Build project and Run Lighthouse CI vai aparecer no commit mais recente.

É possível acessar o relatório do Lighthouse correspondente a uma confirmação específica na guia Ações. Clique no commit, clique na etapa do fluxo de trabalho Lighthouse CI e expanda os resultados da etapa run Lighthouse CI.

Você acabou de configurar uma ação do GitHub para executar a CI do Lighthouse. Isso será mais útil quando usado em conjunto 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 cada PR e geralmente inclui informações como os resultados de um teste ou o sucesso de um build.

Captura de tela da guia "Configurações" do GitHub

As etapas abaixo explicam como configurar uma verificação de status para a CI do Lighthouse.

Acesse a página do app do GitHub da CI do Lighthouse e clique em Configurar.
(Opcional) Se você faz parte de várias organizações no GitHub, escolha a organização que é proprietária do repositório em que você quer usar o Lighthouse CI.
Selecione Todos os repositórios se quiser ativar a CI do Lighthouse em todos os repositórios ou selecione Somente repositórios selecionados se quiser usá-la apenas em repositórios específicos e, em seguida, 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, acesse a página Configurações do repositório do GitHub, clique em Secrets e em Adicionar um novo secret.
Defina o campo Nome como LHCI_GITHUB_APP_TOKEN e o campo Valor como o token que você copiou na última etapa. Em seguida, clique no botão Adicionar secret.
Acesse o arquivo lighthouse-ci.yaml e adicione o novo secret de ambiente ao 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: $

A verificação de status está pronta para uso. Para testar, crie uma nova solicitação de pull ou envie um commit para uma solicitação de pull atual.

Configurar o servidor de CI do Lighthouse

O servidor de CI do Lighthouse oferece um painel para analisar relatórios históricos do Lighthouse. Ele também pode atuar como um repositório de dados particular de longo prazo para relatórios do Lighthouse.

Captura de tela do painel do servidor de CI do Lighthouse

Captura de tela da comparação de dois relatórios do Lighthouse no servidor de CI do Lighthouse

Escolha quais commits comparar.
A mudança na pontuação do Lighthouse entre os dois commits.
Esta seção mostra apenas as métricas que mudaram entre os dois commits.
As regressões são destacadas em rosa.
As melhorias são destacadas em azul.

O servidor de CI do Lighthouse é mais adequado para usuários que se sentem confortáveis em implantar e gerenciar a própria infraestrutura.

Para saber como configurar o servidor de CI do Lighthouse, incluindo receitas para usar o Heroku e o Docker para implantação, consulte estas instruções.

Saiba mais

Repositório do GitHub do Lighthouse CI (em inglês)