JavaScript

See the:

• README & Quick Start - Installation and basic setup

• Full API Documentation - Complete TypeDoc reference

This document provides a comprehensive reference for all APIs, configuration options, and concepts.

---

QUICK REFERENCE

What is stoobly-js?

stoobly-js is a library for HTTP request interception, recording, and mocking with Stoobly. The JavaScript library (stoobly npm package) 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

Minimum Requirements

• Node.js 18 or higher

Import Patterns

// CommonJS
const Stoobly = require('stoobly');

// ES Modules
import Stoobly from 'stoobly';

// Import constants
import { RecordPolicy, RecordOrder, RecordStrategy, InterceptMode } from 'stoobly/constants';

// Import types (TypeScript)
import { InterceptorOptions, RecordOptions } from 'stoobly/types';

---

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:

1. POST /user - Create user

2. GET /user/{id} - Fetch user data

3. GET /products - Load product list

Scenarios enable:

• Grouping related requests together

• Replaying entire workflows

• Sharing test data with teammates

• Mocking consistent sequences

Scenario Key: A unique Base64-encoded identifier for each scenario. Obtain from the Stoobly UI or CLI:

stoobly-agent scenario list

Sessions

A session groups requests within a test run. Sessions:

• Default to current timestamp if not specified

• Can be manually set for consistent identification

• Enable switching between different test contexts

Context

A context is a collection of requests and scenarios. The default context is stored in ~/.stoobly. Contexts enable:

• Separation of different APIs/applications

• Collaboration by sharing entire contexts

---

API REFERENCE

Stoobly Class

The main entry point for the library.

class Stoobly {
  constructor(apiUrl?: string)  // Default: 'http://localhost:4200'

  // Properties
  httpService: HttpService      // Direct HTTP service access
  config: Config               // Configuration management

  // Methods
  set apiUrl(url: string)      // Update API URL

  // Create interceptors
  interceptor(options: InterceptorOptions): Interceptor
  cypressInterceptor(options: InterceptorOptions): Cypress
  playwrightInterceptor(options: InterceptorOptions): Playwright
}

Example:

import Stoobly from 'stoobly';

const stoobly = new Stoobly();  // Uses default localhost:4200
// OR
const stoobly = new Stoobly('http://custom-agent:4200');

---

InterceptorOptions Interface

Configuration object for all interceptor types.

interface InterceptorOptions {
  urls: (RegExp | string)[];     // REQUIRED: URLs to intercept
  scenarioKey?: string;          // Base64 scenario identifier
  scenarioName?: string;         // Human-readable name (must be unique)
  sessionId?: string;            // Session ID (defaults to timestamp)
  record?: RecordOptions;        // Recording configuration
  framework?: 'cypress' | 'playwright';  // Test framework
}

URL Patterns:

// Exact URL match
urls: ['https://api.example.com/users']

// Regex pattern
urls: [new RegExp('https://api.example.com/.*')]

// Multiple patterns
urls: [
  'https://api.example.com/users',
  new RegExp('https://api.example.com/products/.*')
]

---

RecordOptions Interface

Configuration for recording behavior.

interface RecordOptions {
  policy?: RecordPolicy;     // Which requests to record
  order?: RecordOrder;       // How to handle duplicates
  strategy?: RecordStrategy; // Recording detail level
}

---

Interceptor Class (Base)

The generic interceptor that patches fetch and XMLHttpRequest directly.

class Interceptor {
  // Core methods
  apply(options?: Partial<InterceptorOptions>): string | Promise<string>
  applyRecord(options?: Partial<InterceptorOptions>): string | Promise<string>
  clear(): void
  clearRecord(): void

  // Builder methods (chainable, return this)
  withTestTitle(title?: string): this
  withInterceptMode(mode?: InterceptMode): this
  withRecordOrder(order?: RecordOrder): this
  withRecordPolicy(policy?: RecordPolicy): this
  withRecordStrategy(strategy?: RecordStrategy): this
  withScenarioKey(key?: string): this
  withScenarioName(name?: string): this
  withSessionId(sessionId?: string): this
}

