Configuring audits

The Audit.run function takes an optional configuration object as a second argument to fine-tune the audit. This page provides some quick common setups to use. See the advanced configuration for more details. All options can be combined together as needed.

Note: Rules or outcomes that are filtered out at audit time will also be absent from any reporting, notably the Page Report. If you want to see all identified issues but only fail the test for certain critical ones, the filtering must occur as part of your custom gatekeeping checks.

Including iframe content

By default, content of iframes is not included in the audit, because it often consists of third-party content or separate pages that can be checked individually. To include it, set the includeIframes option to true:

import { Audit, Rules } from "@siteimprove/alfa-test-utils";

const alfaResult = await Audit.run(alfaPage, {
  outcomes: { includeIframes: true },
});

Note that even if the option is set to true, the content of iframe will not be included in the Siteimprove Intelligence Platform page report.

Selecting rules by conformance

The most common setup is likely to only run the rules for WCAG AA conformance (level A and AA criteria):

import { Audit, Rules } from "@siteimprove/alfa-test-utils";

const alfaResult = await Audit.run(alfaPage, {
  rules: { include: Rules.aaFilter },
});

This selects all the rules that test for level A or AA criteria of WCAG 2.2. If an older version of WCAG is required use the Rules.wcag20aaFilter or Rules.wcag21aaFilter filters instead.

Similarly, rules checking for conformance with ARIA specifications can be selected with Rules.ARIAFilter while rules checking for best practices can be selected with Rules.bestPracticesFilter.

Selecting by scope

Another common case is to test design systems by building pages with individual components. Several rules make little sense in that context (such as these test pages not needing a skip link and often having no title).

import { Audit, Rules } from "@siteimprove/alfa-test-utils";

const alfaResult = await Audit.run(alfaPage, {
  rules: { include: Rules.componentFilter },
});

Cherry-picking and excluding rules by their ID number

The rule ID number must be found from Alfa technical documentation. It is the number in the SIA-RXX identifier. These IDs can also be found in Alfa's implementation report in the description before the implementation table of each ACT rule.

In some cases, it might be beneficial to run only a handful of selected rules:

import { Audit, Rules } from "@siteimprove/alfa-test-utils";

const alfaResult = await Audit.run(alfaPage, {
  rules: { include: Rules.cherryPickFilter(2, 42, 68) },
});

Another common case is to exclude a few rules. For example, there could be a known color contrast issue that cannot be fixed immediately and is waiting for designers to decide on new colors. Excluding this rule will unclutter the results and allow you to focus on the immediately actionable issues.

const alfaResult = await Audit.run(page, {
  rules: {
    include: Rules.aaFilter,
    exclude: Rules.cherryPickFilter(69)
  },
});

Filtering the outcomes

When different parts of the page are the responsibility of different teams, it can be beneficial to let each team focus on the relevant section. This is done by filtering the outcomes of the audit.

import { Audit, Outcomes } from "@siteimprove/alfa-test-utils";

const alfaResult = await Audit.run(alfaPage, {
  outcomes: {
    include: Outcomes.insideSelectorFilter("nav.global")
  },
});

The Outcomes.insideSelectorFilter filter takes a CSS selector as an argument and matches all the outcomes that are inside an element matching this selector. In this case, it will only report issues inside a <nav class="global"> element, such as a global navigation menu.

Similarly, it may be useful to exclude occurrences inside a given container:

import { Audit, Outcomes } from "@siteimprove/alfa-test-utils";

const alfaResult = await Audit.run(alfaPage, {
  outcomes: {
    exclude: Outcomes.insideSelectorFilter("nav.global")
  },
});

Excluding specific outcome

In some cases, there is a known error for a given rule on a specific element, but we want to ignore it temporarily because the fix is not the highest priority. In environments where tests fail due to any accessibility issue, it is often simpler to disregard these results altogether to reduce visual clutter:

import { Audit, Outcomes } from "@siteimprove/alfa-test-utils";

const alfaResult = await Audit.run(alfaPage, {
  outcomes: {
    exclude: Outcomes.ruleAndSelectorFilter(66, "span#secret")
  },
});

This excludes the AAA color contrast rule on the element matching the given selector.

Previous: ReportingNext: Advanced audit configuration