Integrating the JavaScript Client

An introduction to the Stoobly JavaScript client library for E2E testing

The Stoobly JavaScript library (npm package stoobly) lets you record, mock, and test HTTP requests directly from end-to-end testing frameworks like Playwright and Cypress. Use it alongside a stoobly-agent scaffold workflow to control interception from your tests.

What is the Stoobly JavaScript client library?

The stoobly npm package (the Stoobly JavaScript client library) 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 — Replay recorded requests

• Testing — Validate API responses against recorded data

Prerequisite

Before using the JavaScript client library, set up Stoobly for E2E testing:

1. Install the agent — stoobly-agent must be available on your machine or in CI

2. Integrate E2E testing — create a scaffold app and services with --plugin playwright or --plugin cypress

The JavaScript client library builds on that scaffold setup. It does not replace creating the app, services, or workflows.

Installation

npm install stoobly --save-dev

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

Integrate with your test framework

After installing the package, wire Stoobly into your E2E tests:

• Playwright — playwrightInterceptor(), withPage(), withContext(), and recording

• Cypress — cypressInterceptor(), enable(), and recording

See Setup for import patterns and framework-specific install steps.

Running the Agent from npm scripts

With your scaffold in place, start the workflow that matches your test mode (mock, record, or test) before running tests. 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.

Configure interception

Configuration covers URL patterns, scenarios, sessions, recording options, and how to start and stop interception from test code.

Reference

• JavaScript Client Library FAQ — full how-to index

• TypeDoc reference — class, method, and type documentation

• Troubleshooting & examples — debugging and complete examples

• GitHub README — quick-start code samples