Key Behaviors:

• apply() - Activates interception, returns session ID

• applyRecord() - Activates recording mode, returns session ID

• clear() - Removes all interception

• clearRecord() - Stops recording but keeps other interception

Example:

const stoobly = new Stoobly();
const interceptor = stoobly.interceptor({
  scenarioKey: 'eyJwIjogMCwgImkiOiAzfQo=',
  urls: [new RegExp('https://api.example.com/.*')]
});

// Start intercepting (returns session ID)
const sessionId = interceptor.apply();

// Later, change session
interceptor.withSessionId('new-session-id');

// Stop all interception
interceptor.clear();

---

Cypress Class

Specialized interceptor for Cypress test framework. Extends Interceptor.

Key Differences from Base Interceptor:

• Uses cy.intercept() instead of patching fetch/XMLHttpRequest

• Must be called in beforeEach() (Cypress clears intercepts before each test)

• Test titles are automatically detected

import Stoobly from 'stoobly';
import { RecordPolicy, RecordOrder, RecordStrategy } from 'stoobly/constants';

const stoobly = new Stoobly();
const stooblyInterceptor = stoobly.cypressInterceptor({
  scenarioKey: '<SCENARIO-KEY>',
  urls: ['https://api.example.com/.*'],
  record: {
    policy: RecordPolicy.All,
    order: RecordOrder.Overwrite,
    strategy: RecordStrategy.Full,
  }
});

describe('My Test Suite', () => {
  beforeEach(() => {
    // IMPORTANT: Must be in beforeEach, not before
    stooblyInterceptor.apply();

    // Or for recording:
    // stooblyInterceptor.applyRecord();
  });

  it('tests something', () => {
    // Your test code
  });
});

Warning: Cypress hangs with synchronous XMLHttpRequest. See Cypress issue #29566.

---

Playwright Class

Specialized interceptor for Playwright test framework. Extends Interceptor.

Key Differences from Base Interceptor:

• Uses Playwright's page.route() API

• All main methods are async

• Requires explicit page setup via withPage()

• Test titles must be set manually via withTestTitle()

class Playwright extends Interceptor {
  // Page management
  withPage(page: Page): this

  // Async versions (override parent)
  async apply(options?: Partial<InterceptorOptions>): Promise<string>
  async applyRecord(options?: Partial<InterceptorOptions>): Promise<string>
  async clear(): Promise<void>
  async clearRecord(): Promise<void>
}

Example:

import { test } from '@playwright/test';
import Stoobly from 'stoobly';
import { RecordPolicy, RecordOrder, RecordStrategy } from 'stoobly/constants';

const stoobly = new Stoobly();
const stooblyInterceptor = stoobly.playwrightInterceptor({
  scenarioKey: '<SCENARIO-KEY>',
  urls: ['https://api.example.com/.*'],
  record: {
    policy: RecordPolicy.All,
    order: RecordOrder.Overwrite,
    strategy: RecordStrategy.Full,
  }
});

test.describe('My Test Suite', () => {
  test.beforeEach(async ({ page }, testInfo) => {
    // IMPORTANT: Must set page before apply
    await stooblyInterceptor.withPage(page).apply();

    // IMPORTANT: Must set test title manually (Playwright has no global API)
    stooblyInterceptor.withTestTitle(testInfo.title);

    // Or for recording:
    // await stooblyInterceptor.withPage(page).applyRecord();
  });

  test('tests something', async ({ page }) => {
    // Your test code
  });
});

---

CONSTANTS REFERENCE

Import from stoobly/constants:

import {
  InterceptMode,
  RecordPolicy,
  RecordOrder,
  RecordStrategy,
  MockPolicy,
  ReplayPolicy,
  TestPolicy,
  TestStrategy,
  FirewallAction,
  RequestParameter,
} from 'stoobly/constants';

InterceptMode

