@faultsense/agent

---

Faultsense is a lightweight, zero-dependency browser agent. It evaluates end-to-end assertions against real user sessions in production. You write the assertions as annotations on the UI they check, and Faultsense decides pass or fail in a real browser on the user's own device.

It's the expect() without the page: the assertion lives next to the markup it checks and runs wherever your app runs.

<button
  fs-assert="checkout/submit-order"
  fs-trigger="click"
  fs-assert-added-success=".order-confirmation"
  fs-assert-added-error=".error-message[text-matches=try again]">
  Place Order
</button>

When a user clicks Place Order: if the order confirmation appears, the success condition passes. If an error message appears instead, the error condition passes. If neither happens before the timeout, Faultsense reports a failure and tells you which assertion broke, on which release, and what should have happened instead.

You don't need a second codebase to test the first one. Your assertions stop being trapped in a script suite that only runs in CI, against a simulated browser, on a network that never drops. They move onto the UI itself and run in the field.

Contents

• Why Faultsense
• How it works
• Quick start
• Instrumentation reference
• JSON-spec instrumentation
• Framework usage
• Works with
• Conformance
• Configuration
• JavaScript API
• Event payload — bring your own sink
• Performance
• Worked examples
• Package info
• License & links

Why Faultsense

The end-to-end test is splitting in two. AI is taking over the driving half: clicking through flows and filling in forms. What's left is the half that was always the point, the assertion half, where you say what "correct" actually means. That's Faultsense.

You already do this when you write a Playwright or Cypress test. Faultsense lets you lift those checks out of the script and onto the element itself, then run them against real user sessions instead of seeded fixtures in CI. It's the same reasoning you already use, minus the fixtures.

How it works

1. Annotate — add fs-* attributes to the flows that matter, right on the elements they check.
2. Drive — an AI agent walks your flows in staging. Your real users walk them in production.
3. Assert — Faultsense evaluates every annotation as the flow runs and records pass or fail. The UI is the signal, so there's no server-side integration to wire up.
4. Report — results stream to the stack you already run: your warehouse, your metrics pipeline, wherever you point them.

Every assertion needs three things:

1. A key — fs-assert="checkout/submit-order" identifies this assertion (stable across releases).
2. A trigger — fs-trigger="click" defines when the assertion activates.
3. An expected outcome — fs-assert-added=".success" defines what should happen.

Quick start

You init the agent with a collector function: a plain callback that receives every resolved assertion, so you decide where it goes. Send it to your warehouse, an internal endpoint, or three sinks at once. There's no API key to manage and no backend you're forced to run.

Via CDN — load the bundle, then init:

<script defer src="https://cdn.faultsense.com/v0.6.0/faultsense-agent.min.js"></script>
<script>
  window.addEventListener('DOMContentLoaded', () => {
    Faultsense.init({
      releaseLabel: '2.4.1',
      collectorURL: (result) => {
        // send it anywhere — this is your sink
        navigator.sendBeacon('/faultsense', JSON.stringify(result));
      },
    });
  });
</script>

/v0.6.0/ is served immutable (Cache-Control: public, max-age=31536000, immutable). Use /v0/ to float to the latest 0.x in development.

Via npm — the same init call:

npm install @faultsense/agent

import { init } from '@faultsense/agent';

const cleanup = init({
  releaseLabel: '2.4.1',
  collectorURL: (result) => {
    // send it anywhere — this is your sink
    navigator.sendBeacon('/faultsense', JSON.stringify(result));
  },
});
// call cleanup() on unmount / HMR dispose

The default entry is side-effect-free and SSR-safe: importing it never touches window or document. collectorURL also accepts a URL string (with apiKey) or one of the built-in 'console' / 'panel' collectors. See Event payload.

Instrumentation reference

The fs-* attributes work in any framework that renders to the DOM. An instrumented element carries an assertion key, a trigger, and one or more expectations.

Triggers

Exactly one fs-trigger per element defines when the assertion activates.

Trigger	When it fires
click	Element is clicked
dblclick	Element is double-clicked
change	Input value changes
input	Input receives input
blur / focus	Element loses / gains focus
hover	Pointer enters the element
keydown / keydown:<key>	Key press (optionally a specific key)
submit	Form is submitted
mount	Element is added to the DOM
unmount	Element is removed from the DOM
load / error	Media resource loads or fails
online / offline	Connectivity changes
invariant	Continuous monitoring — reports violations and recoveries only
event:<name>	A CustomEvent fires on document

