Create a custom scanning scenario in UserWay's Accessibility Scanner

Rodrigo Asai
Rodrigo Asai
  • Updated

UserWay's Accessibility Scanner allows users to create custom scanning scenarios.

Developers can use the Custom Scenario Scan tool to simulate user journeys through a website, to check for 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:

Using Custom Scenario Scans, developers can create custom scenario scripts to scan page components that require user interactions. A scenario script is a simulation of user actions: mouse clicks and keyboard typing. Scenario scan performs the scan implicitly after all actions in the user journey have been completed.

If a particular user journey involves a login, and navigation to a product page, followed by navigating to the shopping cart, the scan will only be performed on the final page (the cart).

To scan multiple pages on a particular journey, you will need to create separate scenarios for them. A scenario consists of 3 parts:

  1. Name
  2. Initial page URL
  3. Scenario script

Authoring scenario scripts is similar to writing in a functional programming language. Scenario scripts use standard JavaScript language plus a few high-level functions provided by our scenario SDK.

Overview:

  • Scenario scans are 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:

  • Scenarios are managed on the site sitemap of the scanner tool:
  • 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. For example, an element's elector with id="submit-btn" is "#submit-btn".
  • Read more: https://www.w3schools.com/cssref/css_selectors.asp.
  • Recommended: develop the scenario script bit by bit, iteratively adding more steps into it, and testing the scenario on each step:
  • 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 - string value of selector
    -fails if selector is not found

  • typeInSelector(selector: string, text: string)
    -typeInSelector(selector: string, text: string)
    -performs text typing to an input (or a textarea) with given CSS selector
    -selector argument - string 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

  • waitForSelector(selector: string, timeout: number)
    - pauses scenario execution until a given CSS selector appears on a page
    - selector argument - string 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 "Test This Journey" scenario edit popup which runs the written script and shows results:
  • 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.
  • If there was an error during scenario execution, an error message will be shown, as well as a page screenshot where the error occurred.
    Browser console error output example:


Examples of valid expressions:

Empty line
// 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 argument list

  • Custom Scenario example:
  • Name: Submit login form
  • Initial URL: https://tools.userway.dev

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