Accessibility Snapshot Testing for Elixir + Phoenix

Excessibility helps you test your Phoenix apps for accessibility (WCAG compliance) by taking HTML snapshots during tests and running them through Pa11y.

• Keep accessibility in your existing test feedback loop. Snapshots are captured inside ExUnit, Wallaby, and LiveView tests, so regressions surface together with your functional failures.
• Ship safer refactors. Baseline comparison saves .good/.bad.html (plus screenshots when enabled) so reviewers can see exactly what changed and approve intentionally.
• Debug CI-only failures quickly. Pa11y output points to the failing snapshot, and the saved artifacts make it easy to reproduce locally.

1. During tests, call html_snapshot(conn) to capture HTML from your Phoenix responses, LiveViews, or Wallaby sessions
2. After tests, run mix excessibility to check all snapshots with Pa11y for WCAG violations
3. When HTML changes, snapshots are diffed against approved baselines — review and approve changes with mix excessibility.approve
4. In CI, Pa11y reports accessibility violations alongside your test failures

• Snapshot HTML from Plug.Conn, Wallaby.Session, Phoenix.LiveViewTest.View, and Phoenix.LiveViewTest.Element
• Automatically diff against saved baselines
• Interactive approval (good/bad) when snapshots change
• Optional PNG screenshots via ChromicPDF
• Mockable system/browser calls for CI
• Pa11y configuration with sensible LiveView defaults

Add to mix.exs:

def deps do
  [
    {:excessibility, "~> 0.5", only: [:dev, :test]}
  ]
end

Fetch dependencies and run the installer:

mix deps.get
mix igniter.install excessibility

The installer will:

• Add configuration to test/test_helper.exs
• Create a pa11y.json with sensible defaults for Phoenix/LiveView
• Install Pa11y via npm in your assets directory

1. Configure the endpoint and helper modules in test/test_helper.exs. The installer does this automatically, or add manually:

   Application.put_env(:excessibility, :endpoint, MyAppWeb.Endpoint)
   Application.put_env(:excessibility, :system_mod, Excessibility.System)
   Application.put_env(:excessibility, :browser_mod, Wallaby.Browser)
   Application.put_env(:excessibility, :live_view_mod, Excessibility.LiveView)

2. Add use Excessibility in tests where you want snapshots:

   defmodule MyAppWeb.PageControllerTest do
     use MyAppWeb.ConnCase, async: true
     use Excessibility
   
     test "renders home page", %{conn: conn} do
       conn = get(conn, "/")
   
       html_snapshot(conn,
         prompt_on_diff: false,
         screenshot?: true
       )
   
       assert html_response(conn, 200) =~ "Welcome!"
     end
   end

3. Typical workflow:

   # Write tests with html_snapshot calls, then:
   mix test                    # Generates snapshots in test/excessibility/
   
   # Check accessibility
   mix excessibility           # Runs Pa11y against snapshots, reports violations
   
   # When snapshots change (after updating your UI)
   mix excessibility.approve   # Review and approve/reject changes

use Excessibility

html_snapshot(conn,
  name: "homepage.html",
  prompt_on_diff: false,
  screenshot?: true
)

The html_snapshot/2 macro works with:

• Plug.Conn
• Wallaby.Session
• Phoenix.LiveViewTest.View
• Phoenix.LiveViewTest.Element

It returns the source unchanged, so you can use it in pipelines.

Snapshots are saved to test/excessibility/html_snapshots/ and baselines live in test/excessibility/baseline/.

When a snapshot differs from its baseline:

1. Diff files are created:

   • .good.html — the current approved baseline
   • .bad.html — the new snapshot from your test

2. You choose which to keep:

   • If prompt_on_diff: true (default), both files open in your browser and you're prompted to keep "good" (baseline) or "bad" (new)
   • Choose "good" to reject the changes
   • Choose "bad" to approve the changes as the new baseline

3. Baseline is updated with your choice, and the .good.html/.bad.html files are cleaned up

First run: If no baseline exists yet, the snapshot is automatically saved as the baseline.

All configuration goes in test/test_helper.exs or config/test.exs:

Example:

# test/test_helper.exs
Application.put_env(:excessibility, :endpoint, MyAppWeb.Endpoint)
Application.put_env(:excessibility, :system_mod, Excessibility.System)
Application.put_env(:excessibility, :browser_mod, Wallaby.Browser)
Application.put_env(:excessibility, :live_view_mod, Excessibility.LiveView)
Application.put_env(:excessibility, :excessibility_output_path, "test/accessibility")

ExUnit.start()

The installer creates a pa11y.json in your project root with sensible defaults for Phoenix/LiveView:

{
  "ignore": [
    "WCAG2AA.Principle3.Guideline3_2.3_2_2.H32.2"
  ]
}

The ignored rule (H32.2) is "Form does not contain a submit button" — a common false positive for LiveView forms that use phx-submit without traditional submit buttons.

Add additional rules to ignore as needed for your project:

{
  "ignore": [
    "WCAG2AA.Principle3.Guideline3_2.3_2_2.H32.2",
    "WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail"
  ]
}

To enable PNG screenshots, start ChromicPDF in your test helper:

# test/test_helper.exs
{:ok, _} = ChromicPDF.start_link(name: ChromicPDF)

ExUnit.start()

Then use screenshot?: true in your snapshots:

html_snapshot(conn, screenshot?: true)

Screenshots are saved alongside HTML files with .png extension.

For CI or headless environments where you don't want interactive prompts or browser opens, mock the system module:

# test/test_helper.exs
Mox.defmock(Excessibility.SystemMock, for: Excessibility.SystemBehaviour)
Application.put_env(:excessibility, :system_mod, Excessibility.SystemMock)

Then stub in your tests:

import Mox

setup :verify_on_exit!

test "snapshot without browser open", %{conn: conn} do
  Excessibility.SystemMock
  |> stub(:open_with_system_cmd, fn _path -> :ok end)

  conn = get(conn, "/")
  html_snapshot(conn, open_browser?: true)  # Won't actually open
end

test/
└── excessibility/
    ├── html_snapshots/          # Current test snapshots
    │   ├── MyApp_PageTest_42.html
    │   ├── MyApp_PageTest_42.png
    │   ├── MyApp_PageTest_42.bad.html
    │   └── MyApp_PageTest_42.good.html
    └── baseline/                # Approved baselines
        └── MyApp_PageTest_42.html

MIT © Andrew Moore