excessibility: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Excessibility is an Elixir library for accessibility snapshot testing in Phoenix applications. It captures HTML snapshots during tests and runs them through Pa11y for WCAG compliance checking.

Development Commands

Testing

# Run all tests
mix test

# Run specific test file
mix test test/snapshot_test.exs

# Run tests with a specific line number
mix test test/snapshot_test.exs:42

# Run tests in watch mode (interactive)
mix test.interactive

Linting & Formatting

# Run static analysis
mix credo

# Format code (using Styler)
mix format

Documentation

# Generate documentation
mix docs

# View docs locally
open doc/index.html

Accessibility Testing

# Run Pa11y on all existing snapshots
mix excessibility

# Run specific test + Pa11y on new snapshots
mix excessibility test/my_test.exs
mix excessibility test/my_test.exs:42
mix excessibility --only a11y

# Approve pending diffs interactively
mix excessibility.approve

# Approve all diffs as good (keep baseline)
mix excessibility.approve --keep good

# Approve all diffs as bad (accept new versions)
mix excessibility.approve --keep bad

Claude Workflow for Accessibility

When helping users write accessible Phoenix code, follow this workflow:

1. Add Snapshot Calls to Tests

For any LiveView or controller test, add html_snapshot() calls to capture rendered HTML:

defmodule MyAppWeb.PageLiveTest do
  use MyAppWeb.ConnCase
  use Excessibility  # Required

  test "page is accessible", %{conn: conn} do
    {:ok, view, _html} = live(conn, "/")

    # Capture snapshot for Pa11y
    html_snapshot(view)

    # Continue with assertions...
  end
end

2. Run Tests to Generate Snapshots

mix test test/my_app_web/live/page_live_test.exs

This creates HTML files in test/excessibility/html_snapshots/.