Add accessibility audits, options, and assertions

Introduce built-in accessibility support: adds AccessibilityMode and AccessibilityOptions, a new AccessibilityAuditHook plugin that can run audits after navigation or certain actions (disabled by default), and wires the hook into PluginHost. Expose LastAccessibilityAudit on Page and add Locator methods to query accessible name/role via AX tree. Add ToPassAccessibilityAuditAsync assertion and AccessibilityAssertionOptions to configure skipped rules and warning handling. Integrate accessibility settings into Motus config/JSON context and merge defaults in ConfigMerge. Update DuplicateIdCollector docs and adjust PluginHost tests to account for the added builtin; include comprehensive unit tests for the audit hook and assertions.

Author: TorreyBetts

src/Motus.Abstractions/Enums/AccessibilityMode.cs

@@ -0,0 +1,16 @@
+namespace Motus.Abstractions;
+
+/// <summary>
+/// Controls how the accessibility audit hook handles violations.
+/// </summary>
+public enum AccessibilityMode
+{
+    /// <summary>Accessibility auditing is disabled.</summary>
+    Off,
+
+    /// <summary>Violations are reported but do not fail tests.</summary>
+    Warn,
+
+    /// <summary>Error-severity violations cause test failures.</summary>
+    Enforce
+}

src/Motus.Abstractions/Options/AccessibilityOptions.cs

@@ -0,0 +1,28 @@
+namespace Motus.Abstractions;
+
+/// <summary>
+/// Configuration for the built-in accessibility audit hook.
+/// </summary>
+public sealed record AccessibilityOptions
+{
+    /// <summary>Whether the accessibility audit hook is enabled. Default: false.</summary>
+    public bool Enable { get; init; }
+
+    /// <summary>How violations are handled. Default: Enforce.</summary>
+    public AccessibilityMode Mode { get; init; } = AccessibilityMode.Enforce;
+
+    /// <summary>Whether to run an audit after each navigation. Default: true.</summary>
+    public bool AuditAfterNavigation { get; init; } = true;
+
+    /// <summary>
+    /// Whether to run an audit after mutating actions (click, fill, selectOption).
+    /// Default: false.
+    /// </summary>
+    public bool AuditAfterActions { get; init; }
+
+    /// <summary>Whether warnings count as failures alongside errors. Default: true.</summary>
+    public bool IncludeWarnings { get; init; } = true;
+
+    /// <summary>Rule IDs to exclude from audits (e.g., "a11y-color-contrast").</summary>
+    public IReadOnlyList<string>? SkipRules { get; init; }
+}

src/Motus.Abstractions/Options/LaunchOptions.cs

@@ -40,4 +40,7 @@ public sealed record LaunchOptions
 
     /// <summary>Manually registered plugins to load into each browser context.</summary>
     public IReadOnlyList<IPlugin>? Plugins { get; init; }
+
+    /// <summary>Accessibility audit hook configuration. Disabled by default.</summary>
+    public AccessibilityOptions? Accessibility { get; init; }
 }

src/Motus/Accessibility/AccessibilityAuditHook.cs

