Español
Menú del sitio

Integración con CI

Plantillas listas para pegar que envuelven la CLI (npx @surea11y/cli scan ...) en GitHub Actions, Bitbucket Pipelines, GitLab CI y Azure DevOps. Si llamas a la librería directamente desde tu propio script de Node en lugar de usar la CLI, consulta en su lugar INTEGRATION.md: esta página trata específicamente sobre la CLI como paso del pipeline de CI.

La CLI analiza HTML estático: no ejecuta el JavaScript de la página. Eso sirve para páginas compiladas o renderizadas en el servidor; para una aplicación renderizada en el cliente, o reglas que necesitan el layout, analiza en un navegador con una de las integraciones de navegador.

Todas estas plantillas utilizan los códigos de salida de la CLI (0 si no se encuentran fallos, 1 si existe al menos un resultado fail (o uno nuevo al utilizar --baseline) y 2 si se produce un error de uso o de análisis) para controlar el pipeline de CI; no se necesita scripting adicional para un control básico de aprobado/fallido. Un pipeline en verde significa que ninguna comprobación falló, o que no falló ninguna nueva. No es una declaración de conformidad, y los hallazgos cantTell no lo hacen fallar.

GitHub Actions

Básico: controlar según el código de salida

name: Accessibility scan
on: [pull_request]
 
jobs:
  a11y-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci && npm run build   # produce whatever static HTML you're scanning
      - run: npx @surea11y/cli scan ./dist/index.html

Esto hace que el job falle en el momento en que se encuentra cualquier resultado fail. Para un sitio existente con violaciones preexistentes, consulta la variante con baseline más abajo en lugar de deshabilitar el paso.

Con un baseline (sitio existente, controlar solo las violaciones nuevas)

# Once, locally: record every current fail occurrence, commit the file.
$ surea11y scan ./dist/index.html --write-baseline a11y-baseline.json
$ git add a11y-baseline.json
      - run: npm ci && npm run build
      - run: npx @surea11y/cli scan ./dist/index.html --baseline a11y-baseline.json

Un baseline evita que las violaciones conocidas hagan fallar la compilación; no las hace aceptables. Corrígelas y reduce el archivo con el tiempo. Consulta Baseline / allowlist para ver qué cuenta como "conocido" frente a "nuevo", y cómo regenerar el archivo a medida que se corrigen violaciones.

Subir SARIF a GitHub Code Scanning

upload-sarif necesita el permiso security-events: write y no hace fallar el job por sí mismo: combínalo con un paso de control independiente (o continue-on-error + tu propia comprobación) si también quieres que la compilación falle ante violaciones nuevas.

Los hallazgos que tienden a fallo son alertas warning por defecto. Generados con renderSarifReport(result, { leanFailAs: 'error' }) desde @surea11y/core/sarif, son error, así que un control sobre los errores se detiene también ante los fallos probables (opciones de SARIF); un baseline escrito con buildBaselineEntries(result, { leanFail: true }) acepta los que una página ya tiene (hallazgos que probablemente fallan).

name: Accessibility scan
on: [pull_request]
 
permissions:
  contents: read
  security-events: write
 
