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):

AnalysisConfig analysisConfig = AnalysisConfig.builder()
        .level(Level.AA)
        .switchOff(false);
 
AuditConfig auditConfig = AuditConfig.builder()
        .saveReport(false) // Does not save JSON-report
        .screenshots(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 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 screenshots; // 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"),
        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"),
        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_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")
}

Example of expanded configurations usage

var analysisConfig = AnalysisConfig.builder()
        .includeRules(Set.of(Rule.REGION, Rule.LINK_AMBIGUOUS_TEXT))
        .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 driver = new ChromeDriver();
driver.get("https://userway.org");
var waitingStrategy = new ExplicitWaitingStrategy(5000L); // Analysis will start after 5 seconds after #userwayAnalysis() execution
 
var auditConfig = AuditConfig.builder()
        .driver(driver)
        .analysisConfiguration(analysisConfig)
        .saveReport(true)
        .reportPath("./a11y-reports") // Default - "./uw-a11y-reports"
        .screenshots(true)
        .printViolationsTable(true)
        .violationsTablePrintStream(System.out) // Default value
        .strict(true)
        .build();
 
AnalysisResult 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 false.

includeExperimental

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

level

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

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.

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 static analysis on pipeline, for example.

Usage GitHub