Faultsense agent reference

Faultsense is a zero-dependency browser agent that validates feature correctness in production through declarative HTML attribute assertions. Think of it as E2E test assertions built into your HTML, running against every real user session. Everything an AI coding agent or a human engineer needs to instrument a web app and consume the results lives here.

Start here

• Installation — drop the script tag, call Faultsense.init(), set up CSP
• Configuration — every init option with type, default, and example
• Patterns cookbook — annotated recipes for common UI scenarios
• Instrumentation skill for your AI coding agent — install the Faultsense skill into Claude Code, Cursor, OpenCode, Goose, or any agentskills.io-compatible tool so it authors fs-* attributes correctly

The fs-* attribute API

Every instrumented element needs three things: an assertion key (fs-assert), a trigger (fs-trigger), and at least one expectation (fs-assert-<type>). The reference splits those axes into three browsable groups.

• Triggers — what starts an assertion (click, submit, mount, invariant, event:<name>, …)
• Assertions — what passing looks like (added, updated, visible, emitted, after, …) plus feature pages for conditional assertions, mutex, OOB, MPA, timeout
• Modifiers — inline refinements (text-matches, count, classlist, attribute checks, …)

A single instrumented element combines all three:

<button
  fs-assert="checkout/submit-order"
  fs-trigger="click"
  fs-assert-added=".confirmation[text-matches=Order #\d+]">
  Place Order
</button>

• fs-assert — the hierarchical key (/-separated) that identifies this assertion across releases
• fs-trigger — the user action that starts the assertion (click)
• fs-assert-added — the assertion type and its target selector (added)
• [text-matches=Order #\d+] — the inline modifier that refines what "passing" means (text-matches)

Authoring without editing HTML

If you can't (or don't want to) edit production HTML, the same instrumentation can be authored as a JSON spec passed to Faultsense.init({ spec: [...] }) or installed at runtime via Faultsense.setSpec(entries). The two paths coexist on the same page and produce identical assertions — same keys, same behaviour, same pipeline. See JSON-spec instrumentation for the full reference.

Framework integration

Framework-specific notes for JSX binding, dynamic attribute values, and framework-native gotchas:

• React · Vue · Svelte · Solid · Alpine
• HTMX · Hotwire · Livewire · LiveView · Astro