@@ -0,0 +1,85 @@
+using Motus.Abstractions;
+
+namespace Motus;
+
+/// <summary>
+/// Built-in plugin that runs accessibility audits after navigation and (optionally)
+/// after mutating actions. Disabled by default; enabled via <see cref="AccessibilityOptions"/>.
+/// </summary>
+internal sealed class AccessibilityAuditHook : IPlugin, ILifecycleHook
+{
+    private static readonly HashSet<string> AuditedActions = new(StringComparer.Ordinal)
+    {
+        "click", "fill", "selectOption"
+    };
+
+    private readonly AccessibilityOptions _options;
+    private BrowserContext? _context;
+
+    internal AccessibilityAuditHook(AccessibilityOptions? options)
+    {
+        _options = options ?? new AccessibilityOptions();
+    }
+
+    public string PluginId => "motus.accessibility-audit";
+    public string Name => "Accessibility Audit Hook";
+    public string Version => "1.0.0";
+    public string? Author => "Motus";
+    public string? Description => "Runs WCAG accessibility audits after navigation and actions.";
+
+    public Task OnLoadedAsync(IPluginContext context)
+    {
+        if (!_options.Enable)
+            return Task.CompletedTask;
+
+        _context = ((PluginContext)context).Context;
+        context.RegisterLifecycleHook(this);
+        return Task.CompletedTask;
+    }
+
+    public Task OnUnloadedAsync() => Task.CompletedTask;
+
+    public Task BeforeNavigationAsync(IPage page, string url) => Task.CompletedTask;
+
+    public async Task AfterNavigationAsync(IPage page, IResponse? response)
+    {
+        if (!_options.AuditAfterNavigation || _context is null)
+            return;
+
+        await RunAuditAsync(page).ConfigureAwait(false);
+    }
+
+    public Task BeforeActionAsync(IPage page, string action) => Task.CompletedTask;
+
+    public async Task AfterActionAsync(IPage page, string action, ActionResult result)
+    {
+        if (!_options.AuditAfterActions || _context is null || !AuditedActions.Contains(action))
+            return;
+
+        await RunAuditAsync(page).ConfigureAwait(false);
+    }
+
+    public Task OnPageCreatedAsync(IPage page) => Task.CompletedTask;
+    public Task OnPageClosedAsync(IPage page) => Task.CompletedTask;
+    public Task OnConsoleMessageAsync(IPage page, ConsoleMessageEventArgs message) => Task.CompletedTask;
+    public Task OnPageErrorAsync(IPage page, PageErrorEventArgs error) => Task.CompletedTask;
+
+    private async Task RunAuditAsync(IPage page)
+    {
+        var concrete = (Page)page;
+        var rules = FilterRules(_context!.AccessibilityRules.Snapshot());
+        var result = await concrete.RunAccessibilityAuditAsync(rules, CancellationToken.None)
+            .ConfigureAwait(false);
+        concrete.LastAccessibilityAudit = result;
+    }
+
+    private IReadOnlyList<IAccessibilityRule> FilterRules(IReadOnlyList<IAccessibilityRule> rules)
+    {
+        var skip = _options.SkipRules;
+        if (skip is null or { Count: 0 })
+            return rules;
+
+        var skipSet = new HashSet<string>(skip, StringComparer.Ordinal);
+        return rules.Where(r => !skipSet.Contains(r.RuleId)).ToList();
+    }
+}

src/Motus/Accessibility/DuplicateIdCollector.cs

@@ -1,7 +1,16 @@
 namespace Motus;
 
 /// <summary>
-/// Pre-fetches the set of duplicate HTML id values in the document via DOM domain queries.
+/// Pre-fetches the set of duplicate HTML id values in the document.
+///
+/// Uses Runtime.evaluate with a JS snippet rather than DOM.getDocument + DOM.querySelectorAll
+/// CDP commands, which reduces the interaction to a single CDP round-trip rather than three
+/// or more (getDocument, querySelectorAll, then getAttributes per matched node).
+///
+/// Risk: If page-level JS execution is restricted (e.g., certain CSP configurations), this
+/// will silently return no duplicates. The DOM domain commands operate at the protocol level
+/// and are unaffected by page JS restrictions. In practice the risk is low because Motus
+/// controls the browser instance and JS execution is always available.
 /// </summary>
 internal static class DuplicateIdCollector
 {

src/Motus/Assertions/AccessibilityAssertionOptions.cs

@@ -0,0 +1,23 @@
+namespace Motus.Assertions;
+
+/// <summary>
+/// Configuration for the <c>ToPassAccessibilityAuditAsync</c> assertion.
+/// </summary>
+public sealed class AccessibilityAssertionOptions
+{
+    private readonly List<string> _skip = [];
+
+    /// <summary>
+    /// Excludes the specified rule IDs from the pass/fail evaluation.
+    /// </summary>
+    public AccessibilityAssertionOptions SkipRules(params string[] ruleIds)
+    {
+        _skip.AddRange(ruleIds);
+        return this;
+    }
+
+    /// <summary>Whether warnings count as failures alongside errors. Default: true.</summary>
+    public bool IncludeWarnings { get; set; } = true;
+
+    internal IReadOnlyList<string> SkippedRules => _skip;
+}

src/Motus/Assertions/LocatorAssertions.cs

@@ -157,4 +157,18 @@ public Task ToHaveCountAsync(int expected, AssertionOptions? options = null) =>
             var count = await _locator.CountAsync().ConfigureAwait(false);
             return (count == expected, count.ToString());
         }, "ToHaveCount", expected.ToString(), options);
