Se usó la API de Cloud Translation para traducir esta página.

Supervisión del rendimiento con Lighthouse CI

Cómo agregar Lighthouse a un sistema de integración continua, como GitHub Actions

Katie Hempenius

Lighthouse CI es un paquete de herramientas para usar Lighthouse durante la integración continua. La CI de Lighthouse se puede incorporar a los flujos de trabajo de los desarrolladores de muchas maneras. En esta guía, se abarcan los siguientes temas:

Usar la CLI de CI de Lighthouse
Configura tu proveedor de CI para ejecutar Lighthouse CI.
Configura una acción de GitHub y una verificación de estado para Lighthouse CI. Esto mostrará automáticamente los resultados de Lighthouse en las solicitudes de extracción de GitHub.
Creación de un panel de rendimiento y un almacén de datos para los informes de Lighthouse

Descripción general

Lighthouse CI es un paquete de herramientas gratuitas que facilitan el uso de Lighthouse para la supervisión del rendimiento. Un solo informe de Lighthouse proporciona un resumen del rendimiento de una página web en el momento en que se ejecuta; Lighthouse CI muestra cómo estos resultados cambiaron con el tiempo. Esto se puede usar para identificar el impacto de cambios de código específicos o garantizar que se cumplan los umbrales de rendimiento durante los procesos de integración continua. Si bien la supervisión del rendimiento es el caso de uso más común de Lighthouse CI, se puede utilizar para supervisar otros aspectos del informe de Lighthouse, por ejemplo, SEO o la accesibilidad.

La interfaz de línea de comandos de Lighthouse CI proporciona la funcionalidad principal de Lighthouse CI. (Nota: Esta es una herramienta independiente de la CLI de Lighthouse). La CLI de Lighthouse CI proporciona un conjunto de comandos para usar la CI de Lighthouse. Por ejemplo, el comando autorun ejecuta varias ejecuciones de Lighthouse, identifica la mediana del informe de Lighthouse y sube el informe para su almacenamiento. Este comportamiento se puede personalizar en gran medida pasando marcas adicionales o personalizando lighthouserc.js, el archivo de configuración de Lighthouse CI.

Si bien la funcionalidad principal de la CI de Lighthouse se encapsula principalmente en la CLI de la CI de Lighthouse, la CI de Lighthouse se suele usar mediante uno de los siguientes enfoques:

Cómo ejecutar Lighthouse CI como parte de la integración continua
Usar una acción de GitHub de Lighthouse CI que se ejecute y comenta en cada solicitud de extracción
Seguimiento del rendimiento en el tiempo a través del panel que proporciona Lighthouse Server

Todos estos enfoques se basan en la CLI de la CI de Lighthouse.

Las alternativas a Lighthouse CI incluyen servicios de supervisión del rendimiento de terceros o la escritura de tu propia secuencia de comandos para recopilar datos de rendimiento durante el proceso de CI. Considera usar un servicio de terceros si prefieres permitir que alguien más se encargue de la administración de tu servidor de supervisión del rendimiento y de los dispositivos de prueba, o si deseas capacidades de notificación (como el correo electrónico o la integración de Slack) sin tener que compilar estas funciones tú mismo.

Usa Lighthouse CI de forma local

En esta sección, se explica cómo ejecutar e instalar la CLI de CI de Lighthouse de forma local y cómo configurar lighthouserc.js. Ejecutar la CLI de CI de Lighthouse de forma local es la forma más fácil de asegurarte de que tu lighthouserc.js esté configurado de forma correcta.

Instala la CLI de CI de Lighthouse.
```
npm install -g @lhci/cli
```
Lighthouse CI se configura colocando un archivo lighthouserc.js en la raíz del repositorio de tu proyecto. Este archivo es obligatorio y contendrá información de configuración relacionada con la CI de Lighthouse. Aunque Lighthouse CI puede configurarse para usarse sin un repositorio de git, en las instrucciones de este artículo, se supone que el repositorio de tu proyecto está configurado para usar Git.
En la raíz de tu repositorio, crea un archivo de configuración lighthouserc.js.
```
touch lighthouserc.js
```
Agrega el siguiente código a lighthouserc.js. Este código es una configuración de CI de Lighthouse vacía. Agregarás esta configuración en los pasos posteriores.
```
module.exports = {
  ci: {
    collect: {
      /* Add configuration here */
    },
    upload: {
      /* Add configuration here */
    },
  },
};
```
Cada vez que se ejecuta Lighthouse CI, se inicia un servidor para entregar tu sitio. Este servidor es el que permite que Lighthouse cargue tu sitio incluso cuando no hay otros servidores en ejecución. Cuando Lighthouse CI termine de ejecutarse, se cerrará automáticamente el servidor. Para asegurarte de que la entrega funcione de forma correcta, debes configurar las propiedades staticDistDir o startServerCommand.

