Add performance budget support

Introduce performance budget functionality: add PerformanceBudgetAttribute to declare per-test/class thresholds and map sentinel values to nullable PerformanceBudget. Implement PerformanceBudgetContext (AsyncLocal) to hold ambient budget for the current async test flow. Add PageAssertions methods (ToMeetPerformanceBudgetAsync and individual metric checks) that resolve budgets from the ambient context or motus.config.json and format failures. Integrate budget push/clear into MSTest/NUnit/xUnit test setup/teardown to apply method/class attributes. Extend configuration with MotusPerformanceConfig, JSON context generation, env var parsing, and ConfigMerge.ToBudget/merging logic. Add comprehensive unit tests for assertions, attribute mapping, context behavior and config deserialization. Also include small cleanups: tweak BrowserFinder comment and refine Download cancellation exception message.

Author: TorreyBetts

src/Motus.Abstractions/Attributes/PerformanceBudgetAttribute.cs

@@ -0,0 +1,49 @@
+namespace Motus.Abstractions;
+
+/// <summary>
+/// Declares performance budget thresholds for a test method or class.
+/// Only specified metrics (values >= 0) are enforced. Method-level attributes
+/// override class-level attributes.
+/// </summary>
+[AttributeUsage(
+    AttributeTargets.Method | AttributeTargets.Class,
+    AllowMultiple = false,
+    Inherited = true)]
+public sealed class PerformanceBudgetAttribute : Attribute
+{
+    /// <summary>Maximum Largest Contentful Paint in milliseconds. -1 means not set.</summary>
+    public double Lcp { get; set; } = -1;
+
+    /// <summary>Maximum First Contentful Paint in milliseconds. -1 means not set.</summary>
+    public double Fcp { get; set; } = -1;
+
+    /// <summary>Maximum Time to First Byte in milliseconds. -1 means not set.</summary>
+    public double Ttfb { get; set; } = -1;
+
+    /// <summary>Maximum Cumulative Layout Shift score. -1 means not set.</summary>
+    public double Cls { get; set; } = -1;
+
+    /// <summary>Maximum Interaction to Next Paint in milliseconds. -1 means not set.</summary>
+    public double Inp { get; set; } = -1;
+
+    /// <summary>Maximum JavaScript heap size in bytes. -1 means not set.</summary>
+    public long JsHeapSize { get; set; } = -1;
+
+    /// <summary>Maximum DOM node count. -1 means not set.</summary>
+    public int DomNodeCount { get; set; } = -1;
+
+    /// <summary>
+    /// Converts the attribute values to a <see cref="PerformanceBudget"/> record.
+    /// Sentinel values (-1) are mapped to null (not enforced).
+    /// </summary>
+    public PerformanceBudget ToBudget() => new()
+    {
+        Lcp = Lcp >= 0 ? Lcp : null,
+        Fcp = Fcp >= 0 ? Fcp : null,
+        Ttfb = Ttfb >= 0 ? Ttfb : null,
+        Cls = Cls >= 0 ? Cls : null,
+        Inp = Inp >= 0 ? Inp : null,
+        JsHeapSize = JsHeapSize >= 0 ? JsHeapSize : null,
+        DomNodeCount = DomNodeCount >= 0 ? DomNodeCount : null,
+    };
+}

src/Motus.Testing.MSTest/MotusTestBase.cs

@@ -1,3 +1,4 @@
+using System.Reflection;
 using Microsoft.VisualStudio.TestTools.UnitTesting;
 using Motus.Abstractions;
 
@@ -73,6 +74,15 @@ public async Task MotusTestInitialize()
 
         _failureTracing = new FailureTracing();
         await _failureTracing.StartIfEnabledAsync(_context).ConfigureAwait(false);
+
+        var testMethodName = TestContext?.TestName;
+        var methodInfo = testMethodName is not null
+            ? GetType().GetMethod(testMethodName, BindingFlags.Public | BindingFlags.Instance)
+            : null;
+        var methodAttr = methodInfo?.GetCustomAttribute<PerformanceBudgetAttribute>();
+        var classAttr = GetType().GetCustomAttribute<PerformanceBudgetAttribute>();
+        var activeAttr = methodAttr ?? classAttr;
+        PerformanceBudgetContext.Push(activeAttr?.ToBudget());
     }
 
     [TestCleanup]
@@ -88,5 +98,7 @@ public async Task MotusTestCleanup()
             _context = null;
             _page = null;
         }
+
+        PerformanceBudgetContext.Clear();
     }
 }

src/Motus.Testing.NUnit/MotusTestBase.cs

