Skip to main content
All CollectionsAccessibility Monitor
Introduction to building Custom Scenario Scans in UserWay's Accessibility Monitor
Introduction to building Custom Scenario Scans in UserWay's Accessibility Monitor

UserWay’s Accessibility Monitor dashboard gives your team accessibility trends, actionable insights for your websites, and real-time alerts.

Updated over a week ago

UserWay's Accessibility Monitor 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 Monitor:

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 Monitor Dashboard under Scenario - Based Scan.

    Scenario - Based Scan - Screenshot
  • Scenarios are managed on the site sitemap of the Accessibility Monitor 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

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)

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?