enum InterceptMode {
  mock = 'mock'      // Return recorded responses
  record = 'record'  // Save requests/responses
  replay = 'replay'  // Re-execute requests
  test = 'test'      // Validate responses
}

RecordPolicy

Controls which requests get recorded.

enum RecordPolicy {
  All = 'all'            // Record all matching requests
  Found = 'found'        // Record only requests matching saved scenarios
  NotFound = 'not_found' // Record only NEW requests (not previously recorded)
}

RecordOrder

Controls how duplicate recordings are handled.

enum RecordOrder {
  Append = 'append'      // Add to existing recordings (DEFAULT)
  Overwrite = 'overwrite' // Replace existing recordings
}

RecordStrategy

Controls recording detail level.

enum RecordStrategy {
  Full = 'full'       // Record all request/response data
  Minimal = 'minimal' // Record minimal data
}

MockPolicy

Controls mocking behavior.

enum MockPolicy {
  All = 'all'     // Mock all requests (return 404 if not found)
  Found = 'found' // Mock only requests with recordings (pass-through others)
}

ReplayPolicy

enum ReplayPolicy {
  All = 'all'  // Replay all requests
}

TestPolicy

enum TestPolicy {
  All = 'all'     // Test all requests
  Found = 'found' // Test only requests with recordings
}

TestStrategy

enum TestStrategy {
  Diff = 'diff'     // Exact difference comparison
  Fuzzy = 'fuzzy'   // Approximate comparison
  Custom = 'custom' // Custom comparison logic
}

FirewallAction

enum FirewallAction {
  Exclude = 'exclude' // Block matching URLs
  Include = 'include' // Allow matching URLs
}

RequestParameter

enum RequestParameter {
  Header = 'Header'         // HTTP headers
  BodyParam = 'Body Param'  // Request body parameters
  QueryParam = 'Query Param' // URL query parameters
}

---

HTTP HEADERS INJECTED

The library injects custom headers into matching HTTP requests:

Header	Description
X-Stoobly-Proxy-Mode	Active intercept mode (mock/record/replay/test)
X-Stoobly-Record-Order	Recording order (append/overwrite)
X-Stoobly-Record-Policy	Recording policy (all/found/not_found)
X-Stoobly-Record-Strategy	Recording strategy (full/minimal)
X-Stoobly-Scenario-Key	Base64-encoded scenario identifier
X-Stoobly-Scenario-Name	Human-readable scenario name
X-Stoobly-Session-Id	Current session identifier
X-Stoobly-Test-Title	Current test name (auto-detected or manual)

---

CONFIG API

Access Stoobly agent configuration:

const stoobly = new Stoobly();

// Get full configuration
const config = await stoobly.config.dump();

// Get configuration summary
const summary = await stoobly.config.summary();

// Set active scenario
await stoobly.config.scenario.set('<SCENARIO-KEY>');

---

COMMON PATTERNS

Basic Mocking (No Test Framework)

import Stoobly from 'stoobly';

const stoobly = new Stoobly();
const interceptor = stoobly.interceptor({
  scenarioKey: 'eyJwIjogMCwgImkiOiAzfQo=',
  urls: [new RegExp('https://api.example.com/.*')]
});

// Start mocking
interceptor.apply();

// Make API calls - they'll return recorded responses
fetch('https://api.example.com/users');

// Stop mocking
interceptor.clear();

Recording New Requests

import Stoobly from 'stoobly';
import { RecordPolicy, RecordOrder, RecordStrategy } from 'stoobly/constants';

const stoobly = new Stoobly();
const interceptor = stoobly.interceptor({
  urls: ['https://api.example.com/.*'],
  record: {
    policy: RecordPolicy.All,
    order: RecordOrder.Append,
    strategy: RecordStrategy.Full,
  }
});

// Start recording
interceptor.applyRecord();

// Make API calls - they'll be recorded
await fetch('https://api.example.com/users');

// Stop recording
interceptor.clearRecord();

Switching Sessions Mid-Test

