Add performance testing docs and integration

Introduce performance testing features and documentation: add a new performance testing guide, document Core Web Vitals and supplementary metrics (LCP, FCP, TTFB, CLS, INP, JS heap, DOM nodes), and explain budget enforcement via [PerformanceBudget] attribute or motus.config.json. Update plugin interfaces to include IPerformanceReporter and register reporter behavior; add CLI flag (--perf-budget) and environment/config options for performance collection. Document browser lifecycle health detection (heartbeat and crash handling), pool proactive replenishment, and test fixture auto-restart on crash. Update various README files and config docs to surface the new functionality and reporter integration.

Author: TorreyBetts

README.md

@@ -127,6 +127,48 @@ Or in `motus.config.json`:
 }
 ```
 
+### Performance Testing
+
+Motus collects Core Web Vitals (LCP, FCP, TTFB, CLS, INP) and supplementary metrics (JS heap size, DOM node count) directly from the browser during test execution. Set budget thresholds via attributes or config, and performance regressions fail your tests automatically.
+
+```csharp
+// Assert all metrics are within the class-level budget
+[PerformanceBudget(Lcp = 2500, Fcp = 1800, Cls = 0.1)]
+[TestClass]
+public class DashboardTests : MotusTestBase
+{
+    [TestMethod]
+    public async Task DashboardLoadsWithinBudget()
+    {
+        await Page.GotoAsync("https://app.example.com/dashboard");
+        await Expect.That(Page).ToMeetPerformanceBudgetAsync();
+    }
+}
+
+// Or assert individual metrics
+await Expect.That(page).ToHaveLcpBelowAsync(2500);
+await Expect.That(page).ToHaveClsBelowAsync(0.1);
+```
+
+Enable budget enforcement from the CLI:
+
+```bash
+motus run ./bin/Debug/net8.0/MyTests.dll --perf-budget
+```
+
+Or in `motus.config.json`:
+
+```json
+{
+  "performance": {
+    "enable": true,
+    "lcp": 2500,
+    "cls": 0.1,
+    "inp": 200
+  }
+}
+```
+
 ## How It Works
 
 Motus communicates directly with the browser over WebSocket. For Chromium-based browsers, it speaks the Chrome DevTools Protocol (CDP). For Firefox, it uses WebDriver BiDi. There is no Node.js sidecar, no driver binary, and no process boundary between your test code and the protocol layer.
@@ -158,6 +200,7 @@ Five interfaces define every point of extensibility, all registered through `IPl
 | `IReporter` | Receive test run events for custom reporting (multiple reporters run simultaneously) |
 | `IAccessibilityRule` | Define custom WCAG accessibility rules evaluated against the browser's accessibility tree |
 | `IAccessibilityReporter` | Opt-in interface for reporters to receive per-violation accessibility events |
+| `IPerformanceReporter` | Opt-in interface for reporters to receive performance metrics and budget results |
 | `IMotusLogger` | Structured logging for plugin diagnostics |
 
 ### Plugin Discovery
@@ -228,6 +271,7 @@ Launch the Blazor-based visual runner with `motus run --visual`:
 | **Recording** | Capture browser interactions and emit idiomatic C# test code (MSTest, xUnit, NUnit) |
 | **Codegen** | Generate Page Object Model classes from live pages with selector inference |
 | **Accessibility** | Built-in WCAG 2.1 Level A/AA audits via CDP accessibility tree, lifecycle hook, page and locator assertions, custom rules via `IAccessibilityRule` |
+| **Performance** | Core Web Vitals collection (LCP, FCP, TTFB, CLS, INP), configurable budgets via `[PerformanceBudget]` attribute or config, auto-retry assertions, reporter integration via `IPerformanceReporter` |
 | **Reporters** | Console, HTML, JUnit XML, TRX, plus custom reporters via `IReporter` (with opt-in `IAccessibilityReporter` for violation events) |
 | **Tracing** | Screenshots, DOM snapshots, network logs, HAR export, and WebM video recording |
 | **Parallel** | Context-level, browser-level, and worker-level parallel execution |
