CI Runner

The @frontend-debugger/ci package provides fd-ci, a CI-oriented runner that executes multiple audits and outputs structured reports.

Installation

npm install -g @frontend-debugger/ci
# or use npx
npx @frontend-debugger/ci <url> [options]

Usage

# HTML report (default)
fd-ci http://localhost:3000 --report report.html

# JUnit XML for test reporting
fd-ci http://localhost:3000 --format junit --report results.xml

# SARIF for GitHub Code Scanning
fd-ci http://localhost:3000 --format sarif --report results.sarif

# With design tokens and visual diff
fd-ci http://localhost:3000 --tokens tokens.json --diff homepage

# Skip specific checks
fd-ci http://localhost:3000 --skip-a11y --skip-contrast

# Upload report to a self-hosted server and get a shareable URL
fd-ci http://localhost:3000 --report report.html --host-url https://reports.uiprobe.dev

Report formats

HTML

Styled report with sections for each audit type. Includes severity badges, code snippets, and pass/fail counts.

JUnit XML

Standard JUnit format compatible with GitHub Actions test annotations, Jenkins, CircleCI, and other CI systems.

<testsuites tests="42" failures="3">
  <testsuite name="a11y" tests="35" failures="2">
    <testcase name="button-name">
      <failure>Buttons must have discernible text</failure>
    </testcase>
  </testsuite>
</testsuites>

SARIF 2.1.0

Static Analysis Results Interchange Format. Upload to GitHub Code Scanning for inline PR annotations.

# .github/workflows/audit.yml
- name: Run frontend audit
  run: npx @frontend-debugger/ci ${{ env.URL }} --format sarif --report results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Checks

Check	Flag to skip	What it runs
Accessibility	--skip-a11y	axe-core audit
Contrast	--skip-contrast	WCAG AA contrast
ARIA	--skip-aria	ARIA validation
Tokens	requires --tokens <file>	Design token drift
Visual diff	requires --diff <name>	Baseline comparison
Hosted report	--host-url <url>	Upload HTML to self-hosted server, emit shareable URL

Configuration

fd-ci reads fd.config.json from the project root:

{
  "chrome": {
    "port": 9222,
    "host": "localhost"
  },
  "tokensFile": "tokens.json",
  "baseline": "homepage",
  "skip": ["contrast"]
}

CLI arguments override config file values.

Exit codes

• 0 — all checks pass
• 1 — one or more violations found
• Use --no-fail to always exit 0 (useful for informational runs)

Hosted reports

Pass --host-url to upload the HTML report to a self-hosted fd-host server and receive a permanent shareable URL:

FD_HOST_TOKEN=<token> fd-ci https://staging.example.com \
  --report report.html \
  --host-url https://reports.uiprobe.dev
# → Report hosted at: https://reports.uiprobe.dev/r/550e8400-...

When running inside GitHub Actions the URL is also written to $GITHUB_OUTPUT as report-url.

GitHub Actions example

name: Frontend Audit
on: [pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Start app
        run: npm start &
        env:
          PORT: 3000

      - name: Wait for app
        run: npx wait-on http://localhost:3000

      - name: Launch Chrome
        uses: browser-actions/setup-chrome@v1

      - name: Run audit
        run: npx @frontend-debugger/ci http://localhost:3000 --format sarif --report audit.sarif

      - name: Upload results
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: audit.sarif