Raxol.AccessibilityTestHelpers (Raxol v0.4.0)

View Source

Test helpers for accessibility-related assertions and simulation in Raxol. Provides assertion helpers for screen reader announcements, contrast, keyboard navigation, and focus management.

Features

  • Test helpers for screen reader announcements
  • Color contrast testing tools
  • Keyboard navigation test helpers
  • Focus management testing
  • High contrast mode testing
  • Reduced motion testing

Usage

use ExUnit.Case
import Raxol.AccessibilityTestHelpers

test "button has proper contrast ratio" do
  assert_sufficient_contrast("#0077CC", "#FFFFFF")
end

test "screen reader announcement is made" do
  with_screen_reader_spy fn ->
    # Perform action that should trigger announcement
    click_button("Save")

    # Assert announcement was made
    assert_announced("File saved successfully")
  end
end

Summary

Functions

Assert that a specific announcement was made to the screen reader.

Assert that the focus is on a specific element.

Assert that no announcements were made to the screen reader.

Assert that a color combination has sufficient contrast for accessibility.

Spy handler for screen reader announcements.

Spy handler for shortcut execution.

Simulate a keyboard navigation sequence.

Test keyboard shortcut handling.

Test high contrast mode.

Run a test with a spy on screen reader announcements.

Functions

assert_announced(expected, opts \\ [])

Assert that a specific announcement was made to the screen reader.

Parameters

  • expected - The expected announcement text or pattern
  • opts - Additional options

Options

  • :exact - Require exact match (default: false)
  • :context - Additional context for the error message

Examples

assert_announced("File saved")

assert_announced(~r/File .* saved/, exact: false)

assert_focus_on(expected, opts \\ [])

Assert that the focus is on a specific element.

Parameters

  • expected - The expected focused element
  • opts - Additional options

Options

  • :context - Additional context for the error message

Examples

assert_focus_on("search_button")

assert_no_announcements(opts \\ [])

Assert that no announcements were made to the screen reader.

Parameters

  • opts - Additional options

Options

  • :context - Additional context for the error message

Examples

assert_no_announcements()

assert_sufficient_contrast(foreground, background, level \\ :aa, size \\ :normal, opts \\ [])

Assert that a color combination has sufficient contrast for accessibility.

Parameters

  • foreground - The foreground color (typically text)
  • background - The background color
  • level - The WCAG level to check against (:aa or :aaa) (default: :aa)
  • size - The text size (:normal or :large) (default: :normal)
  • opts - Additional options

Options

  • :context - Additional context for the error message

Examples

assert_sufficient_contrast("#000000", "#FFFFFF")

assert_sufficient_contrast("#777777", "#FFFFFF", :aaa, :large)

handle_announcement_spy(arg)

Spy handler for screen reader announcements.

handle_shortcut_spy(arg)

Spy handler for shortcut execution.

simulate_keyboard_navigation(count, opts \\ [])

Simulate a keyboard navigation sequence.

This function simulates pressing the tab key to navigate through focusable elements.

Parameters

  • count - Number of tab key presses to simulate
  • opts - Additional options

Options

  • :shift - Whether to use Shift+Tab (backward navigation) (default: false)
  • :starting_element - Element to start navigation from (default: current focus)

Examples

simulate_keyboard_navigation(3)

simulate_keyboard_navigation(2, shift: true)

simulate_keyboard_navigation(1, starting_element: "search_field")

test_keyboard_shortcut(shortcut, opts \\ [])

Test keyboard shortcut handling.

This function simulates pressing a keyboard shortcut and verifies that the appropriate action is triggered.

Parameters

  • shortcut - The shortcut to test (e.g., "Ctrl+S")
  • opts - Additional options

Options

  • :context - Additional context for the error message
  • :in_context - The context in which to test the shortcut

Examples

test_keyboard_shortcut("Ctrl+S")

test_keyboard_shortcut("Ctrl+F", in_context: :editor)

with_high_contrast(fun)

Test high contrast mode.

This function temporarily enables high contrast mode, runs the provided function, and then restores the previous setting.

Examples

with_high_contrast fn ->
  # Test how elements look in high contrast mode
  assert color_of("button") == "#FFFFFF"
end

with_reduced_motion(fun_or_pid, fun \\ nil)

Test reduced motion mode.

This function temporarily enables reduced motion mode, runs the provided function, and then restores the previous setting.

Examples

with_reduced_motion fn ->
  # Test animations with reduced motion
  refute animation_running?("focus_ring", :pulse)
end

with_screen_reader_spy(pid, fun)

Run a test with a spy on screen reader announcements.

This function sets up a spy to capture screen reader announcements during the execution of the provided function, allowing you to assert that specific announcements were made.

Examples

with_screen_reader_spy(user_preferences_pid, fn ->
  # Perform action
  click_button("Save")

  # Assert announcement
  assert_announced("File saved successfully")
end)