Si tu sitio es estático, agrega la propiedad staticDistDir al objeto ci.collect para indicar dónde se encuentran los archivos estáticos. Lighthouse CI usará su propio servidor para entregar estos archivos mientras pruebas tu sitio. Si tu sitio no es estático, agrega la propiedad startServerCommand al objeto ci.collect para indicar el comando que inicia tu servidor. Lighthouse CI iniciará un nuevo proceso del servidor durante las pruebas y lo cerrará después.
```
// Static site example
collect: {
  staticDistDir: './public',
}
```
```
// Dynamic site example
collect: {
  startServerCommand: 'npm run start',
}
```
Agrega la propiedad url al objeto ci.collect para indicar las URLs en las que la CI de Lighthouse debe ejecutar Lighthouse. El valor de la propiedad url se debe proporcionar como un array de URLs, que puede contener una o más URLs. De forma predeterminada, Lighthouse CI ejecutará Lighthouse tres veces con cada URL.
```
collect: {
  // ...
  url: ['http://localhost:8080']
}
```
Nota: El servidor que configuraste en el paso anterior debería poder entregar estas URLs. Por lo tanto, si ejecutas Lighthouse CI de forma local, es probable que estas URLs incluyan localhost en lugar de tu host de producción.
Agrega la propiedad target al objeto ci.upload y establece el valor en 'temporary-public-storage'. Los informes de Lighthouse que recopila Lighthouse CI se subirán al almacenamiento público temporal. El informe permanecerá allí durante siete días y, luego, se borrará automáticamente. En esta guía de configuración, se usa la opción de carga de "almacenamiento público temporal", ya que se configura rápidamente. Para obtener información sobre otras maneras de almacenar los informes de Lighthouse, consulta la documentación.
```
upload: {
  target: 'temporary-public-storage',
}
```
La ubicación de almacenamiento del informe será similar a la siguiente:
```
https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1580152437799-46441.report.html
```
(Esta URL no funcionará porque ya se borró el informe).
Ejecuta la CLI de CI de Lighthouse desde la terminal con el comando autorun. Con esta acción, se ejecutará Lighthouse tres veces y se subirá el informe medio de Lighthouse.
```
lhci autorun
```
Si configuraste Lighthouse CI de forma correcta, ejecutar este comando debería producir un resultado similar al siguiente:
```
✅  .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.
```
Puedes ignorar el mensaje GitHub token not set en el resultado de la consola. Solo se necesita un token de GitHub si deseas usar Lighthouse CI con una acción de GitHub. Cómo configurar una acción de GitHub se explica más adelante en este artículo.

Si haces clic en el vínculo del resultado que comienza con https://storage.googleapis.com..., accederás al informe de Lighthouse correspondiente a la mediana de ejecución de Lighthouse.

Los valores predeterminados que usa autorun se pueden anular a través de la línea de comandos o lighthouserc.js. Por ejemplo, la siguiente configuración lighthouserc.js indica que se deben recopilar cinco ejecuciones de Lighthouse cada vez que se ejecuta autorun.

Actualiza lighthouserc.js para usar la propiedad numberOfRuns:

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

Vuelve a ejecutar el comando autorun:

lhci autorun

El resultado de la terminal debería mostrar que Lighthouse se ejecutó cinco veces en lugar de las tres predeterminadas:

✅  .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 obtener más información sobre otras opciones de configuración, consulta la documentación de configuración de la CI de Lighthouse.

Configura tu proceso de CI para ejecutar Lighthouse CI

Lighthouse CI puede usarse con tu herramienta favorita de CI. La sección Configura tu proveedor de CI de la documentación de Lighthouse CI contiene muestras de código que muestran cómo incorporar Lighthouse CI a los archivos de configuración de las herramientas de CI comunes. Específicamente, estas muestras de código muestran cómo ejecutar Lighthouse CI para recopilar mediciones de rendimiento durante el proceso de CI.

Usar Lighthouse CI para recopilar mediciones de rendimiento es un buen punto de partida de la supervisión del rendimiento. Sin embargo, es posible que los usuarios avanzados quieran ir más allá y usar la CI de Lighthouse para fallar las compilaciones si no cumplen con los criterios predefinidos, como pasar auditorías específicas de Lighthouse o alcanzar todos los presupuestos de rendimiento. Este comportamiento se configura mediante la propiedad assert del archivo lighthouserc.js.

Lighthouse CI admite tres niveles de aserciones:

off: Ignora las aserciones.
warn: Errores de impresión en stderr
error: Fallas de impresión en stderr y salida de Lighthouse CI con un código de salida que no es cero.

A continuación, se muestra un ejemplo de una configuración lighthouserc.js que incluye aserciones. Establece aserciones para las puntuaciones de las categorías de accesibilidad y rendimiento de Lighthouse. Para probarlo, agrega las aserciones que se muestran a continuación a tu archivo lighthouserc.js y, luego, vuelve a ejecutar Lighthouse CI.

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

El resultado de la consola que genera se ve de la siguiente manera:

