Custom Scenario Scans let Accessibility Monitor scan pages that require user interaction before the final page is visible.

Standard Accessibility Monitor scans visit URLs directly and work well for public pages that do not require login, user input, navigation, or other interaction.

Scenario-Based Scans simulate those interactions first, and then run the accessibility scan on the final page.

Examples of actions you can simulate:

Opening a page
Closing a cookie or privacy banner
Completing a login form
Clicking a button (for example, “Search” or “Add to cart”)
Navigating through a workflow (for example, Home → Search → Product page)
Waiting for dynamic content to load after an action

After all scenario steps finish successfully, Accessibility Monitor scans the final page state for accessibility issues.

What is a Custom Scenario Scan?

A Custom Scenario Scan simulates real user actions before running an accessibility scan.

Key points:

A scenario scan simulates user actions such as clicking, typing, waiting, and navigation.
The accessibility scan runs only after the entire scenario is complete, on the final page that is displayed.
If multiple pages need to be scanned within a user journey, create a separate scenario for each final page you want scanned.
Scenario scans consume the same page quota as standard page scans.
Scenario results appear in Accessibility Monitor under the Scenario-Based Scan view.
Scenarios are created and managed through the site’s sitemap in Accessibility Monitor.
Scenario scans currently run in desktop resolution only (standard page scans can also use mobile).

Parts of a Scenario

Every scenario contains three components:

Component	Description
Name	A descriptive label such as `Login and open account page` or `Search for a product`.
Initial Page URL	The URL where the scenario begins, such as `https://example.com/login`. This is the first page the scenario browser opens.
Scenario Script	A short JavaScript-based script that uses Scenario SDK functions to simulate user actions.

The script executes sequentially from the first line to the last line, step by step.

Scenario Script Basics

Scenario scripts use standard JavaScript together with Scenario SDK functions provided by UserWay.

Most scenarios can stay simple. They are usually a small list of actions such as wait, click, type, and navigate.

Supported features

You can safely use:

Simple JavaScript statements (one action per line)
Single-line comments using //
Simple variables
Basic arithmetic (for example, to calculate wait times)
Simple conditional statements (if (...) { ... })
Simple loops (for example, to retry an action a few times)
The Scenario SDK functions described in the next section

Supported examples:

// Store an email address in a variable
let email = 'user@example.com'

// Simple arithmetic (used often for timeouts)
let timeoutMs = 5 * 1000  // 5 seconds

// Simple condition
if (loggedIn) {
  console.log('User is logged in')
}

You do not need to be a JavaScript expert. Most real scenarios will be shorter and simpler than this.

Unsupported features

You cannot use:

Custom JavaScript function definitions
Multi-line comments using /* ... */
Complex, application-style logic or helper libraries

Unsupported example (custom function):

function myHelper() {
  clickOnSelector('#button')
}

This pattern is not supported and will cause an error when the scenario runs.

CSS Selectors

Most Scenario SDK functions use CSS selectors to locate elements on the page.

Common examples:

Selector	Description
`#submit-btn`	Element with `id="submit-btn"`
`.nav-item`	Elements with class `nav-item`
`button[type="submit"]`	A `<button>` used to submit a form

If the selector is invalid or no matching element exists, the action will fail.

If you are not familiar with CSS selectors, this external reference can help:

CSS selector reference: CSS Selectors Reference

Scenario SDK Functions

This section summarizes each Scenario SDK function, what it does, and common failure conditions.

clickOnSelector(selector)

Item	Details
Purpose	Clicks the first element that matches the CSS selector (for example, a button or link).
Parameters	`selector` (string) – CSS selector of the element to click.
Typical use	Click buttons, links, or icons such as `button[type="submit"]` or `#login-btn`.
Fails if	The selector is invalid, misspelled, or no matching element is found on the page.

typeInSelector(selector, text)

Item	Details
Purpose	Types text into a text field such as an email, username, or search field.
Parameters	`selector` (string) – CSS selector of the `<input>` or `<textarea>`; `text` (string) – text to type.
Typical use	Fill login forms, search boxes, contact forms, or filter inputs.
Fails if	The element is not found, is disabled, read-only, or does not accept text input.

setSelectorChecked(selector, checked)

Item	Details
Purpose	Sets a checkbox or radio button to checked or unchecked.
Parameters	`selector` (string) – CSS selector of the checkbox or radio button; `checked` (boolean) – `true` or `false`.
Typical use	Accept terms and conditions, toggle filters, or choose a radio option.
Fails if	The element is not found or `checked` is not a valid boolean (`true`/`false`).

selectDropdown(selector, value)

Item	Details
Purpose	Selects an option in a dropdown (`<select>`) by its value.
Parameters	`selector` (string) – CSS selector of the `<select>` element; `value` (string) – the option value to choose.
Typical use	Choose a country, language, category, or other dropdown option.
Fails if	The dropdown is not found, or the given option `value` does not exist.

waitForSelector(selector, timeout)