jobs:
  a11y-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci && npm run build
      - name: Scan (report, don't fail the job here)
        run: npx @surea11y/cli scan ./dist/index.html --baseline a11y-baseline.json --sarif results.sarif
        continue-on-error: true
        id: scan
      - name: Upload SARIF to Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif
      - name: Fail the job on new violations
        if: steps.scan.outcome == 'failure'
        run: exit 1

Consulta el formato del informe SARIF y una limitación conocida: un análisis de un archivo local en tu checkout obtiene anotaciones en línea en la interfaz de Code Scanning; un análisis de una URL en vivo no las obtiene (SARIF/Code Scanning solo puede asociar un hallazgo con un archivo real del repositorio).

Publicar lo que el análisis deja a una persona

Una puerta decide lo que las reglas pueden decidir. Para entregar el resto a una persona en cada ejecución, escribe el informe HTML y una hoja de trabajo de las comprobaciones que ninguna regla decide por completo (--manual-checks, @surea11y/cli 1.5.0 y core 1.15.0 y posteriores), y sube ambos como un artefacto. Ninguno de los dos cambia el código de salida. Ver Procedimientos de prueba.

      - run: npx @surea11y/cli scan ./dist/index.html --html reports/report.html --manual-checks reports/manual-checks.html
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: accessibility
          path: reports/

Bitbucket Pipelines

Bitbucket Pipelines no tiene un panel integrado que consuma SARIF equivalente a GitHub Code Scanning, así que el código de salida de la CLI (más, opcionalmente, --html como artefacto descargable del pipeline de CI) es el punto de integración práctico en lugar de --sarif.

pipelines:
  pull-requests:
    '**':
      - step:
          name: Accessibility scan
          image: node:22
          script:
            - npm ci
            - npm run build
            - npx @surea11y/cli scan ./dist/index.html --baseline a11y-baseline.json --html a11y-report.html
          artifacts:
            - a11y-report.html

El paso hace fallar el pipeline de CI según el código de salida de la CLI, exactamente igual que cualquier otra entrada de script; a11y-report.html (consulta el informe HTML) se adjunta como artefacto de compilación descargable para que quien revise pueda abrirlo sin volver a ejecutar el análisis localmente.

Informes de pruebas JUnit

GitLab, Azure DevOps, Jenkins y CircleCI muestran JUnit XML en sus propias vistas de pruebas: cada criterio de WCAG se convierte en una suite y cada regla en una prueba (ver el informe JUnit). La CLI lo escribe con --junit <path> (@surea11y/cli 1.1.0 o posterior), a partir del mismo análisis que sus demás salidas, y el informe nunca cambia su código de salida, así que el paso sigue controlando la compilación.

GitLab CI

a11y:
  image: node:22
  script:
    - npm ci
    - npm run build
    - npx @surea11y/cli scan ./dist/index.html --junit a11y.junit.xml
  artifacts:
    when: always
    reports:
      junit: a11y.junit.xml

when: always sube el informe incluso cuando el código de salida del análisis hace fallar el trabajo, que es justo cuando merece la pena leer el widget de la merge request.

Azure DevOps

steps:
  - script: |
      npm ci
      npm run build
      npx @surea11y/cli scan ./dist/index.html --junit a11y.junit.xml
    displayName: Accessibility scan
  - task: PublishTestResults@2
    condition: succeededOrFailed()
    inputs:
      testResultsFormat: JUnit
      testResultsFiles: a11y.junit.xml

Las reglas cantTell llegan como pruebas omitidas, nunca como fallos. Con --baseline, los fallos que ya están en el baseline también son pruebas omitidas. Para mostrar las reglas cantTell como fallos, la CLI no tiene opción: guarda el análisis con --json y genera el informe con renderJunitReport(result, { cantTellAs: 'failure' }) de @surea11y/core/junit (ver el informe JUnit), que necesita @surea11y/core en las devDependencies del propio proyecto. { leanFailAs: 'failure' } es la opción más estrecha: solo los hallazgos cantTell que tienden a fallo pasan a ser fallos, cada uno con el porqué y los pasos para confirmarlo. Cualquiera de las dos cambia el informe, no el código de salida de la CLI.

Límites de minutos en el nivel gratuito/repos privados

Si el nivel gratuito de tu proveedor de pipelines de CI tiene un límite de minutos (el nivel gratuito de Bitbucket Pipelines es de 50 minutos de compilación al mes en workspaces privados, por ejemplo), un análisis basado en jsdom de HTML estático/renderizado en el servidor (lo que hace la CLI) es mucho más económico que controlar un navegador real mediante automatización. Consulta la documentación de la CLI para ver qué se sacrifica con eso (sin contenido renderizado en el cliente ni un motor de diseño CSS real).