Attributes go on the interacted element; clicks on descendants resolve up via closest(). For forms, put submit on the <form> or click on the submit button.

Assertion types

The value is a CSS selector, optionally followed by inline modifiers in brackets.

Attribute	Resolves when
fs-assert-added="<selector>"	A matching element appears in the DOM
fs-assert-removed="<selector>"	A matching element is removed from the DOM
fs-assert-updated="<selector>"	A matched element or subtree is mutated
fs-assert-visible="<selector>"	Element exists and has layout dimensions
fs-assert-hidden="<selector>"	Element exists but has no layout dimensions
fs-assert-loaded="<selector>"	A media element (img/video/iframe) finishes loading
fs-assert-stable="<selector>"	Element is not mutated during the timeout window
fs-assert-emitted="<event>"	A matching CustomEvent fires on document
fs-assert-after="<key>"	The referenced parent assertion(s) have already passed

added vs. updated is the #1 gotcha. added/removed/updated resolve only from mutation records; a pre-existing match doesn't count as a pass. Use added when the element doesn't exist yet; use updated when it exists and its content changes (a class toggle is updated). visible/hidden are point-in-time layout checks and pass immediately if already satisfied.

Conditional assertions

Handle multiple outcomes from a single action with condition keys:

<button fs-assert="auth/login" fs-trigger="click"
  fs-assert-added-success=".dashboard"
  fs-assert-added-error=".error-msg">
  Login
</button>

The first matching condition wins and the rest are dismissed (never sent). The UI is the signal, so nothing changes server-side. For cross-type conditionals (e.g. removed-success + added-error), group them with fs-assert-mutex="each".

Inline modifiers

Chained onto the selector with CSS-like bracket syntax:

fs-assert-updated='#count[text-matches=\d+]'
fs-assert-updated='#logo[src=/img/new.png][alt=New Logo]'
fs-assert-updated='.panel[classlist=active:true,hidden:false]'
fs-assert-added='.success[text-matches=Order #\d+]'

Modifier	Checks
[text-matches=pattern]	Text content — regex, partial match
[value-matches=pattern]	Form control .value — regex, partial match
[checked=true|false]	Checkbox / radio checked state
[disabled=true|false]	Disabled state
[focused=true|false] / [focused-within=…]	Focus state
[count=N] / [count-min=N] / [count-max=N]	Element count
[classlist=class:true,class:false]	Class presence
[detail-matches=key:pattern]	CustomEvent.detail field (with emitted)
[attr=value]	Any other bracket key is an attribute check — full match

Anchoring rule: text-matches / value-matches are partial (unanchored; use ^exact$ to pin them). Attribute checks are full match (auto-anchored). Omit the selector and provide only modifiers to check the triggering element itself: fs-assert-updated="[text-matches=\d+ remaining]".

Assertion keys

Use / to group related assertions hierarchically. Keys must be stable across releases. Human-readable labels live on the collector side, not here.

fs-assert="checkout/add-to-cart"
fs-assert="checkout/submit-order"
fs-assert="profile/media/upload-photo"

Element-level attributes

Attribute	Purpose
fs-assert-timeout="<ms>"	SLA timeout — fail if not resolved in time
fs-assert-mpa="true"	Persist across full page navigation (MPA)
fs-assert-mutex="<mode>"	Group conditionals across types (type / each / conditions)
fs-assert-oob="<keys>"	Fire a side-effect check when a parent assertion passes
fs-assert-oob-fail="<keys>"	Fire a side-effect check when a parent assertion fails

JSON-spec instrumentation

Sometimes you can't edit the HTML: a third-party widget, generated markup, a SaaS template you don't control. Or a tool is generating the instrumentation for you, like a recorder or an importer. For those cases, declare the same assertions as a JSON spec. Both paths run through the same pipeline and behave identically; the only difference is where the fs-* pairs live. HTML and JSON can coexist on the same page.

Each entry mirrors the fs-* attribute names and adds one JSON-only key, fs-target: the CSS selector the trigger binds to. (In HTML that target is implicitly the element itself.)

import { init } from '@faultsense/agent';

init({
  releaseLabel: '2.4.1',
  collectorURL: (result) => navigator.sendBeacon('/faultsense', JSON.stringify(result)),
  spec: [
    {
      'fs-target': '#submit-btn',        // JSON-only: required CSS selector
      'fs-trigger': 'click',
      'fs-assert': 'checkout/submit-order',
      'fs-assert-added': '.confirmation[text-matches=Order #\\d+]',
    },
  ],
});