Captura de pantalla de un mensaje de advertencia generado por Lighthouse CI

Para obtener más información sobre las aserciones de Lighthouse CI, consulta la documentación.

Configura una acción de GitHub para ejecutar Lighthouse CI

Se puede usar una acción de GitHub para ejecutar Lighthouse CI. Esto generará un nuevo informe de Lighthouse cada vez que se envíe un cambio de código a cualquier rama de un repositorio de GitHub. Úsalo junto con una verificación de estado para mostrar estos resultados en cada solicitud de extracción.

Captura de pantalla de una verificación del estado de GitHub

En la raíz de tu repositorio, crea un directorio llamado .github/workflows. Los flujos de trabajo de tu proyecto se incluirán en este directorio. Un flujo de trabajo es un proceso que se ejecuta en un momento predeterminado (por ejemplo, cuando se envía código) y que se compone de una o más acciones.
```
mkdir .github
mkdir .github/workflows
```
En .github/workflows, crea un archivo llamado lighthouse-ci.yaml. Este archivo contendrá la configuración de un flujo de trabajo nuevo.
```
touch lighthouse-ci.yaml
```

Agrega el siguiente texto 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!"

Con esta configuración, se establece un flujo de trabajo que consta de un solo trabajo que se ejecutará cada vez que se envíe código nuevo al repositorio. Este trabajo tiene cuatro pasos:

Revisa el repositorio en el que se ejecutará Lighthouse CI
Instala y configura Node
Instala los paquetes de npm necesarios
Ejecuta Lighthouse CI y sube los resultados al almacenamiento público temporal.

Confirma estos cambios y envíalos a GitHub. Si seguiste correctamente los pasos anteriores, enviar código a GitHub activará la ejecución del flujo de trabajo que acabas de agregar.
Para confirmar que Lighthouse CI se activó y ver el informe que generó, ve a la pestaña Acciones de tu proyecto. Deberías ver el flujo de trabajo Build project and Run Lighthouse CI en la lista de tu confirmación más reciente.

Puedes navegar al informe de Lighthouse correspondiente a una confirmación en particular desde la pestaña Acciones. Haz clic en la confirmación, en el paso del flujo de trabajo de Lighthouse CI y, luego, expande los resultados del paso ejecutar Lighthouse CI.

Acabas de configurar una acción de GitHub para ejecutar Lighthouse CI. Esto será más útil cuando se use junto con una verificación de estado de GitHub.

Configura una verificación de estado de GitHub

Una verificación de estado, si está configurada, es un mensaje que aparece en cada solicitud de extracción y, por lo general, incluye información como los resultados de una prueba o el éxito de una compilación.

Captura de pantalla de la pestaña “Configuración” de GitHub

En los siguientes pasos, se explica cómo configurar una verificación de estado para Lighthouse CI.

Ve a la página de la app de GitHub de Lighthouse CI y haz clic en Configurar.
Si formas parte de varias organizaciones en GitHub, elige la organización propietaria del repositorio para el que deseas usar la CI de Lighthouse (opcional).
Selecciona Todos los repositorios si deseas habilitar Lighthouse CI en todos los repositorios o selecciona Solo seleccionar repositorios si solo deseas usarlo en repositorios específicos. Luego, selecciona los repositorios. Luego, haz clic en Instalar y autorizar.
Copia el token que se muestra. La necesitarás en el próximo paso.
Para agregar el token, navega a la página Configuración de tu repositorio de GitHub, haz clic en Secretos y, luego, en Agregar un secreto nuevo.
Establece el campo Nombre en LHCI_GITHUB_APP_TOKEN y establece el campo Valor en el token que copiaste en el último paso y, luego, haz clic en el botón Agregar secreto.
Ve al archivo lighthouse-ci.yaml y agrega el nuevo secreto de entorno 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: $

La verificación de estado está lista para usarse. Para probarla, crea una solicitud de extracción nueva o envía una confirmación a una solicitud de extracción existente.

Configura el servidor de CI de Lighthouse

El servidor de CI de Lighthouse proporciona un panel para explorar los informes históricos de Lighthouse. También puede actuar como un almacén de datos privado a largo plazo para los informes de Lighthouse.

Captura de pantalla del panel del servidor de CI de Lighthouse

Captura de pantalla de la comparación de dos informes de Lighthouse en el servidor de CI de Lighthouse

Elige qué confirmaciones quieres comparar.
El importe que cambió la puntuación de Lighthouse entre las dos confirmaciones.
En esta sección, solo se muestran las métricas que cambiaron entre las dos confirmaciones.
Las regresiones aparecen destacadas en rosa.
Las mejoras se destacan en azul.

Lighthouse CI Server es más adecuado para usuarios que saben cómo implementar y administrar su propia infraestructura.

Si deseas obtener información sobre la configuración del servidor de CI de Lighthouse, incluidas las recetas para usar Heroku y Docker para la implementación, consulta estas instructions.

Más información

Repositorio de GitHub de Lighthouse CI