@@ -237,7 +281,7 @@ Launch the Blazor-based visual runner with `motus run --visual`:
 ## CLI Reference
 
 ```
-motus run <assemblies>  Run tests with optional --visual, --filter, --workers, --reporter, --a11y
+motus run <assemblies>  Run tests with optional --visual, --filter, --workers, --reporter, --a11y, --perf-budget
 motus record           Record a browser session and emit test code
 motus codegen          Generate POM classes from live pages (--headed, --connect, --detect-listeners)
 motus screenshot       Capture a screenshot (--full-page, --delay, --hide-banners, --width, --height)

docs/architecture/browser-lifecycle.md

@@ -188,10 +188,13 @@ The sequence:
 
 `CloseAsync` is the graceful shutdown path:
 
-1. All contexts are closed in sequence by calling `context.CloseAsync()`.
-2. `Browser.close` is sent over the browser-level CDP session. A `CdpDisconnectedException` is expected and caught because the browser closes the WebSocket as part of its shutdown.
-3. The owned OS process (if any) is awaited for up to **5 seconds**. If it has not exited within that window, `process.Kill(entireProcessTree: true)` is called.
-4. `IsConnected` is set to `false`.
+1. `IsConnected` is set to `false`.
+2. The `BrowserHeartbeat` (if running) is disposed, stopping background health pings.
+3. Signal handlers and the `Process.Exited` handler are unregistered.
+4. All contexts are closed in sequence by calling `context.CloseAsync()`.
+5. `Browser.close` is sent over the browser-level CDP session. A `CdpDisconnectedException` is expected and caught because the browser closes the WebSocket as part of its shutdown.
+6. The transport is disposed.
+7. The owned OS process (if any) is awaited for up to **5 seconds**. If it has not exited within that window, `process.Kill(entireProcessTree: true)` is called.
 
 ### `IBrowserContext.CloseAsync`
 
@@ -204,12 +207,25 @@ The sequence:
 
 `DisposeAsync` is the non-graceful teardown path, used when an exception occurs during launch or when the pool discards a disconnected browser:
 
-1. Signal handlers are unregistered.
-2. `IsConnected` is set to `false`.
-3. The transport is disposed asynchronously.
-4. If the process has not exited, `process.Kill(entireProcessTree: true)` is called immediately, without the 5-second grace period.
-5. The process handle is disposed.
-6. If a temp user data directory is owned, `Directory.Delete(path, recursive: true)` is attempted. Failures are silently ignored (best-effort cleanup).
+1. The `BrowserHeartbeat` (if running) is disposed.
+2. Signal handlers and the `Process.Exited` handler are unregistered.
+3. `IsConnected` is set to `false`.
+4. The transport is disposed asynchronously.
+5. If the process has not exited, `process.Kill(entireProcessTree: true)` is called immediately, without the 5-second grace period.
+6. The process handle is disposed.
+7. If a temp user data directory is owned, `Directory.Delete(path, recursive: true)` is attempted. Failures are silently ignored (best-effort cleanup).
+
+### Health detection
+
+When a browser is launched (not connected via `ConnectAsync`), Motus monitors the browser process for two failure modes: crashes and freezes.
+
+**Crash detection via `Process.Exited`.** The `Browser` constructor subscribes to `_process.Exited`. When Chrome crashes or is killed externally, the handler fires immediately, sets `IsConnected = false`, disposes the transport (which faults all pending CDP commands with `CdpDisconnectedException`), and raises the `Disconnected` event. This is faster than waiting for the WebSocket receive loop to detect the broken connection.
+
+**Freeze detection via `BrowserHeartbeat`.** After `InitializeAsync` completes, a background `BrowserHeartbeat` is started for launched browsers. The heartbeat sends `Browser.getVersion` every 5 seconds with a 10-second timeout. If the ping times out or fails (and the browser has not been intentionally shut down), the `OnHeartbeatFailed` callback triggers the same disconnect path as `Process.Exited`. This catches cases where Chrome becomes unresponsive without closing the WebSocket, such as GPU process hangs or runaway JavaScript.
+
+Both handlers are guarded by an `Interlocked.CompareExchange` on `_disconnectedFlag` so that only one path fires the `Disconnected` event, regardless of which detection mechanism triggers first.
+
+**`IBrowser.IsHealthy`.** The `IsHealthy` property (defined as a default interface member on `IBrowser`) returns `true` when the browser is connected. The `Browser` implementation overrides this with a process-aware check: `_isConnected && (_process is null || !_process.HasExited)`. For browsers obtained via `ConnectAsync` (no process ownership), `IsHealthy` is equivalent to `IsConnected`.
 
 ### Signal handlers
 
@@ -268,6 +284,8 @@ IPage page = await lease.Browser.NewPageAsync();
 
 The returned `IBrowserLease` holds the browser and a return callback. Disposing the lease returns the browser to the idle channel if it is still connected and the pool has not been disposed. A disconnected or post-dispose browser is discarded and the semaphore slot is released.
 
+**Proactive replenishment.** The pool subscribes to each browser's `Disconnected` event. When a browser crashes or becomes unresponsive, `OnBrowserDisconnected` disposes the dead browser, releases its capacity semaphore slot, and (if the idle count has dropped below `MinInstances`) launches a replacement in the background. A `ConcurrentDictionary<IBrowser, byte>` deduplicates the disconnect and lease-return paths to prevent double-dispose when both fire for the same browser.
+
 `IBrowserPool.ActiveCount` and `IdleCount` expose live counters for observability.
 
 `DisposeAsync` on the pool drains and disposes all idle browsers. Browsers that are currently leased out are not forcibly recalled; callers must dispose their leases before the pool can be fully cleaned up.

docs/extensions/plugin-interfaces.md

@@ -1,6 +1,6 @@
 # Plugin Interfaces
 
-Motus exposes seven extensibility interfaces that plugins can implement to participate in browser automation, test reporting, and accessibility auditing. All interfaces live in the `Motus.Abstractions` NuGet package. Plugins register their implementations through `IPluginContext` during initialization.
+Motus exposes eight extensibility interfaces that plugins can implement to participate in browser automation, test reporting, accessibility auditing, and performance monitoring. All interfaces live in the `Motus.Abstractions` NuGet package. Plugins register their implementations through `IPluginContext` during initialization.
 
 ---
 
@@ -271,6 +271,55 @@ public sealed class A11yReporter : IReporter, IAccessibilityReporter
 
 ---
 
+## IPerformanceReporter
+
+`IPerformanceReporter` is an opt-in companion to `IReporter` for reporters that want to receive performance metrics collected during test execution. Motus checks `reporter is IPerformanceReporter` at runtime on each registered reporter; only those that implement both interfaces receive performance callbacks. This follows the same NativeAOT-safe pattern as `IAccessibilityReporter`.
+
+### Members
+
+| Member | Return Type | Description |
+|---|---|---|
+| `OnPerformanceMetricsCollectedAsync(PerformanceMetrics metrics, PerformanceBudgetResult? budgetResult, TestInfo test)` | `Task` | Called when performance metrics have been collected for a test. |
+
+### Supporting Types
+
+`PerformanceMetrics` carries the collected values: `Lcp`, `Fcp`, `Ttfb`, `Cls`, `Inp` (all `double?`), `JsHeapSize` (`long?`), `DomNodeCount` (`int?`), `LayoutShifts` (`IReadOnlyList<LayoutShiftEntry>`), `CollectedAtUtc` (`DateTime`), and `DiagnosticMessage` (`string?`).
+
+`PerformanceBudgetResult` carries the evaluation: `Entries` (`IReadOnlyList<PerformanceBudgetEntry>`) and `Passed` (`bool`). Each `PerformanceBudgetEntry` has `MetricName`, `Threshold`, `ActualValue`, `Passed`, and `Delta`.
+
+`budgetResult` is `null` when no budget is configured.
+
+### Lifecycle Notes
+
+`OnPerformanceMetricsCollectedAsync` is called once per test when metrics have been collected (typically after a navigation). It is called before `OnTestEndAsync` for the same test. Exceptions are caught and logged; they do not suppress remaining reporter events.
+
+### Example
+
+```csharp
+using Motus.Abstractions;
+
+public sealed class PerfReporter : IReporter, IPerformanceReporter
+{
+    public Task OnTestRunStartAsync(TestSuiteInfo suite) => Task.CompletedTask;
+    public Task OnTestStartAsync(TestInfo test) => Task.CompletedTask;
+    public Task OnTestEndAsync(TestInfo test, TestResult result) => Task.CompletedTask;
+    public Task OnTestRunEndAsync(TestRunSummary summary) => Task.CompletedTask;
+
+    public Task OnPerformanceMetricsCollectedAsync(
+        PerformanceMetrics metrics,
+        PerformanceBudgetResult? budgetResult,
+        TestInfo test)
+    {
+        Console.WriteLine(
+            $"[{test.TestName}] LCP={metrics.Lcp:F0}ms " +
+            $"Budget: {(budgetResult?.Passed == true ? "PASS" : budgetResult?.Passed == false ? "FAIL" : "none")}");
+        return Task.CompletedTask;
+    }
+}
+```
+
+---
+
 ## IAccessibilityRule
 
 `IAccessibilityRule` evaluates a single WCAG rule against one node in the accessibility tree. The engine walks every non-ignored node in the tree and calls each registered rule's `Evaluate` method. Rules are synchronous to keep the audit loop efficient; use the `AccessibilityAuditContext` for any cross-node data rather than performing additional async page queries.
@@ -384,7 +433,7 @@ public sealed class MyPlugin : IMotusPlugin
 | `RegisterSelectorStrategy(ISelectorStrategy strategy)` | `void` | Registers a custom selector strategy. |
 | `RegisterWaitCondition(IWaitCondition condition)` | `void` | Registers a custom wait condition. |
 | `RegisterLifecycleHook(ILifecycleHook hook)` | `void` | Registers a lifecycle hook. |
-| `RegisterReporter(IReporter reporter)` | `void` | Registers a test reporter. Reporters that also implement `IAccessibilityReporter` automatically receive violation events. |
+| `RegisterReporter(IReporter reporter)` | `void` | Registers a test reporter. Reporters that also implement `IAccessibilityReporter` or `IPerformanceReporter` automatically receive the corresponding events. |
 | `RegisterAccessibilityRule(IAccessibilityRule rule)` | `void` | Registers a custom accessibility rule that is invoked during accessibility audits. |
 | `CreateLogger(string categoryName)` | `IMotusLogger` | Creates a logger scoped to the given category name. |
 

docs/guides/configuration.md

@@ -66,6 +66,17 @@ When Motus initializes, it walks up from `Environment.CurrentDirectory`, checkin
     "auditAfterActions": false,
     "includeWarnings": true,
     "skipRules": []
+  },
+  "performance": {
+    "enable": false,
+    "collectAfterNavigation": true,
+    "lcp": null,
+    "fcp": null,
+    "ttfb": null,
+    "cls": null,
+    "inp": null,
+    "jsHeapSize": null,
+    "domNodeCount": null
   }
 }
 ```
