`Installation`

Get started with Fault Sense in seconds

Fault Sense can be installed in two ways: automatic setup with a single script tag, or manual setup with more control over initialization. Both methods are production-ready and work identically once configured.

The automatic setup is perfect for getting started quickly, while the manual setup gives you more control over configuration options like the collector URL or function.

Automatic Setup

The fastest way to get started. Add a single script tag to your HTML and Fault Sense will automatically initialize with data-* options you provide. See the configuration section below for all of the configuration options.

<script
  defer
  id="fs-agent"
  src="https://unpkg.com/faultsense@latest/dist/faultsense-agent.min.js"
  data-release-label="0.0.0"
  data-collector-url="console"
  data-debug="true"
></script>

Manual Setup

For more control over initialization, you can manually initialize Fault Sense with custom configuration options.

<script src="https://unpkg.com/faultsense@latest/dist/faultsense-agent.min.js"></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    Faultsense.init({
      releaseLabel: '0.0.0',
      collectorURL: Faultsense.collectors.consoleCollector,
      debug: true
    });
  });
</script>

Next.js Setup

Next.js requires some special handling to get Fault Sense initialized properly.

<Script
  src="https://unpkg.com/faultsense@latest/dist/faultsense-agent.min.js"
  strategy="beforeInteractive"
/>
<Script id="faultsense-agent" strategy="afterInteractive">
  {`
    Faultsense.init({
      releaseLabel: '0.0.0',
      collectorURL: Faultsense.collectors.consoleCollector,
      debug: true,
    });
  `}
</Script>

Configuration Options

All setup methods support the same configuration options. When adding config options as attributes to a script tag, add them as kebab-case data-* attributes. For example, `releaseLabel` would be `data-release-label`. Here's what each option does:

{
  /*
   ** Release identifier for your application (e.g., version number, git commit)
   ** This allows you to monitor the health of features across releases.
   */
  releaseLabel: '1.0.0',
  
  /*
   ** Where to send validation events
   ** Collector URL can be set to a function. A function gives you full control over how events are sent to your backend. 
   ** Faultsense.collectors.consoleCollector is provided that will write events to the console for testing or development.
   */
  collectorURL: 'https://your-backend.com/collect',

  /*
   ** Enable detailed logging for debugging. Default: false
   */
  debug: true,

  /*
   ** The maximum amount of time in milliseconds to wait for an assertion to resolve before failing it. 
   ** This is the global default but can be overridden on an individual assertion. Default: 1_000ms.
   */
  timeout: 1_000,

  /**
   * API Key for the event collection endpoint. Only required if collectorURL is a URL.
   */
  apiKey: "XXXXXXX",
}

Verify Installation

After adding Fault Sense to your page, open your browser's developer console. You should see Fault Sense initialization messages if debug mode is enabled.

// You should see something like:
[Faultsense]: Initializing agent...

Next Steps

Once Fault Sense is installed, you're ready to start adding assertions to your HTML. Check out the Quick Start guide to learn how to add your first assertions and start monitoring user interactions.

Installation