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:
- 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 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(..)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 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)
<%= heading %>