UserWay’s Accessibility Monitor 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 Monitor:
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:
- Name
- Initial page URL
- 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 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(..)andtypeInSelector(..) - 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 selector 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 foundtypeInSelector(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 itwas read onlysetSelectorChecked(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 valuewaitForSelector(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 passedwaitForTimeout(timeout: number)
– pauses scenario execution for a given timeout
– timeout argument – number value of timeout in ms
– fails if timeout is not a valid numbernavigateToUrl(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.
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)
