Ir al contenido

Bloqueo de builds en CI y marcadores de despliegue

Puedes ejecutar una prueba de page speed desde tu pipeline de CI y hacer fallar el build cuando la página rompa un presupuesto, para que una versión lenta se detenga antes de llegar a tus visitantes. El mismo paso puede marcar el despliegue en los gráficos de historial de la prueba, para que una ralentización quede junto a la versión que la causó.

Todo funciona con un pequeño script disponible en https://speed.loadfocus.com/ci.js. Necesita Node 14 o posterior y no tiene dependencias, así que funciona en GitHub Actions y en cualquier otra CI que ejecute Node.

  • Una prueba para la página. El script ejecuta una prueba que ya tienes, consulta Primeros pasos.
  • El id de la prueba. Abre un resultado de la prueba y desplázate hasta CI y marcadores de despliegue, debajo de los gráficos de historial. El paso que aparece en Haz fallar un build cuando esta página se vuelva más lenta ya contiene el id, y Copiar lo copia al portapapeles. El id también es la parte que va después de /speedtests/ en la dirección de la página de resultados. El script lo recibe como --monitor.
  • Una clave de API. Crea una en la página API Keys y guárdala como secreto de CI con el nombre LOADFOCUS_API_KEY. Si trabajas en más de un equipo, define también LOADFOCUS_TEAM_ID; sin ella se usa tu equipo predeterminado.

Cada ejecución de CI lanza una ejecución real de la prueba, así que cuenta como una ejecución de prueba de tu plan.

Añade tu clave de API como secreto del repositorio (Settings > Secrets and variables > Actions > LOADFOCUS_API_KEY) y crea .github/workflows/page-speed.yml:

name: Page speed budget
on:
push:
branches: [ main ]
jobs:
page-speed:
runs-on: ubuntu-latest
steps:
- name: Page speed budget
run: curl -fsSL https://speed.loadfocus.com/ci.js | node - --monitor YOUR_MONITOR_ID --marker "${{ github.sha }}" --budget "lcp<=2.5"
env:
LOADFOCUS_API_KEY: ${{ secrets.LOADFOCUS_API_KEY }}

Sustituye YOUR_MONITOR_ID por el id de tu prueba. El paso publica un marcador de despliegue con el commit como etiqueta, ejecuta la prueba, espera el resultado y hace fallar el job cuando se rompe un presupuesto. Colócalo después de tu paso de despliegue para que mida la versión que acabas de publicar.

Para enlazar el marcador con la página del commit, añade --marker-url "${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}". Repite --budget para más límites, por ejemplo --budget "lcp<=2.5" --budget "performance>=90".

Opción Qué hace
--monitor <id> El id de la prueba que se ejecuta. Obligatorio.
--budget "lcp<=2.5" Un límite adicional para esta ejecución. Se puede repetir.
--marker "<label>" Publica además un marcador de despliegue con esta etiqueta (hasta 120 caracteres), por ejemplo el commit o el tag.
--marker-url <url> Un enlace para el marcador, por ejemplo la página de la versión o del commit.
--timeout <seconds> Se rinde pasado este tiempo. Por defecto 900.
--json Imprime el resultado en bruto como JSON.
--host <url> Por defecto https://speed.loadfocus.com.

curl -fsSL https://speed.loadfocus.com/ci.js | node - --help imprime la misma lista.

Cada ejecución se comprueba contra dos grupos de límites:

  • Las alertas de umbral de la prueba. Cada alerta activada con por encima de o por debajo de y un valor cuenta como presupuesto: una alerta de Largest Contentful Paint por encima de 2.5 se convierte en el presupuesto "LCP como máximo 2.5 s". Son los mismos presupuestos que muestra la página de resultados, consulta Presupuestos de rendimiento. Las alertas que usan "empeora un (%)" no tienen un límite fijo y no se comprueban.
  • Cada --budget que pases. Un presupuesto es una métrica, <= o >= y un número. Puedes pasar hasta 30.
Métrica Unidad
performance, accessibility, best-practices, seo puntuación de 0 a 100
fcp, lcp, si, tbt, tti segundos
cls Cumulative Layout Shift
weight peso de la página en KB
requests número de solicitudes

Las métricas de tiempo van en segundos, Total Blocking Time incluido: tbt<=0.3 significa 300 ms. Un presupuesto cuya métrica no se midió en la ejecución falla, así que una página que no se pudo medir nunca pasa la comprobación.

Código de salida Significado
0 Todos los presupuestos cumplidos.
1 Se rompió un presupuesto.
2 No se pudo comprobar la ejecución: falta la clave de API o el id de la prueba, la ejecución no pudo empezar (por ejemplo por los límites de tu plan), no se pudo probar la página, la ejecución se canceló o no hubo resultado antes del timeout.

El log muestra una línea PASS o FAIL por presupuesto con el valor medido, el límite y el origen del presupuesto (alert o pipeline), y después un enlace al informe completo. Si no hay presupuestos definidos, el script lo indica y termina con 0.

En GitHub Actions el resultado también se escribe en el resumen del job: las cuatro puntuaciones de Lighthouse, una tabla con cada presupuesto y un enlace Full report.

Un marcador es una línea discontinua en los gráficos de historial de la prueba, en la serie Despliegues. Con --marker el script publica uno antes de lanzar la ejecución. Si el marcador no se puede publicar, el script lo indica y sigue con la comprobación.

Para marcar despliegues sin ejecutar ninguna comprobación, usa el comando de O solo marcar despliegues en el mismo panel:

Ventana de terminal
curl -X POST "https://speed.loadfocus.com/api/test/applighthouse/annotations" \
-H "loadfocus-auth: YOUR_API_KEY" -H "content-type: application/json" \
-d '{"label":"Deployed v1.4.2","configId":"YOUR_MONITOR_ID"}'
  • label es obligatorio, hasta 120 caracteres.
  • Omite configId para marcar todas las pruebas del equipo.
  • Añade url para enlazar la versión.
  • Añade timestamp (fecha ISO o epoch) para fechar el marcador hasta 30 días atrás.

Marcadores recientes en el panel lista los marcadores del periodo mostrado, del más reciente al más antiguo. Los marcadores publicados sin prueba indican todos los monitores, y Eliminar borra uno. Cuando un equipo llega a 5.000 marcadores, los más antiguos dejan sitio a los nuevos.

Cuando se rompe un presupuesto, la sección Comparar ejecuciones del resultado muestra qué cambió. Elige otra ejecución de la misma prueba en Comparar con y LoadFocus muestra, lado a lado y con una columna Cambio:

  • Puntuaciones y Métricas
  • Peso de la página, en total y por tipo de recurso, más el número de Solicitudes
  • Solicitudes nuevas, Solicitudes que crecieron y Solicitudes eliminadas
  • Problemas nuevos y Corregido desde entonces, las auditorías que empezaron o dejaron de fallar

Añade el id de la otra ejecución a la dirección del resultado como parámetro compare (por ejemplo &compare=12345 después del testrunid) y la página se abre con esa ejecución ya elegida, algo útil para compartir.