This page contains example scripts, and a list of all functions available when writing scripts in A11y Pulse. To learn how to add scripts to your sites in A11y Pulse, please see the Scripting documentation.
Contents:
- Available functions
- Modifiers
- Variables
- Example scripts
Available functions
navigate(url)
Load the specified URL and wait for network activity to stop. The URLs must include the protocol e.g. https://.
Example
navigate("https://www.w3.org/");fill(selector, value)
Set the value of the first element matching selector. This will work for <input>, <textarea>, and <select> elements. Any Puppeteer selector can be used.
Example
// CSS selectors can be used
fill("#country", "New Zealand");
fill(".form .fieldset > input", "Hello");
// XPath works with the `xpath/` prefix
fill('xpath///button[@type="submit"]/ancestor::form//input', "abc123");click(selector)
Click on the first element matching selector, then wait for any network activity to stop. Any Puppeteer selector can be used.
Example
click("button[type=submit]");submit(selector)
Call the .submit() function of the first element matching selector, then wait for any network activity to stop. Any Puppeteer selector can be used. This is useful when you don’t know which button to click to submit a form.
Example
submit("form:has(input[name=password])");setHeader(name, value, filter?)
Set a header on outgoing requests, optionally filtering by URL. The filter supports simple wildcards using the asterisk * character. If no filter is specified, the header will be applied to all requests. We do not recommend doing this, as it can cause cross-origin (CORS) errors.
Example
// Add basic authentication to all requests.
setHeader("authorization", "Basic YWxhZGRpbjpvcGVuc2VzYW1l");
// Add a custom header to all requests on cdn.a11ypulse.com.
setHeader("x-cache-debug", "1", "https://cdn.a11ypulse.com/*");
// Add a cache-control header to any /favicon.ico requests.
setHeader("cache-control", "none", "*/favicon.ico");setCookie(name, value)
Set a cookie on the browser, scoped to the page’s current URL. This must be called after navigate(), since there’s no page yet to attach the cookie to before that. Injecting a session cookie directly is often faster and more reliable than clicking through a login form, letting you navigate straight to the page you want to scan already authenticated.
Example
// Establish an origin for the cookie to attach to.
navigate("https://app.a11ypulse.com/");
// Inject a session cookie using a stored secret.
setCookie("session", secret("SESSION_COOKIE"));
// Reload so the app picks up the authenticated session.
navigate(PAGE_URL);setLocalStorage(key, value)
Set a key in the browser’s localStorage, scoped to the page’s current origin. Like setCookie(), this must be called after navigate(). Useful for apps that read an auth token from localStorage on startup rather than relying on cookies.
Example
navigate("https://app.a11ypulse.com/");
setLocalStorage("authToken", secret("AUTH_TOKEN"));
navigate(PAGE_URL);secret(name)
Read the plaintext value of a named secret from your team’s Secrets settings. Secrets are encrypted at rest and never stored or logged in plain text. The value is resolved at the start of each scan. If the named secret does not exist, the scan will fail with a descriptive error.
secret() can be used anywhere a string value is accepted, such as the second argument to fill().
Example
// Fill a password field using a stored secret.
fill("input[name=password]", secret("MY_PASSWORD"));totp(secret)
Generate a 6-digit time-based one-time password (TOTP) code from a base32-encoded secret, using the same standard (RFC 6238, SHA-1, 30-second period) as Google Authenticator and most authenticator apps. Use this to log into accounts protected by multi-factor authentication: register A11y Pulse as an additional authenticator using the setup key shown during MFA enrollment (the text version of the QR code), store that key as a secret, and pass it to totp().
The code is generated fresh each time the totp() call runs, not once for the whole scan, so it can’t expire while an earlier step is still running. Like secret(), totp() can be used anywhere a string value is accepted. If the secret is not valid base32, the scan will fail with a descriptive error.
Example
navigate("https://app.a11ypulse.com/auth/login");
fill("input[name=email]", "[email protected]");
fill("input[name=password]", secret("MY_PASSWORD"));
click("button[type=submit]");
// Fill the MFA challenge with a fresh one-time code.
fill("input[name=code]", totp(secret("MFA_SETUP_KEY")));
click("button[type=submit]");Modifiers
.optional()
Append .optional() to any function call to make it best-effort: if the call fails for any reason (e.g. the selector isn’t found, or it times out), the failure is ignored and the script continues to the next line. Without .optional(), a failed call stops the script and fails the scan.
This is useful for steps that don’t apply on every run, such as dismissing a cookie banner that isn’t always shown.
Example
navigate("https://app.a11ypulse.com/auth/login");
// Dismiss a cookie banner if one appears, without failing the scan if it doesn't.
click("#cookie-banner button.accept").optional();
fill("input[name=email]", "[email protected]");
fill("input[name=password]", secret("MY_PASSWORD"));
click("button[type=submit]");Variables
PAGE_URL
At runtime, PAGE_URL is replaced with the URL of the page currently being scanned. This is useful when the same script is shared across multiple pages on a site, such as when setting a request header that references the page’s own URL.
PAGE_URL can be used anywhere a string value is accepted, such as an argument to navigate() or setHeader().
Example
// Re-navigate to the page under test after logging in elsewhere.
navigate(PAGE_URL);SCAN_DATETIME
At runtime, SCAN_DATETIME is replaced with the date and time the scan started, as an ISO 8601 string (e.g. 2026-07-14T18:30:00.000Z), in UTC. It’s resolved once per scan, so every occurrence in a script gets the same value.
Example
setHeader("x-scan-time", SCAN_DATETIME);RANDOM_STRING
At runtime, RANDOM_STRING is replaced with a random 32-character hexadecimal string, for example 3f9a1c2e5b7d8f0a4c6e2b1d9f3a7c58. It’s resolved once per scan, so every occurrence in a script gets the same value. This is useful for filling a field that requires a unique value on every run, such as a username field with a uniqueness constraint.
Example
fill("input[name=username]", RANDOM_STRING);Example scripts
Log into an application
// You can add comments to your script to help others understand them.
//
// Open the login page.
navigate("https://app.a11ypulse.com/auth/login");
// Fill out the username and password fields.
// Use secret() to avoid storing credentials in plain text.
fill("input[name=email]", "[email protected]");
fill("input[name=password]", secret("MY_PASSWORD"));
// Click the login button.
click("button[type=submit]");
// Alternatively, submit the login form.
// submit("form:has(input[name=password])");Log in with a session cookie
// Open the app first, so setCookie() has a page to attach the cookie to.
navigate("https://app.a11ypulse.com/");
// Inject a session cookie using a stored secret, skipping the login form entirely.
setCookie("session", secret("SESSION_COOKIE"));
// Reload the page you want to scan, now authenticated.
navigate(PAGE_URL);Set request headers
// Add basic authentication to all requests.
setHeader("authorization", "Basic YWxhZGRpbjpvcGVuc2VzYW1l");
// Add a custom header to all requests on cdn.a11ypulse.com.
setHeader("x-cache-debug", "1", "https://cdn.a11ypulse.com/*");
// Add a cache-control header to any /favicon.ico requests.
setHeader("cache-control", "none", "*/favicon.ico");
// Open the page to be scanned.
navigate("https://www.a11ypulse.com/");