📡 Accessibility Scanner v3.8.0: The Complete User Guide & Technical Reference

Welcome to the comprehensive guide for the Accessibility Scanner. This document provides a detailed, in-depth overview of every feature and configuration option, along with technical explanations and strategic best practices to empower you to conduct the most effective and efficient accessibility audits possible.

I. The Configuration Interface: Setting Up Your Scan

The main form is designed for both simplicity and power. Key sections can be expanded to reveal advanced controls.

A. Basic Setup: Defining Your Scan Scope

This section is the foundation of your scan, determining what the scanner will target. Only one scope mode (Crawl, Sitemap, Specific URLs, or User Journey) can be active at a time. The UI will automatically disable conflicting options to guide you.

• URL to Scan / Crawl From:
  • Purpose: The primary starting point for the scanner. This is the most common way to begin a scan.
  • Usage:
    • Web URL: Enter a full URL, like https://example.com. This will be the starting point for a crawl.
    • Local File: Use the file:/// protocol. The path must be absolute and correctly formatted for your operating system.
      • Windows Example: file:///C:/Users/YourName/Desktop/project/index.html (Note the three slashes after file:)
      • macOS/Linux Example: file:///Users/YourName/project/index.html
  • Note: This field is required unless you are using a User Journey, Sitemap, or Specific URL list, which will override it.
