# Docker-Based Pipeline Execution for Accessibility Scans

This blueprint is part of CI/CD Integration & Automated Quality Gating, and it solves the single most corrosive problem in automated accessibility testing: non-reproducible browser environments. When a scan passes on a developer laptop but fails on the CI runner — or worse, flips between green and red across runs — the root cause is almost always a drifting Chromium version, a mismatched font stack, or an unpinned runtime. Containerizing the scan locks every layer of that stack so the same DOM renders identically everywhere.

A reproducible accessibility container pins the browser binary, the runtime, and the rendering dependencies, then ships them as immutable image layers your CI runner pulls on every job. Whether you drive the scan with axe-core, Lighthouse CI, or a custom Playwright runner, the container guarantees that WCAG 2.2 SC evaluations execute against a known-good render tree.

Key implementation targets:

• Pin an exact Chromium/Chrome build so contrast and reflow checks (WCAG 2.2 SC 1.4.3, 1.4.10) stay deterministic
• Resolve headless sandbox flags correctly for unprivileged CI containers
• Order Dockerfile layers so dependency and browser-binary caches survive code changes
• Split build and scan into multi-stage builds to keep the runtime image lean

# Prerequisites

• Docker Engine 24+ with BuildKit enabled (DOCKER_BUILDKIT=1)
• A CI provider that can run container jobs (GitHub Actions, GitLab CI, or similar)
• An accessibility runner chosen — @axe-core/cli, @axe-core/playwright, or Lighthouse CI
• A pinned base image digest recorded (e.g. node:20.11.1-bookworm-slim)
• A registry to push/pull the built image (GHCR, ECR, or your provider’s cache)

# 1. Pin the Base Image and Runtime

Reproducibility starts with refusing floating tags. node:20 silently advances; pin a patch version, and for true immutability, pin the digest. The same applies to the browser — never let apt-get install chromium resolve to “whatever is current,” because a contrast-ratio threshold can shift by a sub-pixel of anti-aliasing between Chromium builds and flip a WCAG 2.2 SC 1.4.3 result.

# syntax=docker/dockerfile:1.7
# Pin the patch version; optionally append @sha256:... for digest-level immutability.
FROM node:20.11.1-bookworm-slim AS base

# Pin the Chromium/Chrome version explicitly. Do NOT use unversioned installs.
ENV CHROME_VERSION=124.0.6367.91
ENV DEBIAN_FRONTEND=noninteractive

# 2. Install Headless Browser Dependencies

A headless Chromium needs a specific set of shared libraries to render text, SVG, and form controls the way a real browser does — omit them and your scan evaluates a degraded render tree, producing false passes on focus and contrast rules. Install them in their own layer so they cache independently of your application code.

