UserWay’s Accessibility Monitor

UserWay’s Accessibility Monitor allows users to create custom scanning scenarios tailored to specific user journeys on a website. This feature helps developers identify and address accessibility issues effectively.

Introduction to Custom Scenario Scans

The Custom Scenario Scan tool enables developers to simulate user interactions, such as mouse clicks and keyboard typing, to ensure accessibility across different user journeys. The scanning process takes place implicitly after completing all actions defined in the scenario script.

For example, if a user journey includes logging in, navigating to a product page, and accessing the shopping cart, the scan will focus solely on the final page (the cart).

To scan multiple pages within a journey, separate scenarios must be created. Each scenario consists of three key components:

1. Name
2. Initial Page URL
3. Scenario Script

Writing scenario scripts is similar to functional programming. These scripts use standard JavaScript along with high-level functions provided by the scenario SDK.

Overview of Scenario Scans

• • Scenario scans are priced the same as standard page scans.
  • A Custom Scenario Scan typically corresponds to a user journey, such as “Update Profile” or “Go to Shopping Cart.”
  • Results from scenario scans are displayed alongside standard page scan results in the Accessibility Monitor Dashboard under Scenario-Based Scan:

• • Scenarios are managed via the site sitemap in the Accessibility Monitor tool:

• • Examples of predefined scenario SDK functions include clickOnSelector(..) and typeInSelector(..).
  • Some SDK functions require a “CSS selector” as an input parameter. Familiarity with CSS selectors is essential; for example, an element with id="submit-btn" has the selector "#submit-btn".
  • For further learning, visit: W3Schools CSS Selectors.
  • It is recommended to develop scenario scripts iteratively, testing each step:

• Predefined SDK functions may fail for various reasons. For instance:
  • clickOnSelector(..) may fail if the selector is invalid or not found.
  • waitForSelector(..) may fail if the element is not found within a specified timeout.

Custom Scenario Scan Language

• Based on JavaScript, enhanced with helpful SDK functions.
• Supports loops and conditional statements, as well as standard JavaScript functions, e.g., Math.max(..).
• Single-line comments are allowed, e.g., //.
• Predefined SDK functions accept string or number arguments.
• Timeout arguments are measured in milliseconds.
• A semicolon at the end of each line is optional.
• Defining custom functions is not supported.

Predefined SDK Functions

• clickOnSelector(selector: string)
  • Performs a mouse click on a specified CSS selector.
  • Fails if the selector is not found.
• typeInSelector(selector: string, text: string)
  • Types text into an input or textarea identified by the CSS selector.
  • Fails if the selector is not found or the text is invalid.
• setSelectorChecked(selector: string, checked: boolean)
  • Sets the value of a checkbox specified by the CSS selector.
  • Fails if the selector is not found or the checked state is invalid.
• waitForSelector(selector: string, timeout: number)
  • Pauses execution until the specified CSS selector appears on the page.
  • Fails if the selector is not found after the timeout or if invalid arguments are passed.
• waitForTimeout(timeout: number)
  • Pauses execution for a specified duration.
  • Fails if the timeout is not a valid number.
• navigateToUrl(url: string)
  • Navigates the browser to the provided URL.

Known Limitations

• Normal pages are scanned in two resolutions (mobile and desktop), while scenarios are scanned only in desktop resolution.

Debugging and Troubleshooting

• • Developers may need to run the scenario multiple times for debugging purposes.
  • The “Test This Journey” button in the scenario edit popup runs the script and displays results:

• • Results include a screenshot of the final page and browser console output.
  • Use console.log(..) to trace values during execution.
  • If an error occurs, an error message and a screenshot of the page will be displayed:

Examples of Valid Expressions

// Some comment
clickOnSelector('button[type="submit"]')
waitForSelector('#' + 'submit', 5 * 1000)
console.log(`Random number: ${1 + Math.random()}`);

new Date()
var a = "submit"
waitForTimeout(-1)
waitForTimeout('4000')

for (let i = 0; i < 5; i++) {
    let j = i * i;
    console.info(`j = ${j}`);
}
if (true) {
    console.info('Was true');
}

Examples of Invalid Expressions

fooBar() // Produces ReferenceError: fooBar is not defined
/*
click on search box
type search term
click search button
*/
. clickOnSelector ('button[type="submit"]') // Produces SyntaxError: missing ) after