Get started / Written tutorial
Test the extension from start to finish
A complete desktop Chrome testing tutorial: demo pages, JSON profiles, every tab, expected evidence, recovery and a useful failure report.
What you will get
A repeatable test record covering page scans, configuration safety, crawl, responsive layouts, visible states, keyboard and reading order, AI, reports and cleanup. Test the webpage at smaller viewports while the extension runs in desktop Chrome.
Follow these steps
Install A11y Scan from the Chrome Web Store, then open chrome://extensions to confirm it is enabled. If you are testing a team preview instead, remove or disable the store build first, extract the supplied beta ZIP, and choose Developer mode → Load unpacked, selecting the extracted A11yScan folder that contains manifest.json. A ZIP cannot be loaded directly. The source-build alternative is on Getting Started.
After replacing an older build, choose Reload on the extension and refresh existing demo tabs. Record the ZIP/build name, extension version, Chrome version and operating system. Open the side panel from Chrome’s Extensions menu on the demo tab.
Keep this guide in one tab and the current demo in another. The downloaded profiles target the production website and named paths. Import the profile for each test, or use the builder to set a matching target; do not carry the core demo’s target into a different demo.
Use the deliberate bad examples to test detection and the good examples to check false positives. Record exact rule IDs and affected elements rather than matching the old illustrative total counts printed inside some fixtures.
Run the baseline and recovery tests first, then work through the checklist. Preserve reports before clearing or closing a workflow; all current features are free, with no account or payment required.
1. Establish a baseline scan
What to do
- Download the core profile, then open the core demo in a separate Chrome tab. Keep this guide open so you can return to it.
- Open A11y Scan on the demo tab. Choose Test configuration → Form → Import JSON file and select core-scan.json. Check that the target is this website’s /demo/axe-core-basics path and the WCAG target is 2.2 AA.
- Choose Scan Page. Open the image-alt, button-name and label findings in Results. Use the finding highlight to locate each affected element.
- Inspect the good controls too: the image with descriptive alt, the email input with its associated label, and the button with visible text.
Expected evidence
- The image without alt, empty button and unlabeled text input are reported on their actual elements. A highlight must not point at an unrelated passing sibling.
- The good image is absent from image-alt; #email is absent from label; the named button is absent from button-name. Other rules can still report other aspects of those elements.
- The result URL is the demo you scanned. Do not use older on-page total counts as an accuracy target: rule versions, settings and viewport can change totals.
Reset before continuing: Use Clear before the next independent scan. Re-import the core profile whenever you need this baseline again.
Back to the test checklist ↑2. Reject bad configuration and recover
Intentional broken JSONIntentional wrong versionIntentional unknown fieldUnsupported mode combination
What to do
- Apply the core profile first. Export or copy its active configuration so you can compare it afterward.
- Import each intentionally invalid file separately. Read the error and inspect the active configuration after each attempt. These files are negative test cases, not broken downloads.
- Paste an incomplete JSON object into the editor. Do not apply a correction yet; copy/download the active configuration and confirm the invalid draft has not replaced it.
- Import the unsupported Crawl + multi-viewport profile. It has valid JSON and schema, but execution must be blocked with an explanation. Try the core profile on a different demo path to check the target mismatch message.
- Return to the core demo, import core-scan.json and run Scan Page again.
Expected evidence
- Malformed syntax, unsupported versions and unknown fields show errors and preserve the last valid active profile.
- Unsupported combinations and target mismatches never create a successful report. A configuration can be structurally valid and still be unsuitable for the active page.
- The corrected baseline scans successfully. HTTPS profile imports reject HTTP URLs, embedded credentials, redirects and oversized responses, and time out after 15 seconds; closing the dialog cancels pending imports.
Reset before continuing: Discard the invalid draft and re-import the core profile on its matching demo before continuing.
Back to the test checklist ↑3. Prove the JSON controls the scanner
What to do
- Scan the core demo with the core profile and confirm image-alt is present. Then import image-alt-disabled.json and scan the same page again.
- Export JSON and inspect provenance.effectiveConfig: the axe image-alt override must be false. The profile disables that particular axe rule, not every image-related heuristic.
- In the website builder, import the override profile, give it a local name, inspect Form and JSON, and download it. Import that file into the extension and repeat the scan.
- Change a supported setting in the extension, export its configuration, and import it back into the builder. Confirm the target, rules and viewport settings survive. A profile’s display name is local metadata, outside scanner JSON.
Expected evidence
- The axe image-alt finding disappears with the override while button-name and label remain enabled.
- Form → JSON → extension → report uses the same validated settings; a JSON text draft does not silently take effect.
- A mismatched target is rejected. Profiles configure shipped checks; arbitrary JavaScript is not a supported custom rule.
Reset before continuing: Restore the core profile. Remove temporary named profiles in the builder if you no longer want them saved in this browser.
Back to the test checklist ↑4. Locate findings and preview color vision
What to do
- Clear the previous run and use a profile whose target includes the overlay demo. In the builder, set this demo’s full URL as the target, leave single-page mode on, and import the downloaded profile.
- Scan, open the missing-alt image or empty-button finding and highlight its affected node. Toggle Violations, Tab order and Focus gaps individually.
- Open Color vision simulation and choose Achromatopsia. Compare the page colors, then select Normal vision.
- Turn overlays on again and navigate to another page. Return to the demo and run a fresh analysis.
Expected evidence
- Outlines and badges correspond to the current page and actual elements. Controls can be reached using Tab and Enter.
- The color preview changes page pixels; Normal vision restores them. It is a simulation, not a diagnosis of a person’s vision.
- Navigation clears old result controls and overlays. The next page must never display findings belonging to the previous one.
Reset before continuing: Choose Normal vision, turn overlays off and Clear the result. Reload the demo if a page interaction has changed it.
Back to the test checklist ↑5. Wait for delayed content
What to do
- Import deferred.json and open the delayed-content demo. Its inventory table appears after about three seconds.
- Run the profile immediately after opening the page. It uses a crawl page rule waiting for table tbody tr before scanning.
- Review the table images and their image-alt finding. Export JSON and inspect the effective wait rule and page status.
- To test failure, use the builder’s JSON editor to change the wait selector to #element-that-never-appears with a short supported timeout. Import it, reload the demo and run again.
Expected evidence
- A successful run analyzes loaded table rows, including their missing-alt images; scanning a loading screen is not equivalent.
- The nonexistent selector produces an explicit failed-page or run message after its timeout, with no invented successful scan for that page.
Reset before continuing: Restore the original delayed profile after the failure check. Return to single-page settings before manual workflow tests.
Back to the test checklist ↑6. Capture the states people actually see
What to do
- Create a single-page profile for the accordion demo; turn Crawl, Movie and Multi-viewport off. Start workflow session in Scan.
- Name the first state Collapsed and choose Capture state. On the demo, open Team Members, then name the next state Team expanded and capture it.
- Choose Finish and review. Select each named state and inspect the image-alt and link-name findings; export the workflow JSON before closing the side panel.
- Separately open the dialog demo. Scan it closed, then open each modal and scan again. Try Tab, Shift+Tab and Escape yourself; check whether focus stays useful and returns to the trigger.
Expected evidence
- The Team Members image and empty team link are inserted only after expansion. The expanded capture includes their findings; the collapsed capture must not invent those elements.
- Each workflow capture retains its own label, URL and evidence. Opening a dialog is not by itself proof its focus behavior is correct.
- Workflow capture is manual. It does not replay click scripts or retain unsaved sessions after the panel closes.
Reset before continuing: Export the workflow first. Close dialogs, clear the session and reload the demo to restore its initial state.
Back to the test checklist ↑7. Crawl the six-page mini-site
What to do
- Import crawl.json, open the hub and start Site Crawl. The scope stays inside /demo/crawl-hub, with a cap that allows the hub and five children.
- Review the visited URLs, page statuses and findings per page. Page 1 omits image alt; page 2 has placeholder-only inputs. Do not confuse the clean-content example with a conformance guarantee for its entire document.
- Repeat in URL-list mode using two child URLs, including one duplicate. Confirm the duplicate is not scanned repeatedly.
- Start another crawl and choose Cancel while it is running. For a failure test, use an explicit URL within the scope that does not exist and inspect its failed-page entry.
Expected evidence
- The normal profile visits six documents and does not wander onto the marketing site or another origin.
- Every finding stays associated with its page. Errors and cancellations are visible and are not reported as successful empty pages.
- Authenticated crawl, mocks and page waits require explicit configuration; see the crawl guide before using them on a real site.
Reset before continuing: Wait for cancellation/completion before changing modes. Export the crawl if needed, then switch Crawl off for the next single-page checks.
Back to the test checklist ↑8. Scan the target page at smaller viewports
What to do
- Run the extension in desktop Chrome. Import responsive.json, open the responsive demo and note the original browser-window size. This profile uses explicit desktop page emulation (Mobile layout off, Touch input off, height 900, pixel ratio 1), so narrow widths do not depend on Chrome’s window minimum. Close DevTools; Chrome’s debugging banner is expected.
- Select Multi-viewport and run Scan All Viewports at 375, 768 and 1280 CSS pixels. The target webpage should change layout as each viewport is applied.
- Select each completed width in Results. Compare the responsive navigation and affected elements; export JSON and check requestedWidth, measuredWidth and status for each entry.
- For mobile layout and touch, import mobile-emulation.json and open the mobile / touch demo. Enable Emulate mobile / touch; confirm Mobile layout, Touch input, height 844 and pixel ratio 2. Close DevTools and run 320, 375 and 768px. The debugging banner is expected. The demo shows real layout metrics and a native touch counter; scans do not automatically tap controls.
- Cancel a second run and check that the page returns to its original size. If a width cannot be reached, inspect the explicit failure rather than accepting a different measured width.
Expected evidence
- The page’s layout and CSS media queries respond to the measured page viewport, not the width of the extension side panel. The desktop extension itself is not a mobile app.
- Findings belong to their selected width, and incomplete widths are visible. The browser/window and page focus are restored after success or cancellation.
- Width-only testing resizes the desktop window. Opt-in emulation also sets mobile layout, height, pixel ratio and touch in Chrome; it leaves the user agent unchanged and does not cover Safari, iOS or physical devices. The controlled reflow box is flagged at 320px only. A missing mobile viewport meta tag, debugger conflict or interrupted attachment produces an explicit failure. Movie + multi-viewport and Crawl + multi-viewport are blocked.
Reset before continuing: Clear the result and disable Multi-viewport before the remaining single-page tests. Confirm the original page size has returned.
Back to the test checklist ↑9. Follow keyboard order and focus
What to do
- Open the tab-order demo and choose Keyboard → Analyze. Inspect the sequence and enable the Tab order overlay.
- On the webpage, use Tab and Shift+Tab. Compare the order with the positive tabindex controls and the normal controls; check that focus is visible.
- Try Keyboard playback, its pause/resume controls and Stop. Then use the focus-gap demo to inspect controls that look clickable but cannot be reached or activated using the keyboard.
- Navigate to another page and confirm that the previous analysis/overlay disappears.
Expected evidence
- The analyzed list and badges come from the current page. Positive tabindex can change the order even when visual order looks reasonable.
- Playback can stop and cleanup works. Hands-on keyboard activation is still required; an order list does not prove the widgets work.
Reset before continuing: Stop playback, disable overlays and leave focus on a known webpage control before proceeding.
Back to the test checklist ↑10. Inspect reading order and speech
What to do
- Open Screen Reader on the demo tab and choose Analyze. Inspect names, roles and the reading sequence.
- Select a listed element and use its page navigation/highlight action. Try scope/Inspect where Chrome makes it available.
- If browser speech is available, start it and stop it. Compare the spoken content with visible labels and headings.
- Navigate to another page and analyze again; then separately try a real screen reader with the demo’s controls.
Expected evidence
- The list refers to live page elements and refreshes for the new tab/page. Unsupported Inspect or speech states are explained.
- Browser speech is a reading aid, not VoiceOver, NVDA or JAWS, and cannot certify the accessibility of a widget.
Reset before continuing: Stop speech, clear highlights and close Inspect before moving to the next test.
Back to the test checklist ↑11. Keep manual review and ARIA evidence separate
What to do
- Use a matching single-page profile, run a page scan and open Scan → Manual. Inspect a suggested human check and record a verdict after actually trying the interaction.
- Open Scan → ARIA on the ARIA demo, analyze the widgets and inspect a selected role’s attributes and references.
- Compare the combobox missing required state with the checkbox supplying its required state. Check the interaction with keyboard input as well as the reported attributes.
Expected evidence
- Manual decisions remain human review; they do not silently rewrite automated findings.
- ARIA analysis uses actual page widgets. Valid attributes alone do not establish correct focus management, labeling or behavior; the default axe WCAG filter also excludes some best-practice checks.
Reset before continuing: Export evidence you need before clearing. Do not treat an unchecked manual item as a pass.
Back to the test checklist ↑12. Watch Scan Movie and stop it
What to do
- With Crawl and Multi-viewport off, enable Movie in Scan and run a single-page scan on a matching demo.
- Watch the focusable-element walkthrough after the scan. Choose Stop while it is playing, then Clear.
- Compare the findings with a run on the same state with Movie off.
Expected evidence
- Movie can stop and its overlay is removed by Clear. It is a visual walkthrough, not a video recording or an extra scanning engine.
- Keyboard tab playback is a separate control over its analyzed trace. Movie does not enable Observe, which remains unavailable.
Reset before continuing: Turn Movie off and clear its overlay before AI and saved-run tests.
Back to the test checklist ↑13. Discuss real findings with Chrome AI
What to do
- Scan the core demo, select a finding and choose Ask AI or open AI Chat. Read its model-availability message.
- When offered, choose Start AI or Download and start AI. Chrome manages the on-device model download; the extension does not require a cloud AI key.
- Ask: Explain the selected finding, cite its finding ID, and suggest a fix. Use Open to return to the actual finding and compare the answer with its evidence.
- Change the selected finding or perform a new scan; confirm the next conversation uses the current context. Do not mistake a simulated test model for proof of actual downloaded-model inference.
Expected evidence
- If Chrome offers its model, the answer concerns the selected scan/finding and references its ID. AI cannot change findings or prove WCAG conformance.
- If Chrome reports unavailable or unsupported, composition stays disabled with an explanation. Record that state as unavailable, not a successful conversation or a scanner failure.
- The context is a bounded finding summary, not the whole page HTML. Hardware, Chrome settings and model availability can still prevent inference.
Reset before continuing: Start a new chat when changing the subject and clear the scan after preserving evidence. Do not paste private page data into a bug report.
Back to the test checklist ↑14. Save and compare repeatable runs
What to do
- Run the core profile on the core demo and choose Save this run. Repeat without changing the page/settings, save again and choose Compare runs.
- For a controlled fix, use Chrome DevTools Elements to add a descriptive alt attribute to the specific image missing it. Close DevTools, rerun the same profile on the same page and save the new result.
- Compare the relevant runs and inspect resolved, new and persisting findings. Check that the resolved image-alt node is the image you edited.
- Export the comparison or saved snapshot. Keep the page, viewport and settings equivalent when interpreting a change.
Expected evidence
- The unchanged run has stable matching evidence. The fixed missing-alt finding resolves without deleting unrelated findings.
- Changed page/state/viewport scopes may be excluded from comparison and must be disclosed. Runs are stored in this Chrome profile, not a cloud account; storage can fail or reach its limit.
Reset before continuing: Reload the demo to undo the temporary DOM edit. Delete test runs you no longer need, keeping any exported evidence first.
Back to the test checklist ↑15. Export evidence and test error cleanup
What to do
- Export a successful single-page scan as JSON, HTML and print-to-PDF where offered. Open the downloaded files and compare the page URL, findings and effective configuration with Results.
- For crawl, workflow and multi-viewport, use their JSON exports and inspect page/state/width statuses. Do not assume every report format supports every mode.
- Open a Chrome internal page such as chrome://settings, attempt analysis from the extension and read the restriction message. Return to the demo and perform a fresh scan.
- Reload the extension from chrome://extensions after an update, refresh demo tabs, and rerun the baseline to catch stale content-script behavior.
Expected evidence
- Downloaded evidence is readable and belongs to the run you performed. Review URLs, snippets and captured artifacts before sharing; they can contain page data.
- Restricted-page errors never replace missing evidence with sample results. The extension recovers on a normal allowed page and clears stale overlays.
Reset before continuing: Clear the scan, stop speech/playback, choose Normal vision and close test tabs. Keep a short result log with pass/fail/unavailable for each section.
Back to the test checklist ↑If something does not match
- The profile targets another page
- Open its matching demo URL. To use a local copy, update the target origin, crawl seed URLs and absolute scope prefixes together in the builder.
- Counts differ from the demo’s old instructions
- Compare rule IDs and actual affected elements in this guide. Older fixture counts are illustrative; do not mark every extra finding wrong or assume an empty result proves conformance.
- A download opens in the browser
- Save the linked JSON file, preserving its .json extension, then use Import JSON file. The three intentionally invalid profiles must fail validation.
- A viewport or AI is unavailable
- Record the requested settings and exact message. Do not substitute an unmeasured width or claim a conversation occurred. Return to the baseline profile to check the scanner independently.
- The extension was updated or the tab changed
- Reload the extension in chrome://extensions, refresh the demo tab, reopen the side panel and analyze again. Check the active tab and profile before retrying.
Keep a useful test record
Copy this template for each failure. A screenshot of the page and panel plus a redacted JSON report is more useful than a total count alone.
Test section / pass, fail or unavailable: Extension version + build or ZIP name: Chrome version + operating system: Demo URL + page state: Profile filename + changes: Requested/measured viewport (if applicable): Steps to reproduce: Expected rule ID / element / behavior: Actual result + exact error: Screenshot / redacted report: Does reloading and repeating the baseline recover?
Use Support to report it. If the protected submission form is unavailable, use the email contact shown there. Remove credentials, private URLs and captured page content before sharing.
Check your result
- Each tested workflow has a recorded pass, fail or unavailable outcome with its page, state and profile.
- An invalid profile, failed page, cancelled run or unavailable AI model never masquerades as a successful scan.
- Exports, cleanup and a fresh baseline work after the negative tests. Automated results remain evidence for review, not proof of WCAG conformance.