Runtime scanner for arbitrary URLs.

Unlike the ExUnit integration in Excessibility, this module is intended to be called from application code — LiveViews, background jobs, CLI wrappers, external HTTP APIs, etc. It launches Playwright (via assets/axe-runner.js), navigates to the given URL, and runs axe-core analysis, returning a structured report.

Usage

{:ok, report} = Excessibility.Scanner.scan("https://example.com")

for v <- report.violations do
  IO.puts("[#{v.impact}] #{v.id}: #{v.description}")
end

On failure, returns {:error, reason} where reason is a typed tuple (see scan_error/0). Pattern-match cleanly from LiveView handlers:

case Excessibility.Scanner.scan(url, timeout: 20_000) do
  {:ok, report} -> send(self(), {:scan_complete, report})
  {:error, :timeout} -> send(self(), {:scan_failed, :timeout})
  {:error, {:http_error, status}} -> ...
  {:error, {:navigation_failed, msg}} -> ...
  {:error, {:invalid_url, _}} -> ...
  {:error, {:playwright_error, msg}} -> ...
end

Fallback behavior

If Playwright fails to reach a remote URL (timeout, WAF block, or navigation error), the scanner automatically retries by fetching the HTML via curl and scanning it as a local file. This won't execute JavaScript, so SPA content may be missing, but server-rendered pages still get full results. When the fallback path is used, the returned report has a non-nil :fallback field. Disable with fallback: false.

file:// URLs never fall back (curl can't fetch them).

Reusing an existing Playwright installation

By default the scanner uses the Playwright copy bundled under this library's assets/ directory. Projects that already have Playwright installed (with browsers downloaded) can point Excessibility at it and skip the second browser download:

config :excessibility, playwright_path: "assets/node_modules/playwright"

To skip the bundled npm install entirely, point Excessibility at a host node_modules directory that provides both playwright and @axe-core/playwright:

config :excessibility, node_modules_path: "assets/node_modules"

Relative paths are expanded from the project root. Note that resolving @axe-core/playwright from the host also pins the axe-core version, so engine.axe_version in reports follows the host installation — an axe minor bump can change finding sets relative to earlier baselines.