YAML-based Accessibility Testing Configuration

Automated accessibility testing tools need to know what to check, where to check it, and how strictly to apply the rules. A YAML-based configuration file provides these instructions in a human readable format. YAML (YAML Ain't Markup Language) is a data serialization language that uses indentation and simple key-value pairs, making it easier to read and maintain than JSON or XML for configuration purposes.

In practice, these configuration files sit at the root of a project or within a CI/CD pipeline definition. They specify which WCAG conformance levels to target (A, AA, or AAA), which specific success criteria to include or exclude, which URLs or URL patterns to audit, and what thresholds determine whether a build passes or fails. Tools like axe, Pa11y, and various CI integrations accept YAML configuration to control their behavior.

Why YAML-based accessibility testing configuration matters

Without a configuration file, accessibility audits typically run with default settings. Defaults are a reasonable starting point, but they rarely match the specific requirements of a project. A government website legally required to meet WCAG 2.1 Level AA needs different settings than an internal dashboard where the team is progressively addressing Level A issues first.

Configuration files make accessibility testing reproducible. Every developer on a team runs the same checks with the same rules. When the configuration lives in version control alongside the source code, changes to testing rules are tracked, reviewed, and approved through the same process as code changes.

Teams also use configuration to suppress known false positives or to temporarily ignore issues that are being addressed in a future sprint. Without this ability, noisy test results lead to alert fatigue, and developers start ignoring accessibility reports entirely.

For organizations running accessibility audits at scale across many sites or applications, a shared YAML configuration template ensures consistent standards. Individual projects can extend or override the base configuration as needed.

How YAML-based accessibility testing configuration works

Structure and common fields

A typical configuration file includes sections for target URLs, the WCAG conformance level, specific rules to enable or disable, output format preferences, and thresholds. The exact schema depends on the tool, but the concepts are consistent across most accessibility testing frameworks.

Integration with CI/CD pipelines

The configuration file is read by the testing tool during a pipeline run. If the audit results exceed the configured error threshold, the pipeline fails and blocks deployment. This prevents accessibility regressions from reaching production.

Rule customization

Most tools map their internal rules to specific WCAG success criteria. The configuration file can reference these mappings to enable only the criteria relevant to the project's compliance target. For example, a team targeting Level AA would disable AAA-only rules to reduce noise.

Page and component scoping

Configuration files can specify which pages to test using URL lists or patterns. Some tools also support CSS selectors to include or exclude specific regions of a page, which is useful when third party widgets fall outside the team's control.

Code examples

The following examples show a poorly structured configuration and a well structured one for a hypothetical accessibility testing tool.

Bad example: no configuration (relying on defaults)

# Empty or missing configuration file
# The tool runs with all default rules, no URL targeting,
# and no threshold — every warning and notice floods the output.

Running without configuration means the tool tests whatever page it is pointed at with every rule enabled. Results are noisy, inconsistent across environments, and hard to act on.

Bad example: overly permissive configuration

accessibility:
  level: "A"
  threshold: 500
  ignore:
    - "*"

Setting the threshold to 500 errors and ignoring all rules defeats the purpose of automated testing. This configuration will never fail a build regardless of how many accessibility issues exist.

Good example: targeted WCAG 2.1 Level AA configuration

accessibility:
  standard: "WCAG2.1"
  level: "AA"
  urls:
    - "https://example.com/"
    - "https://example.com/contact"
    - "https://example.com/products"
  threshold:
    error: 0
    warning: 10
  rules:
    enable:
      - "color-contrast"
      - "image-alt"
      - "label"
      - "link-name"
      - "heading-order"
    disable:
      - "region"  # Third-party widget region; tracked in issue #432
  output:
    format: "json"
    file: "reports/a11y-results.json"
  viewport:
    width: 1280
    height: 720

This configuration targets a specific standard and conformance level, lists the pages to test, sets a zero tolerance threshold for errors while allowing some warnings, enables specific rules that match the project's compliance goals, and documents why a rule is disabled. The output section ensures results are saved in a machine readable format for further processing.

Good example: HTML page that passes the configured rules

The configuration above enables the image-alt, label, and link-name rules among others. Here is an HTML snippet that would pass those checks:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Products - Example</title>
</head>
<body>
  <h1>Our products</h1>
  <img src="widget.jpg" alt="Blue widget with ergonomic grip">
  <form action="/search" method="get">
    <label for="search-input">Search products</label>
    <input type="text" id="search-input" name="q">
    <button type="submit">Search</button>
  </form>
  <a href="/contact">Contact our sales team</a>
</body>
</html>

Every image has descriptive alt text, form inputs have associated label elements, and the link has meaningful text content. These are the specific checks the YAML configuration has enabled, so this page would produce zero errors in the audit report.

Bad example: HTML page that fails the configured rules

<!DOCTYPE html>
<html>
<head>
  <title>Products</title>
</head>
<body>
  <h1>Our products</h1>
  <img src="widget.jpg">
  <form action="/search" method="get">
    <input type="text" name="q">
    <button type="submit">Search</button>
  </form>
  <a href="/contact"></a>
</body>
</html>

The html element is missing a lang attribute. The image has no alt attribute. The text input has no associated label. The anchor element has no text content. With the threshold set to zero errors, this page would fail the audit and block deployment until the issues are fixed.