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.
Scenarios are managed on the site sitemap of the Accessibility Monitor 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. 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.
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.
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:
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 listCustom 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