@@ -154,6 +165,22 @@ Controls the built-in accessibility audit hook. When enabled, Motus runs axe-sty
 | `includeWarnings` | `bool` | `true` | Treat warning-severity findings as failures alongside errors (when mode is `Enforce`). |
 | `skipRules` | `string[]` | `null` | Rule IDs to exclude from every audit, e.g. `["a11y-color-contrast"]`. |
 
+### `performance` Section
+
+Controls the built-in performance metrics collector and budget thresholds. When enabled, Motus collects Core Web Vitals and supplementary metrics during test execution. Setting metric thresholds activates budget enforcement.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `enable` | `bool` | `false` | Enable the performance metrics collector. |
+| `collectAfterNavigation` | `bool` | `true` | Collect metrics after each page navigation. |
+| `lcp` | `number` | `null` | Maximum Largest Contentful Paint in milliseconds. |
+| `fcp` | `number` | `null` | Maximum First Contentful Paint in milliseconds. |
+| `ttfb` | `number` | `null` | Maximum Time to First Byte in milliseconds. |
+| `cls` | `number` | `null` | Maximum Cumulative Layout Shift score (unitless). |
+| `inp` | `number` | `null` | Maximum Interaction to Next Paint in milliseconds. |
+| `jsHeapSize` | `number` | `null` | Maximum JavaScript heap size in bytes. |
+| `domNodeCount` | `number` | `null` | Maximum DOM node count. |
+
 ---
 
 ## Environment Variables