@@ -1,3 +1,4 @@
+using System.Reflection;
 using Motus.Abstractions;
 using NUnit.Framework;
 
@@ -66,6 +67,12 @@ public async Task SetUp()
 
         _failureTracing = new FailureTracing();
         await _failureTracing.StartIfEnabledAsync(_context);
+
+        var methodInfo = TestContext.CurrentContext.Test.Method?.MethodInfo;
+        var methodAttr = methodInfo?.GetCustomAttribute<PerformanceBudgetAttribute>();
+        var classAttr = GetType().GetCustomAttribute<PerformanceBudgetAttribute>();
+        var activeAttr = methodAttr ?? classAttr;
+        PerformanceBudgetContext.Push(activeAttr?.ToBudget());
     }
 
     [TearDown]
@@ -81,5 +88,7 @@ public async Task TearDown()
             _context = null;
             _page = null;
         }
+
+        PerformanceBudgetContext.Clear();
     }
 }

src/Motus.Testing.xUnit/BrowserContextFixture.cs

@@ -1,3 +1,4 @@
+using System.Reflection;
 using Motus.Abstractions;
 using Xunit;
 
@@ -42,6 +43,9 @@ public async Task InitializeAsync()
     {
         _context = await _browserFixture.NewContextAsync(ContextOptions);
         _page = await _context.NewPageAsync();
+
+        var classAttr = GetType().GetCustomAttribute<PerformanceBudgetAttribute>();
+        PerformanceBudgetContext.Push(classAttr?.ToBudget());
     }
 
     public async Task DisposeAsync()
@@ -52,5 +56,7 @@ public async Task DisposeAsync()
             _context = null;
             _page = null;
         }
+
+        PerformanceBudgetContext.Clear();
     }
 }

src/Motus/Assertions/PageAssertions.cs

@@ -81,6 +81,105 @@ public async Task ToPassAccessibilityAuditAsync(
         }
     }
 
+    public async Task ToMeetPerformanceBudgetAsync(AssertionOptions? options = null)
+    {
+        var budget = ResolveBudget();
+
+        await RetryAsync(async ct =>
+        {
+            var metrics = _page.LastPerformanceMetrics;
+            if (metrics is null)
+                return (false, "<no metrics collected>");
+
+            var result = budget.Evaluate(metrics);
+            var actual = result.Passed
+                ? "all metrics within budget"
+                : FormatBudgetFailures(result);
+            return (result.Passed, actual);
+        }, "ToMeetPerformanceBudget", "all metrics within budget", options)
+            .ConfigureAwait(false);
+    }
+
+    public Task ToHaveLcpBelowAsync(double thresholdMs, AssertionOptions? options = null) =>
+        RetryAsync(async ct =>
+        {
+            var metrics = _page.LastPerformanceMetrics;
+            if (metrics?.Lcp is null)
+                return (false, "<LCP not collected>");
+            var actual = metrics.Lcp.Value;
+            return (actual <= thresholdMs, $"{actual:F1}ms");
+        }, "ToHaveLcpBelow", $"< {thresholdMs}ms", options);
+
+    public Task ToHaveFcpBelowAsync(double thresholdMs, AssertionOptions? options = null) =>
+        RetryAsync(async ct =>
+        {
+            var metrics = _page.LastPerformanceMetrics;
+            if (metrics?.Fcp is null)
+                return (false, "<FCP not collected>");
+            var actual = metrics.Fcp.Value;
+            return (actual <= thresholdMs, $"{actual:F1}ms");
+        }, "ToHaveFcpBelow", $"< {thresholdMs}ms", options);
+
+    public Task ToHaveTtfbBelowAsync(double thresholdMs, AssertionOptions? options = null) =>
+        RetryAsync(async ct =>
+        {
+            var metrics = _page.LastPerformanceMetrics;
+            if (metrics?.Ttfb is null)
+                return (false, "<TTFB not collected>");
+            var actual = metrics.Ttfb.Value;
+            return (actual <= thresholdMs, $"{actual:F1}ms");
+        }, "ToHaveTtfbBelow", $"< {thresholdMs}ms", options);
+
+    public Task ToHaveClsBelowAsync(double threshold, AssertionOptions? options = null) =>
+        RetryAsync(async ct =>
+        {
+            var metrics = _page.LastPerformanceMetrics;
+            if (metrics?.Cls is null)
+                return (false, "<CLS not collected>");
+            var actual = metrics.Cls.Value;
+            return (actual <= threshold, $"{actual:F3}");
+        }, "ToHaveClsBelow", $"< {threshold}", options);
+
+    public Task ToHaveInpBelowAsync(double thresholdMs, AssertionOptions? options = null) =>
+        RetryAsync(async ct =>
+        {
+            var metrics = _page.LastPerformanceMetrics;
+            if (metrics?.Inp is null)
+                return (false, "<INP not collected>");
+            var actual = metrics.Inp.Value;
+            return (actual <= thresholdMs, $"{actual:F1}ms");
+        }, "ToHaveInpBelow", $"< {thresholdMs}ms", options);
+
+    private static PerformanceBudget ResolveBudget()
+    {
+        if (PerformanceBudgetContext.Current is { } ambient)
+            return ambient;
+
+        var configBudget = ConfigMerge.ToBudget(MotusConfigLoader.Config.Performance);
+        if (configBudget is not null)
+            return configBudget;
+
+        throw new InvalidOperationException(
+            "No performance budget is active. Apply [PerformanceBudget] to the test method or class, " +
+            "or configure budget thresholds in motus.config.json under the \"performance\" key.");
+    }
+
+    private static string FormatBudgetFailures(PerformanceBudgetResult result)
+    {
+        var sb = new System.Text.StringBuilder();
+        sb.AppendLine("Performance budget exceeded:");
+        foreach (var entry in result.Entries)
+        {
+            if (!entry.Passed)
+            {
+                var actualStr = entry.ActualValue.HasValue ? $"{entry.ActualValue.Value:F1}" : "null";
+                var deltaStr = entry.Delta.HasValue ? $"{entry.Delta.Value:F1}" : "?";
+                sb.AppendLine($"  {entry.MetricName}: {actualStr} (budget: {entry.Threshold:F1}, over by {deltaStr})");
+            }
+        }
+        return sb.ToString().TrimEnd();
+    }
+
     private static IReadOnlyList<IAccessibilityRule> FilterRules(
         IReadOnlyList<IAccessibilityRule> rules, IReadOnlyList<string> skippedRules)
     {

src/Motus/Browser/BrowserFinder.cs

@@ -10,7 +10,7 @@ internal static class BrowserFinder
 {
     /// <summary>
     /// When set, this path is prepended to candidate lists for all channels.
-    /// Used by the install system (Phase 3D) to register downloaded binaries.
+    /// Used by the install system to register downloaded binaries.
     /// </summary>
     internal static string? InstalledBinariesPath { get; set; }
 

src/Motus/Config/ConfigMerge.cs

@@ -46,9 +46,44 @@ internal static LaunchOptions ApplyConfig(LaunchOptions options)
             };
         }
 
