Configuring Audits

The Audit.run function takes an optional configuration object as a second argument to fine-tune the audit. This page gives 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 not be absent from any reporting, notably the Page Report. If you wish to see all found issues but, e.g., only fail the test for some critical ones, the filtering must occur as part of custom gatekeeping checks.

Including iframe content

By default, content of iframes is not included in the audit, as this is often 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, 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 instead the Rules.wcag20aaFilter or Rules.wcag21aaFilter filters.

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 (e.g., these test pages do not need a skip link and often have 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 has to be found from Alfa technical documentation, it is the number in the SIA-RXX identifier. These ids can also be found from Alfa's implementation report in the description before the implementation table of each ACT rule.

In some cases, it might be beneficial to only run 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 waits for designers to decide on new colors), thus excluding this rule will unclutter the result and allow focusing on the immediately actionable issues.

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

Focusing Outcomes

When different parts of the page are under the responsibility of different teams, it can be beneficial to let each one focus on the relevant bit. 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 this will only report issues inside a <nav class="global"> element, e.g., 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 given element, but we want to ignore it temporarily because the fix is not the highest priority. In environments where tests fail if there is any accessibility issue, or to reduce visual clutter, it is often simpler to disregard these results altogether:

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