@@ -179,8 +206,16 @@ Boolean variables accept `true`, `false`, `1`, or `0` (case-insensitive). Intege
 | `MOTUS_FAILURES_TRACE_PATH` | `failure.tracePath` | `string` | Directory for trace archives. |
 | `MOTUS_ACCESSIBILITY_ENABLE` | `accessibility.enable` | `bool` | Enable the accessibility audit hook. |
 | `MOTUS_ACCESSIBILITY_MODE` | `accessibility.mode` | `string` | Audit violation handling mode (`Off`, `Warn`, `Enforce`). |
+| `MOTUS_PERFORMANCE_ENABLE` | `performance.enable` | `bool` | Enable the performance metrics collector. |
+| `MOTUS_PERFORMANCE_LCP` | `performance.lcp` | `double` | Maximum LCP in milliseconds. |
+| `MOTUS_PERFORMANCE_FCP` | `performance.fcp` | `double` | Maximum FCP in milliseconds. |
+| `MOTUS_PERFORMANCE_TTFB` | `performance.ttfb` | `double` | Maximum TTFB in milliseconds. |
+| `MOTUS_PERFORMANCE_CLS` | `performance.cls` | `double` | Maximum CLS score. |
+| `MOTUS_PERFORMANCE_INP` | `performance.inp` | `double` | Maximum INP in milliseconds. |
+| `MOTUS_PERFORMANCE_JS_HEAP_SIZE` | `performance.jsHeapSize` | `long` | Maximum JS heap size in bytes. |
+| `MOTUS_PERFORMANCE_DOM_NODE_COUNT` | `performance.domNodeCount` | `int` | Maximum DOM node count. |
 