Every trigger, assertion type, and modifier documented above applies verbatim. Three keys are required per entry: fs-target, a trigger (fs-trigger, or fs-assert-oob / fs-assert-oob-fail for OOB children), and fs-assert.

• fs-target is re-resolved on every event, so elements added after init (SPAs, late-rendered content) get picked up on their own; you never re-register them.
• Escape backslashes. JSON string rules apply: a regex modifier is "fs-assert-updated": "#counter[text-matches=\\d+]" (double backslash). A single backslash silently compiles to the wrong regex. Emit specs with JSON.stringify.
• Validate against the schema. The published spec.schema.json (also at https://faultsense.com/spec.schema.json) is the only place typos in fs-* keys surface loudly; the agent itself ignores unknown keys, same as on the HTML side.

Update the spec at runtime, or run purely from JSON:

Faultsense.setSpec(entries);        // replace the active spec (installs/tears down as needed)
Faultsense.addSpec(entries);        // append — never removes
const entries = Faultsense.getSpec(); // frozen snapshot

// Drive an existing HTML-instrumented page entirely from JSON without stripping attributes:
init({ /* … */, ignoreHtmlAttrs: true, spec: [/* … */] });

See docs/public/agent/json-spec.md for the full authoring guide, including selector-stability tips and the HTMLJSON co-existence rules.

Framework usage

Faultsense observes the DOM, not framework internals, so fs-* attributes work anywhere that renders HTML.

React (JSX)

<button onClick={handleAdd}
  fs-assert="cart/add-item" fs-trigger="click"
  fs-assert-updated="#cart-count">
  Add to Cart
</button>

Vue (SFC)

<template>
  <button @click="handleAdd"
    fs-assert="cart/add-item" fs-trigger="click"
    fs-assert-updated="#cart-count">
    Add to Cart
  </button>
</template>

Svelte

<button on:click={handleAdd}
  fs-assert="cart/add-item" fs-trigger="click"
  fs-assert-updated="#cart-count">
  Add to Cart
</button>

Framework traps: React drops bare boolean attributes, so always use explicit string values (fs-assert-mutex="each", not fs-assert-mutex). Custom components must forward fs-* props to the root DOM element. Server-swap frameworks force the added vs. updated choice: morphdom-style patching preserves element identity (use updated); outerHTML replacement creates a new node (use added).

Works with

Faultsense is framework-agnostic. The matrix below is verified end-to-end against real framework dev servers via Playwright on every release.

Framework	Runtime	Coverage
React 19 + Vite	conformance/react/	10/10 scenarios
Vue 3 + Vite	conformance/vue3/	10/10 scenarios
Svelte 5 (runes) + Vite	conformance/svelte/	10/10 scenarios
Solid 1.9 + Vite	conformance/solid/	10/10 scenarios
Alpine.js 3	conformance/alpine/	10/10 scenarios
Astro 6 (SSR + React island)	conformance/astro/	11/11 scenarios
Hotwire (Rails 8 + Turbo 8)	conformance/hotwire/ (Docker)	8/8 scenarios
HTMX 2 + Express	conformance/htmx/	7/7 scenarios
Livewire 3 (Laravel 11)	conformance/livewire/ (Docker)	8/8 scenarios
Phoenix LiveView 1.0	conformance/liveview/ (Docker)	8/8 scenarios

Docker is required only for the Hotwire, Livewire, and LiveView harnesses (each boots its own Rails / Laravel / Phoenix runtime in a container). The other seven run directly in Node. See conformance/README.md for setup.

Conformance

Support is enforced through two layers:

• Layer 1 — DOM mutation-pattern suite. An exhaustive jsdom suite (tests/conformance/) that locks in every raw DOM mutation shape the agent handles. This is the source of truth: any framework that produces a locked-in shape is supported by transitivity.
• Layer 2 — Per-framework harnesses. Minimal real apps under conformance/ run in real browsers as empirical confirmation, and feed newly-discovered patterns back into Layer 1.

The mutation-pattern catalog:

ID	Pattern	Status	Seen in
PAT-01	Pre-existing target	supported	SSR React/Vue, Turbo/HTMX server lists
PAT-02	Delayed-commit mutation	supported	HTMX mid-swap classes, React Suspense, transitions
PAT-03	outerHTML replacement	supported	HTMX hx-swap="outerHTML", Turbo Stream replace
PAT-04	morphdom preserved-identity	supported	Livewire, Turbo 8 morphing, Alpine x-html.morph
PAT-05	Detach-reattach	supported	React keyed reorder / StrictMode, Vue Teleport
PAT-06	Text-only mutation	supported	Solid, Svelte, Vue 3 reactive text, Lit
PAT-07	Microtask batching	supported	React 18 auto-batching, Vue nextTick, Preact signals
PAT-08	Cascading mutations	supported	Redux/Zustand, Turbo Stream broadcasts, hx-swap-oob
PAT-09	Hydration upgrade	supported	Next.js App Router, Remix, Astro, SvelteKit, Nuxt
PAT-10	Shadow-DOM traversal	gap	Lit, Stencil, Salesforce LWC

Known limitation — Shadow DOM (PAT-10). The MutationObserver is rooted at document.body and does not cross shadow-root boundaries, so mutations inside shadow trees are invisible to the agent today. Tracked as a future feature.

Configuration

Passed to Faultsense.init(config) (or as data-* attributes on the script tag).

Option	Type	Required	Default	Description
releaseLabel	string	Yes	—	App version or commit hash
collectorURL	string | function | 'console' | 'panel'	Yes	—	Where results go — see below
apiKey	string	If URL	—	API key (required when collectorURL is a URL)
debug	boolean	No	false	Enable console logging
userContext	Record<string, any>	No	—	Arbitrary context attached to every payload (e.g. userId, plan tier)
userCohorts	Record<string, string>	No	—	Low-cardinality cohort dimensions for per-cohort assertion health
gcInterval	number (ms)	No	5000	Background sweep interval for stale assertions
unloadGracePeriod	number (ms)	No	2000	On page unload, assertions older than this fail; fresher ones are dropped
spec	SpecEntry[]	No	—	JSON-spec instrumentation — peer of fs-* attributes
ignoreHtmlAttrs	boolean	No	false	Ignore all fs-* HTML attributes and run purely from spec

Assertions have no default per-assertion timer; they resolve naturally when the DOM changes. Add a per-element SLA with fs-assert-timeout when you want one.

Script-tag data-* attributes map one-to-one: data-release-label, data-collector-url, data-api-key, data-debug, data-gc-interval, data-unload-grace-period, data-user-context (JSON), data-user-cohorts (JSON).

CSP: script-src 'self' https://cdn.faultsense.com; and connect-src 'self' https://collector.example.com;. No inline scripts, no eval.

JavaScript API

Method	Description
Faultsense.init(config)	Initialize the agent. Returns a cleanup function.
Faultsense.cleanup()	Tear down the agent — remove all listeners and observers.
Faultsense.registerCleanupHook(fn)	Register a function to run during cleanup.
Faultsense.setUserContext(context)	Replace the current user context (does not merge).
Faultsense.setUserCohorts(cohorts)	Replace the current user cohorts (low-cardinality strings).
Faultsense.setSpec(entries)	Replace the active JSON spec.
Faultsense.addSpec(entries)	Append entries to the active JSON spec (never removes).
Faultsense.getSpec()	Return a frozen snapshot of the active JSON spec.
Faultsense.version	The agent's semver string.

// At init
Faultsense.init({
  releaseLabel: '2.4.1',
  collectorURL: (result) => navigator.sendBeacon('/faultsense', JSON.stringify(result)),
  userContext: { plan: 'pro' },
  userCohorts: { plan: 'pro', region: 'us-east' },
});

// After login — pass the complete context each time (no merge)
Faultsense.setUserContext({ userId: 'u_123', plan: 'pro' });
Faultsense.setUserCohorts({ plan: 'pro', region: 'us-east' });

Event payload — bring your own sink

Faultsense sends results wherever you point collectorURL. It never mandates a backend; bring your own sink. collectorURL accepts four shapes:

1. A URL string — one POST per resolved assertion via navigator.sendBeacon (with a fetch fallback), Content-Type: application/json, fire-and-forget. Requires apiKey. This is the contract below.
2. A function (payload) => void — an in-process sink (proxy, queue, logger, tests). No apiKey needed; one call per event.
3. 'console' — logs each payload with console.log (via @faultsense/console-collector).
4. 'panel' — renders results in a Shadow-DOM overlay (via @faultsense/panel-collector), handy in staging.

Only passed and failed are sent (internal dismissed results are dropped), and only on a status change. Each event has this shape:

interface EventPayload {
  api_key: string;
  assertion_key: string;
  assertion_trigger: string;
  assertion_type:
    | "added" | "removed" | "updated" | "visible"
    | "hidden" | "loaded" | "stable" | "emitted" | "after";
  assertion_type_value: string;
  assertion_type_modifiers: Record<string, string>;
  attempts: number[];          // re-trigger timestamps (rage-click signal)
  condition_key: string;
  element_snapshot: string;    // outerHTML of the instrumented element
  release_label: string;
  status: "passed" | "failed";
  timestamp: string;           // trigger (creation) time, ISO 8601
  user_context?: Record<string, any>;
  user_cohorts?: Record<string, string>;
  agent_version: string;
  error_context?: {            // first uncaught error during the session, if any
    message: string;
    stack?: string;
    source?: string;
    lineno?: number;
    colno?: number;
  };
}

Example body:

{
  "api_key": "your-api-key",
  "assertion_key": "checkout/submit-order",
  "assertion_trigger": "click",
  "assertion_type": "added",
  "assertion_type_value": ".success-message",
  "assertion_type_modifiers": { "text-matches": "Order confirmed" },
  "attempts": [],
  "condition_key": "success",
  "element_snapshot": "<button fs-assert=\"checkout/submit-order\" …>Submit</button>",
  "release_label": "2.4.1",
  "status": "passed",
  "timestamp": "2026-03-24T14:30:00.000Z",
  "user_context": { "userId": "u_123", "plan": "pro" },
  "user_cohorts": { "plan": "pro", "region": "us-east" },
  "agent_version": "0.6.0"
}

A cross-origin URL sink must answer CORS preflight with Access-Control-Allow-Origin, Access-Control-Allow-Headers: Content-Type, and Access-Control-Allow-Methods: POST, OPTIONS. Keep user_cohorts low-cardinality; they're for dimensions like plan tier or region, not user IDs.

Performance

Faultsense is built to stay off the critical path. The numbers below come from a React 19 stress harness running 50–1000 assertions with background DOM churn and CPU throttling, measured with paired A/B runs (Wilcoxon signed-rank test, Hodges–Lehmann 95% CI) on an Apple M4 Pro.

Metric	Result
INP impact	0 ms across every configuration, including 1000 assertions under 4× CPU throttle
New long tasks	Zero — the agent never creates one in steady state
Idle heap footprint	+1.7 KB (measurable; 95% CI [+1.5, +1.7 KB])
Heap @ 1000 assertions	~140 KB — sub-linear scaling (20× the assertions → ~1.8× the heap)
MutationObserver callback P99 (worst case)	2.2 ms at 1000 assertions under 4× CPU — 4% of the 50 ms long-task threshold
LCP impact (<200 assertions)	Undetectable (deltas fall within noise)
Bundle	17.7 KB gzipped, zero dependencies

Demo benchmark (HTMX todolist, 30 pairs, 60 s soak):

Scenario	LCP Δ	INP Δ	Heap Δ	Long tasks
Unthrottled, idle	−4 ms	n/a	+1.7 KB	0
Slow 4G, idle	−4 ms	n/a	+1.7 KB	0
Unthrottled, active	−4 ms (noise)	+0 ms	−6.9 KB (noise)	0

A typical instrumented page carries 10–50 assertions; 1000 is a deliberate stress case. The numbers above were measured on agent v0.4.0 (Chromium-only; INP is a lab estimate in headless Chromium). Reproduce them yourself:

npm run benchmark:stress   # scaling curve across assertion counts
npm run benchmark:demo     # against examples/todolist-htmx

See tools/benchmark/README.md for full methodology and caveats.

Worked examples

The examples/ directory contains reference ports you can run locally. Both use the same assertion keys, so you can diff them side-by-side and see how the instrumentation pattern maps across rendering paradigms.

• todolist-tanstack — React + TanStack Router + TanStack Start (virtual DOM, JSX interpolation for dynamic assertion values).
• todolist-htmx — HTMX 2 + Express + EJS (server-rendered fragments, hx-boost SPA nav, server-side interpolation).

Package info

• Dependencies: none
• Bundle: 17.7 KB gzipped, single file
• Browser support: modern browsers (ES2020+)
• Framework: anything that renders HTML
• License: FSL-1.1-ALv2

License & links

Licensed under FSL-1.1-ALv2, the Functional Source License. It converts to Apache 2.0 two years after each release.

• Issues
• Discussions