UserWay's Accessibility Scanner allows users to create custom scanning scenarios. Custom Scenario Scan is a tool that allows developers to simulate user journeys through a website to ensure there are no accessibility issues. Multiple scenarios can be mapped at once and a detailed report is generated for any issues detected.

Introduction to building Custom Scenario Scans in UserWay's Accessibility Scanner:

Custom Scenario scans allow a developer to scan page components that require user interactions by users creating custom scenario scripts. A Scenario script in a nutshell is a simulation of user actions: mouse clicks and keyboard typing. Scenario scan performs the scan implicitly after all user actions have been completed. Meaning: if a particular user journey involves a login, navigation to a product page, and then navigating to the shopping cart, then the scan will only be performed on the final page (cart). If you need to scan multiple pages on a particular journey, you will need to create separate scenarios for them. A scenario consists of 3 parts: name, initial page URL, and scenario script. Authoring scenario scripts is similar to programming in a functional programming language. Scenario scripts are written by using standard JavaScript language plus a few high-level functions provided by our scenario SDK.

Overview:

  • Scenario scans are priced at the same price as ‘standard' page scans.

  • A Custom Scenario Scan normally corresponds to a particular user journey, e.g. “Update profile” or “Go to shopping cart.”

  • Scenario scan results are shown along with other page scan results in the Accessibility Scanner Dashboard under Scenario - Based Scan.

    Scenario - Based Scan - Screenshot
  • Scenarios are managed on the site sitemap of the scanner tool.

    Sitemap - Screenshot
  • Some examples of predefined scenario SDK functions include clickOnSelector(..) and typeInSelector(..).

  • Some predefined scenario SDK functions accept “CSS selector” as an input parameter, so an understanding of CSS selectors is vital. i.e. selector of an element with id=”submit-btn” is: “#submit-btn”. Read more: https://www.w3schools.com/cssref/css_selectors.asp.

  • It is recommended to develop the scenario script by iteratively adding more and more steps into it and testing the scenario on each step.

    Test Scenario - Screenshot
  • Any predefined scenario SDK function may fail for a particular reason. For example:

    • clickOnSelector(..) may fail if a selector is invalid or it was not found on a page.

    • waitForSelector(..) may fail if the element was not found on a page for a given timeout or if the timeout argument is not a valid value.

Custom Scenario Scan Language:

  • Is based on JavaScript language, with a few helpful SDK functions.

  • Supports loops or conditions, all vanilla JS functions, e.g. Math.max(..)

  • Single line comments are supported, i.e: //

  • Predefined SDK functions accept arguments of type string or type number.

  • Timeout arguments represent milliseconds

  • A semicolon at the end of each line is optional

  • Defining your own functions is not supported

Predefined SDK Functions:

  • clickOnSelector(selector: string)

    • performs mouse click on a given CSS selector

    • selector argument - sting value of selector

    • fails if selector is not found

  • typeInSelector(selector: string, text: string)

    • performs text typing to an input (or a textarea) with given CSS selector

    • selector argument - sting value of selector

    • text argument - string value to type

    • fails if selector is not found or text is not a valid value

    • may fail if for some reason input did not change its value, e.g. if it was read only

  • setSelectorChecked(selector: string, checked: boolean)

    • performs setting of a checkbox value on given selector

    • selector argument – string value of selector

    • checked argument – boolean value of checkbox state

    • fails if selector is not found or checked is not a valid value

  • selectDropdown(selector: string, value: string)

    • performs selection of a value from the selector of dropdown box

    • selector argument – string value of selector

    • value argument – string value of dropdown box value

    • fails if selector is not found or value is not valid

  • waitForSelector(selector: string, timeout: number)

    • pauses scenario execution until a given CSS selector appears on a page

    • selector argument - sting value of selector

    • timeout argument - number value of timeout in ms

    • fails if selector is not found after given timeout or invalid argument(s) is/are passed

  • waitForTimeout(timeout: number)​​

    • pauses scenario execution for a given timeout

    • timeout argument - number value of timeout in ms

    • fails if timeout is not a valid number

  • navigateToUrl(url: string)

    • Navigates browser to any URL provided as the argument

Known limitations

  • Normal pages are scanned in two resolutions by default: mobile and desktop. Scenarios are scanned only in desktop resolution.

Debugging and troubleshooting:

  • During the development of a scenario, the script developer may need to run the code a few times in order to debug it.

  • There is a button in the scenario edit popup Test This Journey which runs the written script and shows results.

    Test Scenario - Screenshot
  • Results of Test This Journey are the final page screenshot image and browser console output text.

  • In order to trace some values during scenario execution - console.log(..) can be used.

  • In cases when there was an error during scenario execution, there will be an error message shown as well as a page screenshot where the error occurred. Browser console error output example:

    Error Console Example - Screenshot

Examples of valid expressions:

1. Empty line
2. // some comment
3. clickOnSelector('button[type="submit"]')
4. waitForSelector('#' + 'submit', 5 * 1000)
5. console.log(`Random number: ${1 + Math.random()}`);
1. new Date()
2. var a = "submit"
3. waitForTimeout(-1)
4. waitForTimeout('4000')
1. for (let i = 0; i < 5; i++) { 
let j = i * i;
console.info(`j = ${j}`);
}
2. if (true) {
console.info('Was true');
}

Examples of invalid expressions:

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

Custom Scenario example:

Name: Submit login form

Initial URL: https://tools.userway.dev

1. clickOnSelector('a[href="/form-auth.html"]')
2. typeInSelector('#user_name', 'demo')
3. typeInSelector('#user_pwd', '123123')
4. clickOnSelector('#submit_btn')
5. waitForSelector('.ng-binding', 1000)
6. waitForTimeout(3000)

Try it for yourself: Creating a Custom Scanning Scenario - Sample

Learn more about debugging: Debugging Custom Scenarios Scans

If you have any questions, you can reach our support team at support@userway.org

Did this answer your question?