+
+    public Task ToHaveAccessibleNameAsync(string expected, AssertionOptions? options = null) =>
+        RetryAsync(async ct =>
+        {
+            var name = await _locator.GetAccessibilityNameAsync(ct).ConfigureAwait(false) ?? "";
+            return (name == expected, name);
+        }, "ToHaveAccessibleName", expected, options);
+
+    public Task ToHaveRoleAsync(string expected, AssertionOptions? options = null) =>
+        RetryAsync(async ct =>
+        {
+            var role = await _locator.GetAccessibilityRoleAsync(ct).ConfigureAwait(false) ?? "";
+            return (role == expected, role);
+        }, "ToHaveRole", expected, options);
 }

src/Motus/Assertions/PageAssertions.cs

@@ -38,4 +38,92 @@ public Task ToHaveTitleAsync(string expected, AssertionOptions? options = null)
             var title = await _page.TitleAsync().ConfigureAwait(false);
             return (title == expected, title);
         }, "ToHaveTitle", expected, options);
+
+    public async Task ToPassAccessibilityAuditAsync(
+        Action<AccessibilityAssertionOptions>? configure = null,
+        AssertionOptions? options = null)
+    {
+        var a11yOptions = new AccessibilityAssertionOptions();
+        configure?.Invoke(a11yOptions);
+
+        var result = _page.LastAccessibilityAudit;
+        if (result is null)
+        {
+            // On-demand audit: no hook stored a result, so run one now
+            var rules = FilterRules(
+                _page.ContextInternal.AccessibilityRules.Snapshot(),
+                a11yOptions.SkippedRules);
+            result = await _page.RunAccessibilityAuditAsync(rules, CancellationToken.None)
+                .ConfigureAwait(false);
+        }
+
+        var violations = FilterViolations(result.Violations, a11yOptions);
+        var hasViolations = violations.Count > 0;
+        var passed = _negate ? hasViolations : !hasViolations;
+
+        if (!passed)
+        {
+            var negateLabel = _negate ? "NOT " : "";
+            var expected = $"{negateLabel}0 accessibility violations";
+            var actual = FormatViolations(violations);
+            var message = options?.Message
+                ?? $"Assertion {negateLabel}ToPassAccessibilityAudit failed."
+                   + $" Expected: {expected}. Found {violations.Count} violation(s)."
+                   + (_page.Url is not null ? $" Page: {_page.Url}." : "");
+
+            throw new MotusAssertionException(
+                expected: expected,
+                actual: actual,
+                selector: null,
+                pageUrl: _page.Url,
+                assertionTimeout: TimeSpan.Zero,
+                message: message);
+        }
+    }
+
+    private static IReadOnlyList<IAccessibilityRule> FilterRules(
+        IReadOnlyList<IAccessibilityRule> rules, IReadOnlyList<string> skippedRules)
+    {
+        if (skippedRules.Count == 0)
+            return rules;
+
+        var skipSet = new HashSet<string>(skippedRules, StringComparer.Ordinal);
+        return rules.Where(r => !skipSet.Contains(r.RuleId)).ToList();
+    }
+
+    private static IReadOnlyList<AccessibilityViolation> FilterViolations(
+        IReadOnlyList<AccessibilityViolation> violations,
+        AccessibilityAssertionOptions options)
+    {
+        var filtered = violations.AsEnumerable();
+
+        if (options.SkippedRules.Count > 0)
+        {
+            var skipSet = new HashSet<string>(options.SkippedRules, StringComparer.Ordinal);
+            filtered = filtered.Where(v => !skipSet.Contains(v.RuleId));
+        }
+
+        if (!options.IncludeWarnings)
+            filtered = filtered.Where(v => v.Severity == AccessibilityViolationSeverity.Error);
+        else
+            filtered = filtered.Where(v =>
+                v.Severity is AccessibilityViolationSeverity.Error
+                           or AccessibilityViolationSeverity.Warning);
+
+        return filtered.ToList();
+    }
+
+    private static string FormatViolations(IReadOnlyList<AccessibilityViolation> violations)
+    {
+        var sb = new System.Text.StringBuilder();
+        sb.AppendLine($"Accessibility audit failed with {violations.Count} violation(s):");
+        foreach (var v in violations)
+        {
+            sb.Append($"  [{v.Severity}] {v.RuleId}: {v.Message}");
+            if (v.Selector is not null)
+                sb.Append($" (selector: {v.Selector})");
+            sb.AppendLine();
+        }
+        return sb.ToString().TrimEnd();
+    }
 }

