Chrome extension UserScripts testing needs more than one happy-path injection. A user script can be syntactically invalid, target the wrong frame, lose access while the service worker is still alive, execute in an unsafe world, send an untrusted message, or disappear after an extension update.
Chrome’s current extension documentation gives QA a useful boundary: starting in Chrome 149, chrome.userScripts.execute() validates script syntax synchronously and returns diagnostics on failure. This tutorial turns that behavior into a practical test lab while also covering permission toggles, runtime errors, frame results, update recovery, and human review of user-provided code.
What the UserScripts API does
The official UserScripts API reference describes an MV3 API for running code supplied by users rather than code shipped in the extension package. The API requires the userScripts manifest permission and host permissions for the sites where scripts may run.
Users must also explicitly enable user scripts. Current documentation distinguishes older builds that use Developer mode from Chrome 138 and newer, where each extension has an Allow User Scripts toggle on its details page. Do not infer availability from the manifest alone.
The API has been available since Chrome 120, while execute() and frame-level injection results are documented from Chrome 135. Pin the browser build in automated tests and verify the installed API surface before exercising later behavior.
Define the QA contract
Given a disposable MV3 extension, a synthetic page, and a reviewed user script, reject invalid syntax before page effects, run valid code only on authorized targets, return traceable per-frame results, handle revoked access visibly, preserve world and messaging boundaries, and restore only approved scripts after an extension update.
Record the browser build, extension version and ID, manifest hash, user-script toggle state, host permissions, tab and document URLs, tab ID, frame and document IDs, execution world, world ID, CSP, messaging state, script hash, source type, injection timing, result or diagnostic, DOM canary state, service-worker lifecycle, and reviewer decision.
Step 1: build a disposable fixture
Create an unpacked MV3 extension with only the userScripts permission and a narrow host permission for a local test origin. Use a fixed extension ID in automation. The fixture page should contain:
- A top frame with a unique DOM canary.
- One same-origin child frame.
- One cross-origin child frame on another local origin.
- A page variable visible only from the main world.
- A message receiver that records correlation IDs without performing privileged actions.
Keep the scripts synthetic. Never begin with production pages, credentials, personal profiles, or code downloaded from an untrusted source.
Step 2: verify API availability correctly
Do not check only whether chrome.userScripts is defined. Google documents a revocation edge case: if a user disables access while an extension service worker is running, the namespace can remain defined, but method calls throw. After the extension context reloads, the namespace can become undefined.
Probe a method and handle both a synchronous throw and a rejected promise:
async function userScriptsAvailable() {
try {
await chrome.userScripts.getScripts();
return true;
} catch (error) {
return false;
}
}Test four states: permission absent, permission present but user toggle off, toggle turned off while the worker remains alive, and toggle off after the worker reloads. The UI should explain how to enable access without repeatedly prompting or pretending execution succeeded.
Step 3: create a syntax-validation matrix
Build small scripts with one fault each:
| Fixture | Expected QA evidence |
|---|---|
| Valid expression | Execution reaches only the selected target |
| Missing closing delimiter | Syntax diagnostic and zero page mutation |
| Illegal token | Syntax diagnostic and zero message |
| Truncated template literal | Syntax diagnostic with the original script hash |
| Valid syntax, thrown error | Runtime error attributed to the target frame |
| Valid async rejection | Rejected execution is not mislabeled as syntax failure |
Before each trial, reset the page canaries and capture DOM, storage, network, and message baselines. After a syntax failure, independently prove none changed. A diagnostic is useful only if malformed code did not partially execute.
Record the diagnostic as data, not as the assertion itself. The essential assertion is the combination of clear rejection, correct script correlation, no unintended page effect, and no successful result.
Step 4: distinguish validation from runtime failure
execute() returns a promise of InjectionResult[]. Each result includes a frame ID and document ID, plus either result or error; those two fields are mutually exclusive. Syntax validation happens before execution, while runtime failures occur after valid code reaches a target.
Normalize every attempt into:
{
trialId, scriptHash, tabId, documentId, frameId,
world, phase, diagnostic, result, runtimeError,
domChanged, messageCount, decision
}Never collapse a top-frame success and child-frame failure into one green status. The test passes only when the result set matches the expected target inventory and every result has exactly one terminal outcome.
Step 5: test frame and document targeting
The API accepts a tab target plus optional frame IDs, document IDs, or all-frames behavior. Current docs state that allFrames cannot be true when frameIds is supplied, and documentIds cannot be combined with frameIds.
Exercise top frame only, one child frame, a document ID after navigation, all eligible frames, an unknown frame, a stale document after reload, and invalid option combinations. Compare requested targets with returned frame and document IDs. Verify host permissions independently for each frame URL; a permitted top frame must not imply access to an unrelated child origin.
Step 6: verify code and file source rules
A script source must contain exactly one of code or file. Test neither, both, an empty code string, a missing packaged file, a valid packaged file, a path outside the extension root, and a file that becomes invalid in a new extension build.
Hash the exact source used in the trial. When reporting a diagnostic, link it to the hash rather than logging the entire user script, which may contain private data.
Step 7: compare USER_SCRIPT and MAIN worlds
The default USER_SCRIPT world is isolated from the page. The MAIN world shares the host page’s JavaScript environment and is visible to the page and other extensions. Treat MAIN-world execution as a separate, higher-risk feature.
Place a page variable and a tampered page function in the fixture. Verify the isolated world cannot directly read or overwrite them, while the main world can interact as designed. Then let the page replace a function your script expects and confirm your extension does not trust a page-controlled return value for a privileged decision.
Configure a restrictive user-script-world CSP where appropriate and record it with getWorldConfigurations(). Test resetting the world configuration and ensure scripts fall back to the reviewed default rather than retaining stale settings.
Step 8: test messaging as untrusted input
User-script messaging is disabled by default and must be enabled with configureWorld({ messaging: true }). Messages arrive through dedicated runtime.onUserScriptMessage and runtime.onUserScriptConnect handlers, which helps distinguish this less-trusted context.
Send valid, missing-field, oversized, duplicate, out-of-order, prototype-shaped, and prompt-like payloads. Validate type, size, correlation ID, allowed action, sender document, and rate limits before responding. A user script should not be able to trigger arbitrary commands, broad network access, extension updates, or secret reads through a permissive message bridge.
Step 9: exercise immediate injection timing
With injectImmediately, Chrome attempts injection as soon as possible, but Google explicitly says this does not guarantee execution before page load because the page may already be loaded. Do not write timing assertions that depend on a guaranteed race winner.
Run trials before navigation, during a deliberately slow document, after DOMContentLoaded, and after full load. Assert observable outcomes and document identity, not an assumed event order. Use correlation timestamps for diagnosis without replacing state-based assertions with fixed delays.
Step 10: verify registration and update behavior
Test register(), getScripts(), update(), and unregister() with stable IDs. Script IDs cannot begin with an underscore because that prefix is reserved. For an update batch, seed one invalid script or unknown ID and verify the documented atomic behavior: no scripts in that request are updated when parsing, file validation, or ID checks fail.
Chrome clears user scripts when the extension updates. Build version A with two approved registrations, then update to version B. Confirm the old registrations are gone before your recovery logic runs. Re-register only from runtime.onInstalled when the reason is update, and prove install, browser startup, and other reasons do not create duplicates.
Step 11: automate visible outcomes
Google’s end-to-end testing guidance recommends asserting user-visible behavior where possible instead of coupling every test to internal extension state. Load the unpacked extension in an isolated browser, open the synthetic page, trigger the user script from an extension page, and assert the DOM or UI result.
Use internal getScripts(), world configuration, and frame evidence for focused diagnostics. Remember that some drivers keep extension service workers alive, so explicitly include a test path that reloads the extension context when verifying revocation and lifecycle behavior.
Step 12: define a safe release gate
A release candidate passes only when valid scripts run on the intended targets, invalid syntax has no effect, runtime failures remain frame-specific, revoked access is visible, MAIN-world and messaging risks are bounded, update recovery is deterministic, and logs are privacy-safe.
Do not automatically approve or rewrite user code from diagnostics. Show the error, preserve the original input, let the user edit deliberately, and rerun the complete validation. Human review remains required for scripts that touch accounts, payments, personal data, production tools, or privileged extension capabilities.
QA rollout checklist
- Browser build, extension version, manifest, toggle, and host permissions are recorded
- Availability is tested through a method call, including live revocation and context reload
- Valid, invalid, runtime-error, and async-rejection scripts are separated
- Syntax failures produce zero DOM, storage, network, and message side effects
- Every frame and document result matches the expected target inventory
- Invalid frame-option combinations fail clearly
- Exactly one of code or file is accepted
- USER_SCRIPT and MAIN worlds have separate risk tests
- CSP and world reset behavior are verified
- User-script messages are validated as untrusted input
- Immediate injection tests assert outcomes rather than timing assumptions
- Batch update failures leave all targeted registrations unchanged
- Extension updates clear and deterministically restore only approved scripts
- Service-worker lifecycle is tested without relying on a permanently attached debugger
- Diagnostics and logs use hashes and redaction
- Human reviewers retain approval and release authority
Official sources
- What’s new in Chrome extensions
- Chrome UserScripts API reference
- Chrome extension permissions reference
- Chrome extension message passing
- End-to-end testing for Chrome extensions
UserScripts can be tested safely when QA treats syntax validation as the first gate, not the only gate. Prove no malformed code executed, trace every frame result, recheck access after revocation, isolate worlds and messages, test update recovery, and keep user-provided code under explicit human control.