• Login URL (Optional, Web Only):
  • Purpose: To handle scans of websites that require user authentication, such as internal dashboards, staging environments, or user-specific portals.
  • How it Works:
    • Enter the direct URL of the login page (e.g., https://app.example.com/login).
    • When you start the scan, a visible browser window (non-headless) will open to this URL.
    • You must manually enter the credentials and complete the login process in that window. This includes handling any multi-factor authentication (MFA) prompts.
    • Once you are successfully logged into the application, return to the command line/terminal that is running the scanner and press the Enter key.
    • The scanner will then proceed to the main "URL to Scan" you provided, now with an authenticated session.
  • Best Practice: For maximum effectiveness and to avoid logging in on every scan, use this feature with the "Use Persistent Browser Session" option in the Advanced section.
• Sitemap XML URL (Optional, Web Only):
  • Purpose: The most efficient method for scanning all known pages of a large, well-structured website. This avoids the time-consuming process of crawling.
  • Behavior: This option overrides all Crawl settings and the "Scan Specific URLs" list. The scanner will fetch the sitemap, parse it for all page URLs, and scan each one. It intelligently handles:
    • Nested Sitemaps: If the provided URL is a sitemap index, it will recursively fetch and process all sub-sitemaps.
    • Compressed Files: Automatically decompresses .xml.gz files.
• Scan Specific URLs/Local Files Only (Optional):
  • Purpose: To audit a predefined list of pages or local files without any automated discovery. Ideal for regression testing, focusing on a critical user flow, or auditing a small set of provided pages.
  • Behavior: This option overrides Crawl Mode. Enter one URL or file:/// path per line.

B. User Journey (Automation) 🚶

• Purpose: The most powerful feature for testing modern web applications. It allows you to test dynamic content, multi-step forms, and complex user flows by simulating a real user's actions from start to finish. This is the definitive tool for testing authenticated areas and Single-Page Applications (SPAs).
• Usage:
  1. Expand the "User Journey" section.
  2. Click + Add Step to begin building your script.
  3. For each step, choose an Action from the dropdown menu.
  4. Fill in the required parameters (e.g., a URL for "Go to URL", a CSS selector like #submit-button for "Click Element").
  5. Steps can be reordered by dragging and dropping them via their step number.
• Key Actions:
  1. Go to URL: Navigates the browser to a specific page. This is typically the first step.
  2. Click Element: Simulates a mouse click on an element identified by its CSS selector.
  3. Type in Element: Types text into an input field identified by its CSS selector.
  4. Select Option: Chooses an option from a <select> dropdown menu by its value.
  5. Wait for Element / Wait for Time: Pauses the script until a specific element appears or for a fixed duration in milliseconds. Essential for SPAs where content loads dynamically after an action.
  6. Scan Page: This is the most important action. It tells the scanner to perform a full accessibility audit on the page in its current state, capturing any content that has appeared or changed as a result of previous steps.
• Behavior:
  1. Highest Precedence: A defined User Journey overrides all other scope options (URL, Sitemap, Crawl).
  2. Required Action: Your journey must contain at least one "Scan Page" action to generate any accessibility results. You can (and should) have multiple "Scan Page" actions at different points in your journey.

C. Viewport and Device Emulation 🖥️

This section offers three distinct modes for testing responsive designs and mobile-specific experiences.

1. Standard Viewport Preset:
   • Single Viewport: Select one preset (e.g., Mobile, Tablet, Large Desktop) for a quick, targeted test.
   • All Viewports: Check the "Scan All Standard Viewports" box. The scanner will execute the entire scan (crawl, sitemap, or journey) for each standard viewport, providing comprehensive responsive coverage. Be aware this multiplies the total scan time.
2. Device Emulation Preset:
   • Purpose: To accurately test on specific, real-world devices.
   • How it Works: Choose a device (e.g., iPhone 15 Pro, Galaxy S24). The scanner will automatically configure the correct screen size, user agent string, pixel density, and touch capabilities, providing a high-fidelity emulation.
3. Custom Device Emulation:
   • Purpose: For highly specific or non-standard testing scenarios, such as testing a new device before it's in the presets list.
   • How it Works: Manually define all device parameters: width, height, user agent, device scale factor, and whether it's a mobile device with touch input.

D. General Behaviour & Output

• Generate Tickets in Report 🎟️: A powerful workflow enhancement. When checked, the final HTML report will include a "View Ticket" button for each issue. Clicking it opens a modal with detailed, pre-formatted information designed to be copied directly into issue trackers like Jira or Azure DevOps. Each ticket includes a title, description, impact, standards, code snippets, and reproduction steps.
• Skip pre-scan content check 🔍: By default, the scanner checks a URL's Content-Type header to ensure it's HTML before queuing it for a full scan. This option bypasses that check. It is useful for misconfigured servers that don't send the correct header, or for local files where the check is unnecessary.
• Enable Element Screenshots 📸:
  • Purpose: Captures visual evidence of accessibility violations to aid in quick identification and debugging.
  • Modes:
    • Per Instance (High Memory): Captures a unique screenshot for every single occurrence of a violation. This is the most detailed option, providing maximum context, but it can consume significant disk space and memory on large scans.
    • Per Issue Type (Lower Memory): A resource-friendly alternative that captures one representative screenshot for the first occurrence of each unique issue type, per viewport. This is the recommended setting for very large websites.

E. Crawl Options 🕷️

This section is only active when the scanner is in Crawl Mode (no Sitemap, Specific URLs, or User Journey is defined).

• Max Crawl Depth: Limits how many directory levels deep the crawler explores relative to the starting URL's path. A depth of 0 scans only pages in the same directory. Leave blank for unlimited depth.
• Crawl Delay: Introduces a pause (in milliseconds) between each page load during the crawl. Essential for avoiding rate-limiting on sensitive servers. A good starting value is 500.
• Max Crawl Size: Sets a hard limit on the total number of pages the crawler will discover and queue for scanning.
• Exclude URL Patterns: Prevents the crawler from visiting URLs that contain specific text strings. This is critical for avoiding "crawler traps" (like infinite calendars) and irrelevant content.
  • Examples: logout, ?replytocom=, /archive/, ?utm_source=
• Respect robots.txt 🤖: If checked, the scanner will attempt to read the target site's robots.txt file and obey any Disallow rules that apply to its user agent.
• Enable Parallel Crawling 🚀: Uses multiple browser workers to discover pages simultaneously. Significantly faster for large sites but uses more memory and CPU.

F. Axe Scan Rules 🪓

This section provides granular control over which accessibility rules are applied during the scan.

• Axe Scan Standards (Tags): The primary way to control rules. Select rule sets based on standards like WCAG 2.2 (A/AA) and general Best Practices.
• Customise Axe Rules:
  • Disable Specific Axe Rules: Use the searchable list to check off and exclude individual rules from the scan. For example, you might disable color-contrast if you are only checking for non-visual issues.
  • Run ONLY These Axe Rules: Use this searchable list to run a specific subset of rules. This powerful option overrides all other tag and disable selections, allowing for highly targeted audits.
• Enable Parallel Axe Scanning ⚡: After the discovery phase (crawl or sitemap processing) is complete, this option uses multiple workers to scan the found pages simultaneously, speeding up the analysis phase.

G. Advanced Scan Options 📜

This section contains powerful options for fine-tuning scan behavior to handle complex websites and environments.

• Axe Configuration:
  • Exclude CSS Selectors: Instructs Axe to completely ignore specific parts of a page during the scan. This is ideal for excluding third-party chat widgets, ad banners, or other elements outside your control (e.g., div#chat-widget, .ad-container).
  • Enable elementRef 🔗: A developer-focused option that includes detailed DOM element references in the results for advanced debugging.
  • Run Axe on 'Document' 📄: By default, Axe scans the entire document object. Uncheck this to run only on the <body> element, which can be slightly faster but may miss issues in the <head>, such as a missing <title>.
• Scan Behaviour:
  • Navigation Timeout ⌛: Sets the maximum time (in milliseconds) the scanner will wait for a page to load. Increase this value for slow websites or poor network conditions.
  • Scan Iframes 🖼️: Enables analysis of content within same-origin iframes.
  • Wait Before Scan: Adds a crucial wait condition before Axe runs. Essential for Single-Page Applications (SPAs) to ensure all dynamic content has finished rendering.
    • Wait for Timeout: Pauses for a fixed duration.
    • Wait for Selector: Pauses until a specific element (e.g., #main-content.loaded) appears on the page.
  • Enable Periodic Browser Restarts 🔄: For long sequential (non-parallel) scans, this option automatically restarts the browser instance after a set number of pages. This is a key stability feature that prevents memory leaks.
  • Disable JavaScript for Link Discovery 📜: (Crawl Mode Only) A niche option to find links on sites without executing JavaScript. This is much faster but will miss any links that are generated by client-side code.
• Other Options:
  • Proxy Server URL 🌐: Routes all scanner traffic through a specified proxy server (supports HTTP, HTTPS, and SOCKS protocols).
  • Check PDFs 📄: Enables a basic check for an accessibility tag tree in any PDF documents linked from the scanned pages.
  • Use Persistent Browser Session 💾: Saves browser data (cookies, local storage) in a dedicated folder. Ideal for sites requiring frequent login, as you only need to log in manually once. To start a fresh session, use the "Show Session Folder Path" button to find and delete the old session data.
  • Enable Adaptive Network Delay 📈: A smart feature that automatically adjusts navigation delays based on server error rates, helping to avoid being blocked while maximizing speed.
  • Disable GPU Hardware Acceleration 💨: Recommended for maximum stability. Only uncheck this if a page's core functionality depends on WebGL content that needs to be rendered.
  • Stealth Modes 🕵️‍♂️/🥷: Use Basic Stealth to randomize browser properties or Enhanced Stealth to deploy advanced fingerprint spoofing to evade sophisticated bot detection systems.
  • Attempt to Handle Trusted Types 🛡️: An experimental script injection method designed for modern sites that use strict Content Security Policies (CSPs), which can sometimes block standard testing tools.

H. Backend Fine-Tuning (Advanced) ⚙️

• Purpose: This section is for expert users who need to modify the scanner's core internal parameters for extreme edge cases.
• Controls: It offers granular control over all system timeouts (Axe, Sitemap, general requests), retry logic parameters (attempts, delays, backoff factors, bot-blocking multipliers), adaptive delay behavior, the list of stealth user agents, and even allows you to provide a custom list of low-level browser launch arguments.
• Warning: Incorrect values in this section can lead to scan instability or failure. Use with caution and only when necessary.

I. Configuration & Manual Issues

• Shareable Configuration 📋: A powerful feature for teams and repeatable tests. It generates a text string representing your entire form configuration. You can copy this string to save or share, and paste it back into the UI later to instantly restore all your settings.
• Add Manual Issues ✍️: A dedicated user interface to document accessibility issues found through manual review. You can specify the URL, selector, description, impact, and relevant WCAG criterion. These issues are then seamlessly integrated into the final HTML report, creating a single source of truth for your entire audit.

II. Initiating, Monitoring & Controlling Your Scan

• Analyse Site Settings: Before a full scan, use this button. It triggers a quick, non-intrusive analysis of the target to check for firewalls, CAPTCHAs, SPAs, and sitemaps. It will then provide you with recommended settings (like enabling Enhanced Stealth or suggesting a Crawl Delay) to improve the success and accuracy of your scan.
• Start Scan: Begins the full scan process based on your configuration.
• Live Scan Controls: Once a scan is running, new buttons appear:
  • Pause / Resume Scan: Temporarily halt and continue the scan process.
  • Finish Early & Scan Found: Halts the discovery phase (crawling) and immediately proceeds to scan all URLs that have been found so far.
  • Cancel Scan: Terminates the entire process immediately.
• Progress Display: A real-time dashboard provides:
  • A live progress bar with percentage completion.
  • A detailed, color-coded activity log showing every step the scanner is taking.
  • A backend memory monitor to keep an eye on resource usage.

III. Results, Reports & Management

• View Report: Upon completion, a link appears to open the interactive, self-contained HTML report in your browser. This report can be saved and shared with anyone, as it requires no server to view.
• Retry Failed/Skipped URLs: If any pages failed to scan due to network errors or other issues, this button will appear. Clicking it instantly re-runs the scan, targeting only the previously failed items, using the current form settings.
• Previous Reports Section: An in-app browser for all past reports. You can search by keyword, filter by date, open reports directly, or delete old ones.
• Folder Path Display: Buttons to quickly show you the exact location on your computer where your reports and persistent session data are stored, making manual management easy.