API

Static method

AccessibilityAuditor#userwayAnalysis(AuditConfig config): AnalysisResult

Runs analysis on the current page and returns result object that contains information about violations, that were found on the page.

Default configs (you may not create AnalysisConfig instance if you need default static analysis configuration):

var analysisConfig = AnalysisConfig.builder()
        .level(Level.AA) // Scans only for A- and AA-violation levels
        .switchOff(false) // Analysis will not be performed at all if set to true
        .build();
 
var auditConfig = AuditConfig.builder()
        .saveReport(true) // Saves JSON-report for CA11Y
        .elementScreenshots(false) // Does not take screenshots
        .strict(false) // Does not fail if violations were found
        .build();

Full configs:

public class AnalysisConfig {
    private Set<Rule> includeRules; // Accessibility guidelines' rules that should be checked on your website
    private Set<Rule> excludeRules; // Accessibility guidelines' rules that should NOT be checked on your website
    private Boolean includeBestPractices; // Whether to show our web content recommendations for your website or not
    private Boolean includeExperimental; // Whether to show our beta-tested accessibility rules
    private Level level; // Specify violations of which level should be searched by analysis
    private Set<String> ignoreSelectors; // Specify list of CSS-selectors (ids, classes etc.) that should be ignored by analysis
    private Boolean switchOff; // Turn off analysis, if you do not need it at the moment for some reason
}
 
public class AuditConfig {
    private WebDriver driver; // Provide your configured WebDriver with already loaded page
    private Duration auditTimeout; // Maximal amount of time UserWay analysis can be executed on page
    private AnalysisConfig analysisConfiguration; // Provide configuration for UserWay static analysis script
    private boolean saveReport; // Whether JSON-report with violations should be saved on your device or not
    private String reportPath; // Path to directory, where JSON-reports, HTML-pages and screenshots will be saved
    private boolean elementScreenshots; // Whether to take screenshots of violations or not
    private boolean strict; // Whether analysis should fail if at least one violation was found or not
    private boolean printViolationsTable; // Whether to print table with violations data into output stream
    private PrintStream violationsTablePrintStream; // Specify PrintStream, which will be used for violations table print (System.out is used by default)
}

Rules

