📡 Accessibility Scanner v4.0.2: 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

Good news, everyone! 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:
  1. Enter the direct URL of the login page (e.g., https://app.example.com/login).
  2. When you start the scan, a visible browser window (non-headless) will open to this URL.
  3. You must manually enter the credentials and complete the login process in that window. This includes handling any multi-factor authentication (MFA) prompts.
  4. Once you are successfully logged into the application, return to the command line/terminal that is running the scanner and press the Enter key.
  5. 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:
  • Go to URL: Navigates the browser to a specific page. This is typically the first step.
  • Click Element: Simulates a mouse click on an element identified by its CSS selector.
  • Type in Element: Types text into an input field identified by its CSS selector.
  • Select Option: Chooses an option from a <select> dropdown menu by its value.
  • 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.
  • 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:
  • Highest Precedence: A defined User Journey overrides all other scope options (URL, Sitemap, Crawl).
  • 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.

• 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 for each standard viewport, providing comprehensive responsive coverage. Be aware this multiplies the total scan time.
• 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.
• Custom Device Emulation:
  • Purpose: For highly specific or non-standard testing scenarios.
  • 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.
• Skip pre-scan content check 🔍: Bypasses the default check that verifies a URL's Content-Type header is HTML before a full scan. Useful for misconfigured servers or local files.
• 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 but 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. Recommended for very large websites.

E. Crawl Options 🕷️

This section is only active when the scanner is in Crawl Mode.

• Enable Smart Crawl & Trap Avoidance (New!):
  • Purpose: Prevents the scanner from getting stuck in "crawler traps" like infinite calendars, complex filter combinations, or endlessly deep URL paths.
  • Behavior: When enabled, this feature intelligently analyzes URL structures and path depths. It automatically identifies and avoids patterns indicative of non-unique content, making the crawl significantly faster and more efficient. This is now enabled by default and is highly recommended.
• Max Crawl Depth: Limits how many directory levels deep the crawler explores. A depth of 0 scans only pages in the same directory. Leave blank for unlimited depth.
• Crawl Delay: Introduces a base pause (in milliseconds) between each page load. This value may be automatically increased by the Adaptive Remediation Engine. 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: Manually prevents the crawler from visiting URLs containing specific text strings.
  • Examples: logout, ?replytocom=, /archive/, ?utm_source=
• Respect robots.txt 🤖: If checked, the scanner will read the target site's robots.txt file and obey any Disallow rules.
• Enable Parallel Crawling 🚀: This is the most efficient way to scan a large site, starting from a single URL. Instead of one browser finding links sequentially, this mode launches multiple "workers" that operate as a team. Each worker scans its page, finds all new links, and adds them to a shared queue for other free workers to immediately start processing. This creates a dynamic and rapid crawling process. Be aware that this uses more resources and it is recommended that screenshots be disabled to maximise performance.

F. Axe Scan Rules 🪓

• 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 exclude individual rules from the scan.
  • Run ONLY These Axe Rules: Use this searchable list to run a specific subset of rules. This overrides all other tag and disable selections.
• Enable Parallel Axe Scanning ⚡: After the discovery phase, 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.

• Axe Configuration:
  • Exclude CSS Selectors: Instructs Axe to completely ignore specific parts of a page (e.g., div#chat-widget, .ad-container).
  • Enable elementRef 🔗: A developer-focused option that includes detailed DOM element references in the results.
  • Run Axe on 'Document' 📄: Uncheck this to run only on the <body> element, which can be slightly faster but may miss issues in the <head>.
• Scan Behaviour:
  • Navigation Timeout ⌛: Sets the maximum time (in milliseconds) the scanner will wait for a page to load.
  • 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).
    • Wait for Timeout: Pauses for a fixed duration.
    • Wait for Selector: Pauses until a specific element appears.
• Stability & Performance:
  • Enable Interaction Scanning (Deep Scan) 🖱️ (New!): After a page is scanned, this feature automatically finds and clicks interactive elements (like buttons or tabs) and then re-scans the page to find issues in dynamically revealed content. This provides a deeper analysis but can significantly increase total scan time.
  • Enable Periodic Browser Restarts 🔄: For long sequential (non-parallel) scans, this option automatically restarts the browser instance after a set number of pages to prevent memory leaks.
  • Disable JavaScript for Link Discovery 📜: (Crawl Mode Only) A niche option to find links on sites without executing JavaScript. Faster but will miss any links generated by client-side code.
• Other Options:
  • Proxy Server URL 🌐: Routes all scanner traffic through a specified proxy server (supports HTTP, HTTPS, and SOCKS).
  • Check PDFs 📄: Enables a basic check for an accessibility tag tree in any linked PDF documents.
  • Use Persistent Browser Session 💾: Saves browser data (cookies, local storage). Ideal for sites requiring frequent login.
  • Disable GPU Hardware Acceleration 💨: Recommended for maximum stability.
  • Attempt to Handle Trusted Types 🛡️: An experimental injection method for modern sites with strict Content Security Policies (CSPs).
• Adaptive Remediation & Stealth 🕵️‍♂️ (New!):
  • Purpose: Automatically and intelligently bypasses anti-bot systems to ensure scan completion. This is a critical feature for modern websites and is enabled by default.
  • How it Works: The scanner proactively monitors for signs of blocking. When detected, its Adaptive Remediation Engine automatically escalates its strategy:
    1. Level 1: Intelligently increases the crawl delay.
    2. Level 2: Enables Basic Stealth Mode to mask automation flags.
    3. Level 3: Deploys Enhanced Stealth Mode, using advanced and randomized browser fingerprint spoofing.

H. Backend Fine-Tuning (Advanced) ⚙️

• Purpose: For expert users who need to modify the scanner's core internal parameters for extreme edge cases.
• Controls: Offers granular control over all system timeouts, retry logic, adaptive delay behavior, stealth user agents, and browser launch arguments.

Warning: Incorrect values in this section can lead to scan instability or failure. Use with caution.

I. Configuration & Manual Issues

• Shareable Configuration 📋: Generates a text string representing your entire form configuration. Copy this to save or share, and paste it back in later to restore all settings.
• Add Manual Issues ✍️: A dedicated UI to document issues found through manual review. These are seamlessly integrated into the final HTML report.

II. Initiating, Monitoring & Controlling Your Scan

• Analyse Site Settings: Before a full scan, use this button. It triggers a quick analysis of the target and provides recommended settings (like enabling Adaptive Remediation) to improve scan success.
• Start Scan: Begins the full scan process.
• Live Scan Controls: Once a scan is running, new buttons appear:
  • Pause / Resume Scan: Temporarily halt and continue the scan.
  • Finish Early & Scan Found: Halts the discovery phase and immediately proceeds to scan all URLs found so far.
  • Cancel Scan: Terminates the entire process immediately.
• Progress Display: A real-time dashboard provides:
  • A live progress bar.
  • A detailed, color-coded activity log showing every step the scanner is taking, including any adaptive remediation actions.
  • A backend memory monitor.

III. Results, Reports & Management

• View Report: Upon completion, a link appears to open the interactive, self-contained HTML report in your browser.
• Previous Reports Section: An in-app browser for all past reports. You can search, filter, open, or delete old reports.
• Folder Path Display: Buttons to quickly show you the exact location on your computer where your reports and persistent session data are stored.