src/Motus/Config/ConfigMerge.cs

@@ -6,24 +6,45 @@ internal static class ConfigMerge
 {
     internal static LaunchOptions ApplyConfig(LaunchOptions options)
     {
+        var result = options;
+
         var launch = MotusConfigLoader.Config.Launch;
-        if (launch is null)
-            return options;
+        if (launch is not null)
+        {
+            if (options.Headless && launch.Headless.HasValue)
+                result = result with { Headless = launch.Headless.Value };
 
-        var result = options;
+            if (options.Channel is null && launch.Channel is not null
+                && Enum.TryParse<BrowserChannel>(launch.Channel, ignoreCase: true, out var channel))
+                result = result with { Channel = channel };
 
-        if (options.Headless && launch.Headless.HasValue)
-            result = result with { Headless = launch.Headless.Value };
+            if (options.SlowMo == 0 && launch.SlowMo.HasValue)
+                result = result with { SlowMo = launch.SlowMo.Value };
 
-        if (options.Channel is null && launch.Channel is not null
-            && Enum.TryParse<BrowserChannel>(launch.Channel, ignoreCase: true, out var channel))
-            result = result with { Channel = channel };
+            if (options.Timeout == 30_000 && launch.Timeout.HasValue)
+                result = result with { Timeout = launch.Timeout.Value };
+        }
 
-        if (options.SlowMo == 0 && launch.SlowMo.HasValue)
-            result = result with { SlowMo = launch.SlowMo.Value };
+        var a11y = MotusConfigLoader.Config.Accessibility;
+        if (a11y is not null && options.Accessibility is null)
+        {
+            var mode = AccessibilityMode.Enforce;
+            if (a11y.Mode is not null)
+                Enum.TryParse(a11y.Mode, ignoreCase: true, out mode);
 
-        if (options.Timeout == 30_000 && launch.Timeout.HasValue)
-            result = result with { Timeout = launch.Timeout.Value };
+            result = result with
+            {
+                Accessibility = new AccessibilityOptions
+                {
+                    Enable = a11y.Enable ?? false,
+                    Mode = mode,
+                    AuditAfterNavigation = a11y.AuditAfterNavigation ?? true,
+                    AuditAfterActions = a11y.AuditAfterActions ?? false,
+                    IncludeWarnings = a11y.IncludeWarnings ?? true,
+                    SkipRules = a11y.SkipRules,
+                }
+            };
+        }
 
         return result;
     }