# Browser system dependencies live in their own cached layer.
RUN apt-get update && apt-get install -y --no-install-recommends \
      ca-certificates fonts-liberation libnss3 libatk1.0-0 \
      libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 \
      libxdamage1 libxfixes3 libxrandr2 libgbm1 libpango-1.0-0 libasound2 \
    && rm -rf /var/lib/apt/lists/*   # drop apt cache to keep the layer small

# 3. Order Layers for Maximum Cache Reuse

Docker invalidates every layer after the first changed one. If you COPY . . before installing dependencies, every source edit busts your npm ci and browser-download layers, adding minutes to each scan. Copy only the lockfiles first, install, then copy the source. This is the single highest-leverage change for scan job speed.

WORKDIR /app

# Copy only manifests first so npm ci is cached until dependencies change.
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci   # BuildKit cache mount reuses the npm download cache across builds

# Source copied last: editing app code does not invalidate the install layer.
COPY . .
RUN npm run build

# 4. Use a Multi-Stage Build for a Lean Scan Image

The build stage pulls in compilers and dev dependencies you never need at scan time. A second stage copies only the built artifacts and the runtime, producing a smaller image that pulls faster on every CI job. The browser binaries managed by Playwright are copied across so they are not re-downloaded.

FROM base AS scanner
WORKDIR /app

# Carry over installed deps and Playwright browsers from the build stage.
COPY --from=base /app/node_modules ./node_modules
COPY --from=base /root/.cache/ms-playwright /root/.cache/ms-playwright
COPY --from=base /app/dist ./dist
COPY --from=base /app/scripts ./scripts

# Non-root user: headless Chromium runs without --no-sandbox where possible.
RUN useradd -m scanuser
USER scanuser

ENTRYPOINT ["node", "scripts/run-a11y-scan.mjs"]

# Pipeline Integration

The container becomes a single step in your gating workflow. Build (or pull) the image, then run it with the scan output mounted back to the host so the CI job can archive it and annotate the pull request. The container’s exit code is the gate: a non-zero code from the scan script fails the job.

name: a11y-docker
on: pull_request
jobs:
  containerized-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build scan image (cached)
        run: DOCKER_BUILDKIT=1 docker build -t a11y-scan:ci .
      - name: Run scan, export report
        run: |
          docker run --rm \
            -v "$PWD/reports:/app/reports" \
            a11y-scan:ci > reports/a11y.json   # non-zero exit fails the gate
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: a11y-report
          path: reports/a11y.json

For severity-based gating that fails only on critical and serious violations, wire the container’s output into the patterns described in Auto-Fail vs Warning Workflows. Two focused walkthroughs cover the most common runners: running Lighthouse CI in a Docker-based pipeline and caching axe-core browser binaries in CI containers.

# Troubleshooting & Flaky-Test Mitigation

The dominant flake source in containers is timing: the scan runs before the app’s render is stable. Inside the container, always wait for networkidle or a stable landmark before invoking the scan, and serve the built output over HTTP rather than scanning file paths. A second class of flake comes from font availability — if fonts-liberation is missing, text metrics shift and reflow checks (WCAG 2.2 SC 1.4.10) become non-deterministic.

When a scan crashes immediately with a Chromium namespace error, the runner lacks the privileges Chromium’s sandbox needs. Prefer fixing the runner (allowing user namespaces) over disabling the sandbox, but if you must, scope --no-sandbox to the scan process only and document it as a known caveat.

# Common Pitfalls

• Floating base tags: node:20 and chromium (unversioned) drift between runs. Pin patch versions and ideally digests so WCAG evaluations stay reproducible.
• COPY . . before install: This busts the dependency cache on every source edit. Copy lockfiles first.
• Blanket --no-sandbox: Disabling the sandbox image-wide is a security regression. Fix runner privileges, or scope the flag narrowly.
• Re-downloading browsers at scan time: If Playwright/Puppeteer binaries are not baked into a layer, every job re-fetches ~150 MB. Cache them in the image.
• Scanning before hydration: Containers do not magically fix race conditions; wait for a stable DOM before evaluating.

# FAQ

Why containerize accessibility scans at all instead of using the CI runner’s browser? Hosted runners update their pre-installed browsers on their own cadence, which means a passing scan can silently break when the runner image rolls forward. A pinned container freezes the exact Chromium build, fonts, and runtime, so contrast, reflow, and focus evaluations stay identical across every run and every developer machine.

Should I pin the Chromium version or let Playwright manage it? Let Playwright manage the binary, but pin the Playwright package version in your lockfile — each Playwright release bundles a specific Chromium build, so a pinned Playwright transitively pins the browser. Bake those downloaded binaries into an image layer so they are cached rather than re-fetched per job.

Does multi-stage building actually speed up the scan job? Yes, on the pull side. The scan stage ships only runtime dependencies and built artifacts, so the image the CI runner pulls is smaller and starts faster. The build stage’s compilers and dev dependencies never reach the runner.

# Related

• CI/CD Integration & Automated Quality Gating — the parent section covering gating strategy end to end.
• Running Lighthouse CI in a Docker-Based Pipeline — a full Dockerfile and lhci autorun walkthrough.
• Caching axe-core Browser Binaries in CI Containers — cache-key strategy to cut scan time.
• Auto-Fail vs Warning Workflows — turning the container’s exit code into a merge gate.