+        var perf = MotusConfigLoader.Config.Performance;
+        if (perf is not null && options.Performance is null)
+        {
+            result = result with
+            {
+                Performance = new PerformanceOptions
+                {
+                    Enable = perf.Enable ?? false,
+                    CollectAfterNavigation = perf.CollectAfterNavigation ?? true,
+                }
+            };
+        }
+
         return result;
     }
 
+    internal static PerformanceBudget? ToBudget(MotusPerformanceConfig? cfg)
+    {
+        if (cfg is null)
+            return null;
+
+        if (cfg.Lcp is null && cfg.Fcp is null && cfg.Ttfb is null &&
+            cfg.Cls is null && cfg.Inp is null && cfg.JsHeapSize is null &&
+            cfg.DomNodeCount is null)
+            return null;
+
+        return new PerformanceBudget
+        {
+            Lcp = cfg.Lcp,
+            Fcp = cfg.Fcp,
+            Ttfb = cfg.Ttfb,
+            Cls = cfg.Cls,
+            Inp = cfg.Inp,
+            JsHeapSize = cfg.JsHeapSize,
+            DomNodeCount = cfg.DomNodeCount,
+        };
+    }
+
     internal static ContextOptions ApplyConfig(ContextOptions options)
     {
         var context = MotusConfigLoader.Config.Context;

src/Motus/Config/MotusConfig.cs

@@ -49,6 +49,17 @@ internal sealed record MotusAccessibilityConfig(
     bool? IncludeWarnings = null,
     string[]? SkipRules = null);
 
+internal sealed record MotusPerformanceConfig(
+    bool? Enable = null,
+    bool? CollectAfterNavigation = null,
+    double? Lcp = null,
+    double? Fcp = null,
+    double? Ttfb = null,
+    double? Cls = null,
+    double? Inp = null,
+    long? JsHeapSize = null,
+    int? DomNodeCount = null);
+
 internal sealed record MotusRootConfig(
     string? Motus = null,
     MotusLaunchConfig? Launch = null,
@@ -58,7 +69,8 @@ internal sealed record MotusRootConfig(
     MotusAssertionsConfig? Assertions = null,
     MotusRecorderConfig? Recorder = null,
     MotusFailureConfig? Failure = null,
-    MotusAccessibilityConfig? Accessibility = null);
+    MotusAccessibilityConfig? Accessibility = null,
+    MotusPerformanceConfig? Performance = null);
 
 internal static class MotusConfigLoader
 {
@@ -177,6 +189,33 @@ private static MotusRootConfig ApplyEnvironmentVariables(MotusRootConfig config,
         if (envReader("MOTUS_ACCESSIBILITY_MODE") is { Length: > 0 } a11yMode)
         { accessibility = accessibility with { Mode = a11yMode }; accessibilityChanged = true; }
 
+        var performance = config.Performance ?? new MotusPerformanceConfig();
+        var performanceChanged = false;
+
+        if (TryParseBool(envReader("MOTUS_PERFORMANCE_ENABLE"), out var perfEnable))
+        { performance = performance with { Enable = perfEnable }; performanceChanged = true; }
+
+        if (TryParseDouble(envReader("MOTUS_PERFORMANCE_LCP"), out var perfLcp))
+        { performance = performance with { Lcp = perfLcp }; performanceChanged = true; }
+
+        if (TryParseDouble(envReader("MOTUS_PERFORMANCE_FCP"), out var perfFcp))
+        { performance = performance with { Fcp = perfFcp }; performanceChanged = true; }
+
+        if (TryParseDouble(envReader("MOTUS_PERFORMANCE_TTFB"), out var perfTtfb))
+        { performance = performance with { Ttfb = perfTtfb }; performanceChanged = true; }
+
+        if (TryParseDouble(envReader("MOTUS_PERFORMANCE_CLS"), out var perfCls))
+        { performance = performance with { Cls = perfCls }; performanceChanged = true; }
+
+        if (TryParseDouble(envReader("MOTUS_PERFORMANCE_INP"), out var perfInp))
+        { performance = performance with { Inp = perfInp }; performanceChanged = true; }
+
+        if (TryParseLong(envReader("MOTUS_PERFORMANCE_JS_HEAP_SIZE"), out var perfHeap))
+        { performance = performance with { JsHeapSize = perfHeap }; performanceChanged = true; }
+
+        if (TryParseInt(envReader("MOTUS_PERFORMANCE_DOM_NODE_COUNT"), out var perfDom))
+        { performance = performance with { DomNodeCount = perfDom }; performanceChanged = true; }
+
         return config with
         {
             Launch = launchChanged ? launch : config.Launch,
@@ -185,6 +224,7 @@ private static MotusRootConfig ApplyEnvironmentVariables(MotusRootConfig config,
             Assertions = assertionsChanged ? assertions : config.Assertions,
             Failure = failureChanged ? failure : config.Failure,
             Accessibility = accessibilityChanged ? accessibility : config.Accessibility,
+            Performance = performanceChanged ? performance : config.Performance,
         };
     }
 
@@ -207,4 +247,20 @@ private static bool TryParseInt(string? value, out int result)
         result = default;
         return false;
     }
+
+    private static bool TryParseDouble(string? value, out double result)
+    {
+        if (value is not null && double.TryParse(value.Trim(), System.Globalization.CultureInfo.InvariantCulture, out result))
+            return true;
+        result = default;
+        return false;
+    }
+
+    private static bool TryParseLong(string? value, out long result)
+    {
+        if (value is not null && long.TryParse(value.Trim(), out result))
+            return true;
+        result = default;
+        return false;
+    }
 }

src/Motus/Config/MotusConfigJsonContext.cs

@@ -13,6 +13,7 @@ namespace Motus;
 [JsonSerializable(typeof(MotusReporterConfig))]
 [JsonSerializable(typeof(MotusRecorderConfig))]
 [JsonSerializable(typeof(MotusAccessibilityConfig))]
+[JsonSerializable(typeof(MotusPerformanceConfig))]
 [JsonSourceGenerationOptions(
     PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
     DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull)]

src/Motus/Download/Download.cs

@@ -68,7 +68,7 @@ public Task DeleteAsync()
     }
 
     public Task CancelAsync()
-        => throw new NotSupportedException("Download cancellation requires Fetch domain (Phase 1J).");
+        => throw new NotSupportedException("Download cancellation requires Fetch domain support.");
 
     private readonly record struct DownloadOutcome(bool Success, string? Error);
 }