Using Global Configurations

Overview of Global Configurations

The Global panel of axe Configuration provides a centralized way to manage and control accessibility testing settings across your organization. This powerful feature allows enterprise administrators to establish consistent testing standards while giving individual teams and developers the flexibility they need to work effectively.

What are Global Configurations?

Global configurations (the Global tab of axe Configuration) are a set of controls that determine how axe Developer Hub operates during accessibility testing. These settings include:

• Which accessibility standards to test against (such as WCAG 2.1 AA or EN 301 549)
• Whether to include best practices checks
• Whether to enable experimental rules
• Which version of axe-core to use for testing

These settings can be managed at both the enterprise and individual user level, creating a flexible but controlled testing environment.

Why Use Global Configurations?

Global configurations solve several common challenges in enterprise accessibility testing:

• Consistency: Ensure all teams are testing against the same accessibility standards
• Compliance: Enforce specific testing requirements across your organization
• Flexibility: Allow teams to customize their testing approach within approved parameters
• Version Control: Manage which axe-core versions can be used across projects
• Quality Assurance: Maintain testing standards while enabling team-specific optimizations

How Global Configurations Work

Administrators

Administrators set organization-wide defaults and define which settings users can modify via the configurationOverrides option. These settings establish the baseline for axe Developer Hub testing within the organization. These settings are changed in the Global panel of axe Configuration.

Users

Instead of using the Global panel, individual users customize their testing configuration by changing or adding the configurationOverrides option in their testing setup code. The configurationOverrides option interacts with the settings in the Global panel as defined in the table in Common Global Configuration and Configuration Override Scenarios.

The API reference includes more information about configurationOverrides and its properties.

Common Global Configuration and Configuration Override Scenarios

When a test runs, axe Developer Hub merges enterprise and user settings to create the final testing configuration. This ensures all customizations remain within approved parameters while giving users the necessary flexibility.

The following table illustrates common scenarios you'll encounter when working with global configurations. Each scenario shows how enterprise settings interact with your project configuration.

Understanding the Results

• ✅ Success: Configuration works as expected
• ⚠️ Warning: Configuration works but isn't recommended
• ❌ Error: Configuration will fail

Recommendations

1. Always prefer configurationOverrides over runOptions.
2. Check your enterprise settings before configuring overrides.
3. Only override settings when necessary.
4. Use the most straightforward configuration that meets your needs.

Example Configuration Override

Here's an example configuration that demonstrates overrides to follow WCAG 2.1 AA and best practices:

const config = {
  axe: {
    apiKey: 'YOUR_API_KEY',

    configurationOverrides: {
      accessibilityStandard: 'WCAG 2.1 AA',
      axeCoreVersion: '4.9.1',
      experimentalRules: true,
      bestPractices: true
    }
};

See ConfigurationOverrides Interface for an explanation of the properties.

Errors and Warnings

Errors

Not-Permitted Standard

If you try to use a standard that is not permitted, you will receive a server response code 422, Unprocessable Content. Example message:

Error: Server responded to https://axe.deque.com/api-pub/watcher/sessions with status code 422: "error": "Invalid accessibility standard: WCAG 2.0 AA. Allowed options: EN 301 549, Trusted Tester v5"

Using runOptions.runOnly with configurationOverrides

If you use both runOptions.runOnly with configurationOverrides, your tests will immediately fail. Use only configurationOverrides.

Warnings

Using runOptions.runOnly

If you use runOptions.runOnly in your configuration, you will receive this warning message:

@axe-core/watcher Without Global Configuration Support

If you use a version of @axe-core/watcher that is too old to have global configuration support, you will receive this message:

See Also

• axe Configuration
• configurationOverrides reference