-> Not all config file sections have environment variable coverage. `reporter`, `recorder`, and the locator `selectorPriority` arrays are file-only settings. Use the config file for those.
+> Not all config file sections have environment variable coverage. `reporter`, `recorder`, the locator `selectorPriority` arrays, and `performance.collectAfterNavigation` are file-only settings. Use the config file for those.
 
 ---
 
@@ -215,6 +250,7 @@ The merge checks are per-property:
 - `IgnoreHTTPSErrors` -- a config value of `true` is applied when `options.IgnoreHTTPSErrors` is `false`. A config value of `false` never overrides a caller-set `true`.
 - `Viewport` -- applied only when `options.Viewport is null`. Both `width` and `height` must be non-null in the config for a viewport to be applied.
 - `Accessibility` -- the entire `AccessibilityOptions` object is applied only when `options.Accessibility is null`.
+- `Performance` -- the entire `PerformanceOptions` object is applied only when `options.Performance is null`.
 
 ---
 
@@ -237,6 +273,7 @@ The merge checks are per-property:
 | `DownloadsPath` | `string?` | `null` | Directory for browser-initiated file downloads. |
 | `Plugins` | `IReadOnlyList<IPlugin>?` | `null` | Plugin instances loaded into every browser context created from this launch. |
 | `Accessibility` | `AccessibilityOptions?` | `null` | Accessibility audit hook configuration. Disabled when `null`. |
+| `Performance` | `PerformanceOptions?` | `null` | Performance metrics collector configuration. Disabled when `null`. |
 
 ### AccessibilityOptions
 
@@ -251,6 +288,17 @@ Nested under `LaunchOptions.Accessibility`. A `null` value disables the hook ent
 | `IncludeWarnings` | `bool` | `true` | Count warning-severity findings as failures when mode is `Enforce`. |
 | `SkipRules` | `IReadOnlyList<string>?` | `null` | Rule IDs excluded from every audit. |
 
+### PerformanceOptions
+
+Nested under `LaunchOptions.Performance`. A `null` value disables the collector entirely.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `Enable` | `bool` | `false` | Enable the performance metrics collector. |
+| `CollectAfterNavigation` | `bool` | `true` | Collect metrics after each page navigation. |
+
+Budget thresholds are not part of `PerformanceOptions`. They are configured via the `[PerformanceBudget]` attribute or the `performance` section in `motus.config.json`.
+
 ---
 
 ## ContextOptions
@@ -292,6 +340,9 @@ export MOTUS_FAILURES_TRACE=true
 export MOTUS_FAILURES_TRACE_PATH=test-results/traces
 export MOTUS_ACCESSIBILITY_ENABLE=true
 export MOTUS_ACCESSIBILITY_MODE=Enforce
+export MOTUS_PERFORMANCE_ENABLE=true
+export MOTUS_PERFORMANCE_LCP=2500
+export MOTUS_PERFORMANCE_CLS=0.1
 ```
 
 No `motus.config.json` is required on the CI agent. These variables provide a complete runtime configuration without touching source control.
@@ -335,4 +386,5 @@ Commit this file or add it to `.gitignore` depending on whether the whole team u
 - [Getting Started](../getting-started.md)
 - [Plugins and Extensibility](../extensions/getting-started.md)
 - [Accessibility Testing](./accessibility-testing.md)
+- [Performance Testing](./performance-testing.md)
 - [Testing Frameworks](./testing-frameworks.md)