Auditar en CI con Lighthouse CI

El presupuesto de tamaño de la lección anterior vigila los bytes, pero el rendimiento que vive el usuario es más que peso: es LCP, es INP, es una puntuación que solo emerge al ejecutar el sitio en un navegador real. Medir eso a mano, cuando te acuerdas, es teatro; la regresión que importa siempre llega el día que no miraste. Lighthouse CI convierte la auditoría en una etapa más del pipeline: construye el sitio, lo corre bajo Lighthouse varias veces, compara las métricas con aserciones que tú declaras y hace fallar el build cuando un cambio cruza la línea. Deja de ser algo que recuerdas comprobar y pasa a ser algo que el sistema no te deja olvidar, con un informe compartible clavado en cada pull request.

Qué es Lighthouse CI y por qué vive en el pipeline

Lighthouse CI —el paquete @lhci/cli— envuelve el mismo motor de auditoría que ya conoces en tres fases encadenadas que resume el comando lhci autorun. Primero recoge: levanta tu sitio ya construido y ejecuta Lighthouse sobre él varias veces, guardando cada informe. Después asevera: compara las métricas recogidas con las reglas que hayas declarado y decide si la corrida pasa o falla. Por último publica: sube los informes a un almacenamiento donde poder abrirlos. La gracia de moverlo al pipeline es la misma que la del presupuesto de tamaño, llevada un paso más allá: en lugar de vigilar solo cuántos bytes salen, vigila cómo se comporta el sitio cuando esos bytes se ejecutan.

// lighthouserc.json — recoge, asevera y publica en cada corrida
{
  "ci": {
    "collect": {
      "startServerCommand": "npm run preview",
      "url": ["http://localhost:4173/", "http://localhost:4173/panel"],
      "numberOfRuns": 5
    },
    "assert": {
      "preset": "lighthouse:recommended",
      "assertions": {
        "categories:performance": ["warn", { "minScore": 0.9 }],
        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
        "total-blocking-time": ["error", { "maxNumericValue": 200 }],
        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }]
      }
    },
    "upload": { "target": "temporary-public-storage" }
  }
}

El campo startServerCommand deja que Lighthouse CI arranque tu servidor de preview y lo apague al terminar, de modo que audita el artefacto real de producción, no el dev server. La lista de url es la que hace la auditoría por ruta: cada pantalla se mide por separado, igual que cada una defiende su propio presupuesto. Y numberOfRuns es la primera línea de defensa contra el ruido, un asunto al que volveremos porque decide si la puerta merece confianza.

Aserciones: presupuestos que fallan el build

Una aserción es una regla con un nivel de severidad y un comparador. El nivel warn deja constancia sin romper nada; el nivel error devuelve un código de salida distinto de cero y, por tanto, tumba el build. El comparador suele ser maxNumericValue para métricas que quieres acotar por arriba —milisegundos de LCP, de total-blocking-time— o minScore para puntuaciones que quieres mantener por encima de un suelo. Hay tres familias de cosas que puedes aseverar, y usarlas bien es la diferencia entre una puerta útil y una que estorba.

Los presupuestos de recursos merecen fichero propio. El formato LightWallet describe, por patrón de ruta, cuántos kilobytes de cada tipo de recurso se toleran y cuántas peticiones. Es el complemento natural de size-limit: aquel mide el artefacto en tu build; este lo mide tal como lo carga el navegador, contando también imágenes, fuentes y terceros que el bundler ni ve.

// budget.json — presupuesto de recursos por tipo, estilo LightWallet
[
  {
    "path": "/*",
    "resourceSizes": [
      { "resourceType": "script", "budget": 170 },
      { "resourceType": "total", "budget": 500 }
    ],
    "resourceCounts": [
      { "resourceType": "third-party", "budget": 10 }
    ]
  }
]

Se conecta con el campo budgetsPath dentro de collect, y Lighthouse lo evalúa en cada corrida junto al resto de aserciones. La pieza que falta es engancharlo todo a un evento de pull request para que la puerta se cierre antes del merge, no después.

# .github/workflows/lhci.yml — Lighthouse en cada pull request
name: lhci
on: [pull_request]
jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci && npm run build
      - run: npx @lhci/cli autorun

flowchart TD
pr[Pull request] --> build[Construir el sitio]
build --> collect[lhci collect corre Lighthouse N veces]
collect --> assert[lhci assert compara con presupuestos]
assert --> gate{Alguna asercion en error}
gate -->|si| red[Build en rojo y merge bloqueado]
gate -->|no| up[lhci upload publica el informe]
style red fill:#f38ba8,color:#11111b
style up fill:#a6e3a1,color:#11111b

Estabilizar la señal y prevenir regresiones

Aquí está el escollo que hunde a la mayoría de las integraciones ingenuas: las métricas de laboratorio son ruidosas. Un mismo build, medido dos veces en el mismo runner, puede arrojar un TBT distinto porque la máquina virtual estaba más cargada, porque la recolección de basura cayó en otro momento, porque el arranque del proceso varió unos milisegundos. Si aseveras con error sobre una señal ruidosa, la puerta fallará al azar, el equipo aprenderá a reintentar el job sin mirar y habrás construido una alarma que todos silencian. La disciplina consiste en suprimir la varianza antes de poner la línea.

La primera palanca es la mediana de varias corridas: numberOfRuns de tres a cinco y quedarte con el valor central descarta los picos aislados. La segunda es el estrangulamiento simulado en lugar del aplicado —Lighthouse modela la CPU y la red por software en vez de depender del hardware del runner—, mucho más reproducible entre ejecuciones. La tercera es elegir bien sobre qué aseverar: las métricas concretas y de bajo ruido, como total-blocking-time, son puertas fiables; la puntuación compuesta de rendimiento salta varios puntos por cambios triviales y sirve mejor como aviso que como barrera.

Con la señal domada, la prevención de regresiones es la misma idea del trinquete de la lección anterior, ahora sobre comportamiento y no solo sobre bytes: fija los umbrales un pelo por encima de tu medición estable actual y, cada vez que una optimización mejore la métrica, baja el techo hasta el nuevo suelo. Conviene recordar el límite de la herramienta: Lighthouse CI es laboratorio, no campo. Atrapa regresiones causadas por tu código con reproducibilidad quirúrgica, pero no ve el dispositivo real de tu usuario. La pareja completa es esta puerta de laboratorio en cada PR para atribuir causas, y el RUM de la lección anterior para conocer la verdad en producción.

Ninguna columna sustituye a la otra: la puerta de CI te deja afirmar que un cambio concreto empeoró el TBT, y el campo te confirma si eso les importa a tus usuarios. Un pipeline maduro usa el laboratorio como filtro barato y temprano, y reserva el campo como juez último de si la métrica que defiendes es la que de verdad viven.