Building an Automated QA CI/CD Pipeline

Technical Deep Dive & Specifications

The Enterprise Quality Pyramid for HTML

The Complete GitHub Actions Workflow (.github/workflows/html-qa.yml)

name: 'HTML Quality Assurance Pipeline'

on:
  push:
    branches: [main, master, develop]
  pull_request:
    branches: [main, master, develop]

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  # -------------------------------------------------------------
  # Job 1: Static Quality Gates (Format, Lint & Spec Validation)
  # -------------------------------------------------------------
  static-qa:
    name: 'Static Markup Validation'
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - name: Checkout Source Code
        uses: actions/checkout@v4

      - name: Setup Node.js Environment
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Setup Java JRE (for Nu Validator)
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: Install Dependencies
        run: npm ci

      - name: 1. Verify Code Formatting (Prettier)
        run: npx prettier --check "**/*.html"

      - name: 2. Run HTMLHint Static Analysis
        run: npx htmlhint "**/*.html" --config .htmlhintrc

      - name: 3. Run Markuplint Spec & AST Analysis
        run: npx markuplint "src/**/*.{html,jsx,tsx,vue,svelte}"

      - name: 4. Run W3C Nu HTML Validator
        run: npx vnu --format gnu --errors-only dist/

  # -------------------------------------------------------------
  # Job 2: Dynamic Accessibility & E2E Verification
  # -------------------------------------------------------------
  accessibility-audit:
    name: 'Automated WCAG 2.1 AA Audits (axe-core)'
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout Source Code
        uses: actions/checkout@v4

      - name: Setup Node.js Environment
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Install Dependencies
        run: npm ci

      - name: Install Playwright Headless Browsers
        run: npx playwright install --with-deps chromium

      - name: Build Static Production Site
        run: npm run build

      - name: Execute axe-core E2E Test Suite
        run: npx playwright test tests/accessibility.spec.ts

      - name: Upload Playwright Test Report Artifact
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-accessibility-report
          path: playwright-report/
          retention-days: 14

Pipeline Optimization Strategies

1. Dependency Caching: cache: 'npm' in actions/setup-node caches ~/.npm across workflow runs, reducing setup time from 45 seconds to 3 seconds.
2. Concurrency Cancellation: cancel-in-progress: true automatically cancels running CI jobs on outdated commits when a developer pushes a new commit to an open Pull Request.
3. Artifact Retention: actions/upload-artifact saves detailed HTML test reports only when failures occur (if: failure()), minimizing cloud storage costs.

💻 Interactive Code Playground

Production package.json Quality Scripts

Below is the complete scripts block for package.json that connects every tool learned throughout Chapter 93 into unified commands:

Starter Code (package.json)

Line-by-Line Code Breakdown

• Line 6 (format:check): Runs non-destructive Prettier checks for CI.
• Line 7 (format:write): Auto-formats files locally.
• Line 8 (lint:hint): Scans HTML files using project-level .htmlhintrc rules.
• Line 9 (lint:markup): Runs AST-based spec and ARIA checks on multi-framework components.
• Line 10 (validate:spec): Runs official W3C Nu HTML Validator against compiled build output in dist/.
• Line 11 (test:a11y): Runs headless Chromium Playwright tests with axe-core WCAG assertions.
• Line 12 (qa:all): Chained unified command running all five verification steps sequentially.

{
  "name": "enterprise-html-suite",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "format:check": "prettier --check \"**/*.html\"",
    "format:write": "prettier --write \"**/*.html\"",
    "lint:hint": "htmlhint \"**/*.html\" --config .htmlhintrc",
    "lint:markup": "markuplint \"src/**/*.{html,jsx,tsx,vue,svelte}\"",
    "validate:spec": "vnu --format gnu --errors-only dist/",
    "test:a11y": "playwright test tests/accessibility.spec.ts",
    "qa:all": "npm run format:check && npm run lint:hint && npm run lint:markup && npm run validate:spec && npm run test:a11y",
    "prepare": "husky"
  },
  "devDependencies": {
    "@axe-core/playwright": "^4.8.0",
    "@markuplint/jsx-parser": "^4.0.0",
    "@playwright/test": "^1.40.0",
    "htmlhint": "^1.1.4",
    "husky": "^9.0.0",
    "lint-staged": "^15.0.0",
    "markuplint": "^4.0.0",
    "prettier": "^3.2.0",
    "vnu-jar": "^23.4.11"
  }
}