public enum Rule {
    ACCESSKEYS("accesskeys"),
    AREA_ALT("area-alt"),
    ARIA_ALLOWED_ATTR("aria-allowed-attr"),
    ARIA_ALLOWED_ROLE("aria-allowed-role"),
    ARIA_COMMAND_NAME("aria-command-name"),
    ARIA_DIALOG_NAME("aria-dialog-name"),
    ARIA_HIDDEN_BODY("aria-hidden-body"),
    ARIA_HIDDEN_FOCUS("aria-hidden-focus"),
    ARIA_INPUT_FIELD_NAME("aria-input-field-name"),
    ARIA_METER_NAME("aria-meter-name"),
    ARIA_PROGRESSBAR_NAME("aria-progressbar-name"),
    ARIA_REQUIRED_ATTR("aria-required-attr"),
    ARIA_REQUIRED_CHILDREN("aria-required-children"),
    ARIA_REQUIRED_PARENT("aria-required-parent"),
    ARIA_ROLEDESCRIPTION("aria-roledescription"),
    ARIA_ROLES("aria-roles"),
    ARIA_TEXT("aria-text"),
    ARIA_TOGGLE_FIELD_NAME("aria-toggle-field-name"),
    ARIA_TOOLTIP_NAME("aria-tooltip-name"),
    ARIA_TREEITEM_NAME("aria-treeitem-name"),
    ARIA_VALID_ATTR("aria-valid-attr"),
    ARIA_VALID_ATTR_VALUE("aria-valid-attr-value"),
    AUDIO_CAPTION("audio-caption"),
    AUTOCOMPLETE_VALID("autocomplete-valid"),
    AVOID_INLINE_SPACING("avoid-inline-spacing"),
    BLINK("blink"),
    BOLD("bold"),
    BUTTON_NAME("button-name"),
    BYPASS("bypass"),
    BYPASS_MOVE_FOCUS("bypass-move-focus"),
    COLOR_CONTRAST("color-contrast"),
    COLOR_CONTRAST_ENHANCED("color-contrast-enhanced"),
    CSS_ORIENTATION_LOCK("css-orientation-lock"),
    CUSTOM_FOCUSABLE_ELEMENTS("custom-focusable-elements"),
    DEFINITION_LIST("definition-list"),
    DLITEM("dlitem"),
    DOCUMENT_TITLE("document-title"),
    DUPLICATE_ID("duplicate-id"),
    DUPLICATE_ID_ACTIVE("duplicate-id-active"),
    DUPLICATE_ID_ARIA("duplicate-id-aria"),
    EMPTY_HEADING("empty-heading"),
    EMPTY_TABLE_HEADER("empty-table-header"),
    FIELDSET_LEGEND("fieldset-legend"),
    FOCUS_ORDER_SEMANTICS("focus-order-semantics"),
    FORM_FIELD_MULTIPLE_LABELS("form-field-multiple-labels"),
    FRAME_FOCUSABLE_CONTENT("frame-focusable-content"),
    FRAME_TITLE("frame-title"),
    FRAME_TITLE_UNIQUE("frame-title-unique"),
    HEADING_ORDER("heading-order"),
    HIDDEN_CONTENT("hidden-content"),
    HTML_HAS_LANG("html-has-lang"),
    HTML_LANG_VALID("html-lang-valid"),
    HTML_XML_LANG_MISMATCH("html-xml-lang-mismatch"),
    IDENTICAL_LINKS_SAME_PURPOSE("identical-links-same-purpose"),
    IMAGE_ALT("image-alt"),
    IMAGE_ALT_LONG("image-alt-long"),
    IMAGE_ALT_SUSPICIOUS("image-alt-suspicious"),
    IMAGE_LINK_WITHOUT_TEXT("image-link-without-text"),
    IMAGE_REDUNDANT_ALT("image-redundant-alt"),
    IMAGE_SAME_ALT("image-same-alt"),
    INPUT_BUTTON_NAME("input-button-name"),
    INPUT_IMAGE_ALT("input-image-alt"),
    INVALID_ID("invalid-id"),
    ITALIC("italic"),
    LABEL("label"),
    LABEL_CONTENT_NAME_MISMATCH("label-content-name-mismatch"),
    LABEL_TITLE_ONLY("label-title-only"),
    LANDMARK_BANNER_IS_TOP_LEVEL("landmark-banner-is-top-level"),
    LANDMARK_COMPLEMENTARY_IS_TOP_LEVEL("landmark-complementary-is-to-level"),
    LANDMARK_CONTENT_INFO_IS_TOP_LEVEL("landmark-contentinfo-is-top-level"),
    LANDMARK_MAIN_IS_TOP_LEVEL("landmark-main-is-top-level"),
    LANDMARK_NO_DUPLICATE_BANNER("landmark-no-duplicate-banner"),
    LANDMARK_NO_DUPLICATE_CONTENTINFO("landmark-no-duplicate-contentinfo"),
    LANDMARK_NO_DUPLICATE_MAIN("landmark-no-duplicate-main"),
    LANDMARK_ONE_MAIN("landmark-one-main"),
    LANDMARK_UNIQUE("landmark_unique"),
    LINK_AMBIGUOUS_TEXT("link_ambiguous-text"),
    LINK_IN_TEXT_BLOCK("link-in-text-block"),
    LINK_NAME("link-name"),
    LINK_NO_MENTION_TARGET_BLANK("link-no-mention-target-blank"),
    LINK_REFER_TO_IMAGE("link-refer-to-image"),
    LIST("list"),
    LISTITEM("listitem"),
    MARQUEE("marquee"),
    META_REFRESH("meta-refresh"),
    META_REFRESH_NO_EXCEPTIONS("meta-refresh-no-exceptions"),
    META_VIEWPORT("meta-viewport"),
    META_VIEWPORT_LARGE("meta-viewport-large"),
    NESTED_INTERACTIVE("nested-interactive"),
    NO_AUTOPLAY_AUDIO("no-autoplay-audio"),
    NO_AUTOPLAY_AUDIO_NO_EXCEPTIONS("no-autoplay-audio-no-exceptions"),
    OBJECT_ALT("object-alt"),
    P_AS_HEADING("p-as-heading"),
    PAGE_HAS_HEADING_ONE("page-has-heading-one"),
    PRESENTATION_ROLE_CONFLICT("presentation-role-conflict"),
    REGION("region"),
    ROLE_IMG_ALT("role-img-alt"),
    SCOPE_ATTR_VALID("scope-attr-valid"),
    SCROLLABLE_REGION_FOCUSABLE("scrollable-region-focusable"),
    SELECT_NAME("select-name"),
    SERVER_SIDE_IMAGE_MAP("server-side-image-map"),
    SKIP_LINK("skip-link"),
    SVG_IMG_ALT("svg-img-alt"),
    TABINDEX("tabindex"),
    TABLE_DUPLICATE_NAME("table-duplicate-name"),
    TABLE_FAKE_CAPTION("table-fake-caption"),
    TARGET_SIZE("target-size"),
    TD_HAS_HEADER("td-has-header"),
    TD_HEADERS_ATTR("td-headers-attr"),
    TH_HAS_DATA_CELLS("th-hs-data-cells"),
    VALID_LANG("valid-lang"),
    VIDEO_CAPTION("video-caption");
}

Examples