const interceptor = stoobly.interceptor({
  scenarioKey: '<KEY>',
  sessionId: 'session-1',
  urls: [new RegExp('https://api.example.com/.*')]
});

interceptor.apply();
// Requests go to session-1

interceptor.withSessionId('session-2');
// Now requests go to session-2

Overwriting Existing Recordings

const interceptor = stoobly.interceptor({
  urls: ['https://api.example.com/.*'],
  record: {
    order: RecordOrder.Overwrite,  // Replace existing recordings
    policy: RecordPolicy.All,
  }
});

interceptor.applyRecord();

Recording Only New Requests

const interceptor = stoobly.interceptor({
  urls: ['https://api.example.com/.*'],
  record: {
    policy: RecordPolicy.NotFound,  // Only record if not already recorded
  }
});

interceptor.applyRecord();

---

REQUEST MATCHING (Mocking)

When mocking, Stoobly matches requests using these components (case-sensitive):

1. HTTP Method (required) - GET, POST, PUT, DELETE, etc.

2. Path (required) - e.g., /users

3. Query Parameters - Sorted alphabetically before comparison

4. Headers - Sorted alphabetically before comparison

5. Body - Strict matching if provided

6. Body Parameters - Parsed from JSON or form-urlencoded, sorted alphabetically

With Scenario: Only requests in that scenario are matched. Multiple matches return responses in recording order.

Without Scenario: Any matching request is considered.

---

PROXY SETTINGS (Agent Configuration)

These settings are configured in the Stoobly agent UI or via CLI, not the JS library:

Data Rules

• Scenario: Which scenario to record to / mock from

• Policy: Which requests to record/mock

Firewall Rules

Fine-grained URL filtering:

• Pattern: Regex to match request URLs

• Action: Include or Exclude

• Methods: Which HTTP verbs

• Modes: Which intercept modes (mock, record, replay)

Example: Exclude OAuth token requests from recording:

Pattern: https://internal.company.com/v1/token
Action: Exclude
Methods: POST
Modes: Record

Match Rules

Customize which request components are used for matching (mocking only):

• Components: Header, Body Param, Query Param

• Default: Query params and body only (method/path always required)

Rewrite Rules

Modify request components before processing:

• Pattern: URL pattern to match

• Parameter Type: Header, Body Param, or Query Param

• Name/Value: What to rewrite

Example: Redact auth tokens during recording:

Pattern: https://api.example.com/.*
Parameter: Header
Name: Authorization
Value: REDACTED
Modes: Record

---

TROUBLESHOOTING

Common Issues

Q: Requests aren't being intercepted

• Verify URLs match your patterns (check regex)

• Ensure apply() or applyRecord() was called

• For Cypress: Must call in beforeEach(), not before()

• For Playwright: Must call withPage(page) before apply()

Q: Cypress tests hang

• Check for synchronous XMLHttpRequest usage (not supported)

• See Cypress issue #29566

Q: Test titles not being captured

• Cypress: Automatic

• Playwright: Must call withTestTitle(testInfo.title) manually

Q: How to find scenario key?

• UI: Scenarios page → Click scenario → Key field

• CLI: stoobly-agent scenario list

Q: Recordings not matching during mock

• Check all matching components (method, path, query params, body, headers)

• Use Match Rules to relax constraints

• Ensure correct scenario is selected

---

TYPE DEFINITIONS

Full TypeScript types available in stoobly/types:

import {
  InterceptorOptions,
  RecordOptions,
  Page,      // Playwright page type
  Route,     // Playwright route type
  Request    // Playwright request type
} from 'stoobly/types';

---

COMPLETE EXAMPLE: CYPRESS E2E TEST

// cypress/support/e2e.js
import Stoobly from 'stoobly';
import { RecordPolicy, RecordOrder, RecordStrategy } from 'stoobly/constants';

const stoobly = new Stoobly();

