Using the JavaScript Client

An introduction to the Stoobly JavaScript client library for E2E testing

The Stoobly JavaScript library (stoobly on npm) lets you record, mock, and test HTTP requests directly from end-to-end testing frameworks like Playwright and Cypress, controlling interception from your test code instead of the Stoobly UI. It still runs alongside a stoobly-agent scaffold workflow — see Running the Agent from npm Scripts below for starting and stopping that workflow from package.json.

What is stoobly-js?

stoobly-js integrates with the stoobly-agent to enable:

• Recording — Capture HTTP requests and responses for later replay

• Mocking — Return pre-recorded responses instead of hitting real APIs

• Replay — Re-execute recorded requests

• Testing — Validate API responses against recorded data

Installation

npm install stoobly --save-dev

Requires Node.js 18 or higher. See Setup for import patterns and framework-specific install steps.

Running the Agent from npm Scripts

The stoobly package controls interception from your tests, but a stoobly-agent scaffold workflow (mock, record, or test) still needs to be running alongside them. Rather than starting and stopping it by hand in a separate terminal, wrap it in package.json scripts so it fits your existing npm test flow:

{
  "scripts": {
    "stoobly:mock": "stoobly-agent scaffold workflow up mock --detached",
    "stoobly:mock:down": "stoobly-agent scaffold workflow down mock",
    "test:mock": "npm run stoobly:mock && (npx playwright test; code=$?; npm run stoobly:mock:down; exit $code)"
  }
}

See npm Scripts for the full set of recommended scripts, including record/test variants, diagnostics, and CI setup.

Core Concepts

Intercept Modes

Intercept modes control what the Stoobly agent does with intercepted HTTP requests.

Mode	Description	Use Case
mock	Returns pre-recorded responses	Testing without real APIs
record	Saves requests/responses to storage	Capturing API behavior
replay	Re-executes recorded requests	Reproducing scenarios
test	Validates responses against recorded data	API contract testing

Scenarios

A scenario is a sequence of related HTTP requests that describes a workflow — for example, a "user registration" scenario might include creating a user, fetching their data, then loading a product list. Scenarios let you group related requests, replay entire workflows, share test data with teammates, and mock consistent sequences.

Each scenario has a scenario key, a unique Base64-encoded identifier you can obtain from the Stoobly UI or via stoobly-agent scenario list.

Sessions

A session groups requests within a single test run. Sessions default to the current timestamp if not specified, but can be set manually for consistent identification or to switch between test contexts mid-run.

Context

A context is a collection of requests and scenarios, stored by default in ~/.stoobly. Contexts let you separate different APIs/applications and collaborate by sharing an entire context.

Where to Go Next

• Quick start: stoobly-js README

• How-to and configuration reference: JavaScript Client Library FAQ — installation, Playwright/Cypress integration, URL/scenario/recording configuration, and troubleshooting

• npm scripts reference: npm Scripts — recommended package.json scripts for running workflows, tests, and CI

• Full API reference: TypeDoc reference — complete class, method, and type documentation