var analysisConfig = AnalysisConfig.builder()
        .excludeRules(Set.of(Rule.TARGET_SIZE, Rule.VIDEO_CAPTION, Rule.SVG_IMG_ALT))
        .includeBestPractices(true)
        .includeExperimental(false)
        .level(Level.AAA)
        .ignoreSelectors(Set.of(".my-class", "button", "#lettuce"))
        .switchOff(false)
        .build();
 
var options = new ChromeOptions();
options.addArguments("--headless");
var driver = new ChromeDriver(options);
driver.get("https://userway.org");
 
var auditConfig = AuditConfig.builder()
        .driver(driver)
        .analysisConfiguration(analysisConfig)
        .saveReport(true)
        .reportPath("./uw-a11y-reports")
        .elementScreenshots(true)
        .build();
 
var result = AccessibilityAuditor.userwayAnalysis(auditConfig);
 
// assert ...

Config

AnalysisConfig

includeRules

Set of rules to include. Accepts a set of Rule values. Default is Collections.emptySet().

excludeRules

Set of rules to exclude. Accepts a set of Rule values. Default is Collections.emptySet(). Note, that this parameter has higher priority then includeRules. It means that if the same rule was added in includeRules and excludeRules then this rule will be excluded.

includeBestPractices

Specify whether to include best practices rules (our recommendations). Default is true.

includeExperimental

Specify whether to include experimental rules (beta tested possibly unstable rules). Default is true.

level

Specify the conformance level. Possible values: A, AA, AAA. Default is AAA.

ignoreSelectors

List of selectors for elements to ignore. Accepts an Set of strings.

Note: use "ignoreSelectors" only to exclude specific elements, avoid using it in root element like body, head, html ( for such elements you can manually exclude related rules ) To see list of all rules related to html or body elements refer to "Rules" section.

switchOff

Default value is false. Set this property to true if you want to temporarily disable static analysis.

AuditConfig

driver

Provide your configured Selenium WebDriver instance with already loaded target page.

auditTimeout

Specify timeout for UserWay analysis script that is executed on target page. For example if auditTimeout is 1 minute and UserWay script did not manage to finish in 1 minute then it will be stopped immediately and timeout exception will be raised.

customTags

This property is used to distinguish issues by some criteria. For example, you have test method that goes through your site's flow. This flow includes:

Login into the system
Creating a post
Watching the list of all posts.

You want to execute scans after each of these parts, and you also want to filter issues on CA11Y dashboard by the following criteria:

Issues that were found during login
Issues that were found during creation of a post
Issues that were found during watching the list of all posts. For this result you can start first scan with Set.of("general-flow", "login"), second with Set.of("general-flow", "creating-post") and third with Set.of("general-flow", "watching-posts")

analysisConfiguration

Provide your AnalysisConfig instance. This config is completely optional.

saveReport

Default value is false. Set this property to true if you want to save JSON-report with your webpage violations.

reportPath

Default value is ./uw-a11y-reports. Specify here path to directory where you wish to save all JSON-reports, HTML-pages and violations screenshots.

screenshots

Default value is false. Set this property to true if you want auditor to take screenshots of violations on your webpage.

printViolationsTable

Default value is false. Set this property to true if you want auditor to form and print table with analysis results into specified PrintStream.

violationsTablePrintStream

Default value is System.out. Provide PrintStream which should be used to print violations table.

Makes sense only if printViolationsTable is true.

strict

Default value is false. Set this property to true if you want analysis to instantly stop if at least one violation was found.

If analysis was stopped due to strict configuration, then it will return AnalysisResult object with status == AnalysisStatus.FAILED_ON_STRICT.

Environment variables

Almost each property of analysis can be specified as environment variable. Note that environment variables have higher priority than configuration that was specified via AnalysisConfig and AuditConfig.

Here is list of all environment variables that you can use:

USERWAY_CA_SWITCH_OFF            # true or false
UW_A11Y_SAVE_JSON_REPORT         # true or false
UW_A11Y_REPORT_PATH              # Path to directory where auditor should save all result files
UW_A11Y_SCREENSHOTS              # true or false
UW_A11Y_STRICT                   # true or false
UW_A11Y_INCLUDE_RULES            # Separated with `,` list of strings
UW_A11Y_EXCLUDE_RULES            # Separated with `,` list of strings
UW_A11Y_WITH_BEST_PRACTICES      # true or false
UW_A11Y_WITH_EXPERIMENTAL        # true or false
UW_A11Y_LEVEL                    # A, AA, AAA
UW_A11Y_IGNORE_SELECTORS         # Separated with `,` list of strings
UW_A11Y_PRINT_VIOLATIONS_TABLE   # true or false

Note: you can set USERWAY_CA_SWITCH_OFF=true if you want to disable UserWay analysis on pipeline, for example.

Usage Background Runner