// Create interceptor once, reuse across tests
export const apiInterceptor = stoobly.cypressInterceptor({
  scenarioKey: process.env.STOOBLY_SCENARIO_KEY,
  urls: [
    new RegExp('https://api.myapp.com/.*'),
    new RegExp('https://auth.myapp.com/.*'),
  ],
  record: {
    policy: RecordPolicy.NotFound,  // Only record new requests
    order: RecordOrder.Append,
    strategy: RecordStrategy.Full,
  }
});

// cypress/e2e/user-flow.cy.js
import { apiInterceptor } from '../support/e2e';

describe('User Registration Flow', () => {
  beforeEach(() => {
    // Enable mocking (use applyRecord() to record instead)
    apiInterceptor.apply();
  });

  it('should register a new user', () => {
    cy.visit('/register');
    cy.get('[data-cy=email]').type('[email protected]');
    cy.get('[data-cy=submit]').click();
    cy.get('[data-cy=success]').should('be.visible');
  });

  it('should show user profile after login', () => {
    cy.visit('/login');
    cy.get('[data-cy=email]').type('[email protected]');
    cy.get('[data-cy=password]').type('password');
    cy.get('[data-cy=submit]').click();
    cy.get('[data-cy=profile-name]').should('contain', 'User');
  });
});

---

COMPLETE EXAMPLE: PLAYWRIGHT E2E TEST

// tests/helpers/stoobly.ts
import Stoobly from 'stoobly';
import { RecordPolicy, RecordOrder, RecordStrategy } from 'stoobly/constants';

const stoobly = new Stoobly();

export const apiInterceptor = stoobly.playwrightInterceptor({
  scenarioKey: process.env.STOOBLY_SCENARIO_KEY,
  urls: [
    'https://api.myapp.com/**',
    'https://auth.myapp.com/**',
  ],
  record: {
    policy: RecordPolicy.All,
    order: RecordOrder.Overwrite,
    strategy: RecordStrategy.Full,
  }
});

// tests/user-flow.spec.ts
import { test, expect } from '@playwright/test';
import { apiInterceptor } from './helpers/stoobly';

test.describe('User Registration Flow', () => {
  test.beforeEach(async ({ page }, testInfo) => {
    // Set page and enable mocking
    await apiInterceptor.withPage(page).apply();

    // Set test title for request tracking
    apiInterceptor.withTestTitle(testInfo.title);

    // For recording instead:
    // await apiInterceptor.withPage(page).applyRecord();
  });

  test('should register a new user', async ({ page }) => {
    await page.goto('/register');
    await page.fill('[data-testid=email]', '[email protected]');
    await page.click('[data-testid=submit]');
    await expect(page.locator('[data-testid=success]')).toBeVisible();
  });

  test('should show user profile after login', async ({ page }) => {
    await page.goto('/login');
    await page.fill('[data-testid=email]', '[email protected]');
    await page.fill('[data-testid=password]', 'password');
    await page.click('[data-testid=submit]');
    await expect(page.locator('[data-testid=profile-name]')).toContainText('User');
  });
});

---

SUMMARY TABLE

Feature	Method/Property	Notes
Create interceptor	stoobly.interceptor(options)	Generic (patches fetch/XHR)
Create Cypress interceptor	stoobly.cypressInterceptor(options)	Uses cy.intercept
Create Playwright interceptor	stoobly.playwrightInterceptor(options)	Uses page.route
Start intercepting	interceptor.apply()	Returns session ID
Start recording	interceptor.applyRecord()	Sets mode to record
Stop all	interceptor.clear()	Removes interception
Stop recording	interceptor.clearRecord()	Keeps other modes
Set scenario	interceptor.withScenarioKey(key)	Chainable
Set session	interceptor.withSessionId(id)	Chainable
Set test title	interceptor.withTestTitle(title)	Chainable
Set intercept mode	interceptor.withInterceptMode(mode)	Chainable
Get config	stoobly.config.dump()	Returns Promise
Set scenario (config)	stoobly.config.scenario.set(key)	Returns Promise