Item	Details
Purpose	Waits until an element appears on the page, or until the timeout is reached.
Parameters	`selector` (string) – CSS selector; `timeout` (number) – maximum time to wait, in milliseconds.
Typical use	Wait for a message, a dashboard, or a dynamic component to load before interacting with it.
Fails if	The element does not appear before the timeout or the arguments are invalid.

waitForTimeout(timeout)

Item	Details
Purpose	Pauses the script for a fixed amount of time.
Parameters	`timeout` (number) – time to wait, in milliseconds.
Typical use	Add a short delay after navigation, animations, or API calls to ensure the page has settled.
Fails if	The timeout is not a valid positive number.

navigateToUrl(url)

Item	Details
Purpose	Navigates the browser to a new URL during the scenario.
Parameters	`url` (string) – the full URL to open.
Typical use	Jump from one part of the site to another (for example, from dashboard to account settings URL).
Fails if	The URL is malformed or cannot be loaded by the browser.

Timeout values (milliseconds)

All timeout values use milliseconds:

Value	Time
`1000`	1 second
`5000`	5 seconds
`5 * 1000`	5 seconds (simple calculation used instead of writing `5000` directly)

Valid Examples

ℹ️ Note: If you use an ID or class in a selector, check that the complete selector does not also match other elements on the same page. If a class is shared, make the selector more specific.

These examples show how to combine SDK functions and simple JavaScript.

// Wait for the page to settle
waitForTimeout(2000)

// Click the submit button
clickOnSelector('button[type="submit"]')

// Wait up to 5 seconds for a welcome message
waitForSelector('#welcome-message', 5 * 1000)

// Log a message to the console output 
console.log('Scenario started')

A slightly more advanced example with a loop:

// Try clicking a retry button up to 3 times
for (let i = 0; i < 3; i++) {
  console.info('Click attempt number: ' + (i + 1))
  clickOnSelector('#retry-button')
}

A simple condition:

let isTestUser = true

if (isTestUser) {
  console.info('Running scenario with test user account')
}

These examples show that you can:

Use console.log() and console.info() to send helpful messages to the debug output.
Use simple loops and conditions when needed.
Use basic math (5 * 1000) to calculate timeouts.

Most real scenarios can be simpler than these patterns, but all of them are allowed.

Invalid Examples

Multi-line comments are not supported:

/*
  Click the login button
  Then type the password
*/

Custom functions are not supported:

/*
  Click the login button
  Then type the password
*/

Calling undefined functions will fail:

fooBar()

If any line fails:

The scenario stops.
You see an error when you run Test This Journey.
The error usually includes the line or selector that failed.

Example: Simple Login Scenario

Scenario Name: Submit login form
Initial URL: https://example.com/login

// Wait for the login form
waitForSelector('#username', 5 * 1000)

// Enter credentials
// Replace [USERNAME] and [PASSWORD] with your test values in the Monitor UI,
// not in public docs or support tickets

 typeInSelector('#username', '[USERNAME]')
 typeInSelector('#password', '[PASSWORD]')

// Submit the form
clickOnSelector('button[type="submit"]')

// Wait for the dashboard or account page
waitForSelector('.account-dashboard', 10 * 1000)

// Optional wait for all content to finish loading
waitForTimeout(2000)

console.log('Login scenario completed, ready for accessibility scan')

After the script completes, Accessibility Monitor scans the final page state, which in this example is the account dashboard.

If you also want to scan the login page itself, create a separate scenario that ends on the login page and does not navigate to the dashboard.

Testing a Scenario

Build incrementally

To avoid complex debugging, build your scenario in small steps:

Start with the Initial Page URL and one or two simple actions (for example, wait and click one button).
Click Test This Journey.
If it works, add the next steps (for example, typing into fields, clicking submit).
Test again after every few changes.

This incremental approach makes it much easier to find where something goes wrong.

What “Test This Journey” does

When you click Test This Journey:

The scenario runs step by step in a browser.
A screenshot of the final page state is generated.
Browser console output is captured, including your console.log and console.info messages.
Any script errors are shown.

If a step fails:

An error message identifies the issue (for example, element not found, timeout reached).
A screenshot shows the page at the time of failure.
The error usually points to the failing selector or script line.

Debugging tips

💡 Tip: Prefer waitForSelector() over long fixed delays such as waitForTimeout(15000). This allows the scenario to continue as soon as the required element appears, making scenarios faster and more reliable.

Additional recommendations:

Handle cookie banners and pop-ups at the beginning of a scenario:
```
waitForTimeout(2000)
clickOnSelector('#cookie-accept')
```
Keep each scenario focused on a single user journey (for example, “submit contact form” or “add item to cart”).
Use console.log() and console.info() to print helpful markers such as console.log('Reached step 3: after login').

Known Limitations

Scenario scans currently run only in desktop resolution.
The accessibility scan occurs once, after the scenario completes, not after every step.
Custom JavaScript function definitions are not supported.
Scenarios should remain focused on a single workflow or journey.

Additional Resources

UserWay Help Center: Home | UserWay Help Center
CSS Selector Reference: CSS Selectors Reference

Need more help?

Contact the UserWay Support Team — we're here to assist you.

Get in touch with UserWay Support.

Accessibility Monitor Scenario-Based Scans Reference Guide