JS Client

Stoobly JavaScript Client Library - Questions & Answers

The Stoobly JavaScript library (stoobly) provides convenient access to stoobly-agent from Playwright and Cypress E2E tests. It enables recording, mocking, and testing HTTP requests directly from your test framework.

📚 Related Documentation:

• For scaffold integration, see ../README.md

• For Docker runtime, see docker.md

• For local runtime, see local.md

---

Installation and Setup

Q: How do I install the Stoobly JavaScript library?

A: Install the library as a dev dependency using npm or yarn.

Example:

# Install with npm
npm install stoobly --save-dev

# Install with yarn
yarn add -D stoobly

Q: What are the requirements for using the Stoobly JavaScript library?

A: The library requires Node.js 18 or higher and works with Playwright and Cypress test frameworks.

Example:

# Check Node version
node --version
# Should output v18.0.0 or higher

# Install with Playwright
npm install stoobly @playwright/test --save-dev

# Install with Cypress
npm install stoobly cypress --save-dev

Q: How do I import the Stoobly library?

A: Import the library using ES modules or CommonJS syntax.

Example:

// ES modules (recommended)
import Stoobly from 'stoobly';
import { RecordPolicy, RecordOrder, RecordStrategy } from 'stoobly/constants';

// CommonJS
const Stoobly = require('stoobly');
const { RecordPolicy, RecordOrder, RecordStrategy } = require('stoobly/constants');

---

Playwright Integration

Q: How do I integrate Stoobly with Playwright tests?

A: Create a Stoobly instance and Playwright interceptor, then call withPage() and apply() in your beforeEach hook.

Example:

import { test, expect } from '@playwright/test';
import Stoobly from 'stoobly';

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

test.describe('My Tests', () => {
  test.beforeEach(async ({ page }, testInfo) => {
    // Required: Set page and test title
    await interceptor.withPage(page).apply();
    interceptor.withTestTitle(testInfo.title);
  });

  test('can fetch data', async ({ page }) => {
    await page.goto('https://example.com');
    // Your test code here
  });
});

Q: Why do I need to call withPage() and withTestTitle() in Playwright?

A: Playwright doesn't provide a global API to auto-detect the current page or test title, so you must explicitly set them in beforeEach.

Example:

test.beforeEach(async ({ page }, testInfo) => {
  // withPage() - Required: Sets the Playwright page for interception
  await interceptor.withPage(page).apply();
  
  // withTestTitle() - Required: Sets the test title for request grouping
  interceptor.withTestTitle(testInfo.title);
});

Q: How do I record requests in Playwright tests?

A: Use applyRecord() instead of apply() to enable recording mode.

Example:

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

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

test.describe('Record Requests', () => {
  test.beforeEach(async ({ page }, testInfo) => {
    // Use applyRecord() to enable recording
    await interceptor.withPage(page).applyRecord();
    interceptor.withTestTitle(testInfo.title);
  });

  test('records API calls', async ({ page }) => {
    await page.goto('https://example.com');
    // All API requests matching urls will be recorded
  });
});

---

Cypress Integration

Q: How do I integrate Stoobly with Cypress tests?

A: Create a Stoobly instance and Cypress interceptor, then call apply() in your beforeEach hook.

Example:

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

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

describe('My Tests', () => {
  beforeEach(() => {
    // Apply interceptor in beforeEach
    interceptor.apply();
  });

  it('can fetch data', () => {
    cy.visit('https://example.com');
    // Your test code here
  });
});

Q: Why must I call apply() in beforeEach for Cypress?

A: Cypress automatically clears all intercepts before every test, so you must reapply the Stoobly interceptor in beforeEach.

Example:

describe('API Tests', () => {
  beforeEach(() => {
    // Required: Reapply interceptor for each test
    // Cypress clears cy.intercept between tests
    interceptor.apply();
  });

  it('test 1', () => {
    // Interceptor is active
  });

  it('test 2', () => {
    // Interceptor must be reapplied (done in beforeEach)
  });
});

Q: How do I record requests in Cypress tests?

A: Use applyRecord() instead of apply() to enable recording mode.

Example:

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

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

describe('Record Requests', () => {
  beforeEach(() => {
    // Use applyRecord() to enable recording
    interceptor.applyRecord();
  });

  it('records API calls', () => {
    cy.visit('https://example.com');
    // All API requests matching urls will be recorded
  });
});

Q: What's the warning about synchronous requests in Cypress?

A: Synchronous XMLHttpRequest calls will cause Cypress to hang. Avoid using synchronous requests when Stoobly interceptor is active.

Example:

// BAD: Synchronous request (will hang Cypress)
const xhr = new XMLHttpRequest();
xhr.open('GET', 'https://api.example.com/data', false); // false = synchronous
xhr.send();

// GOOD: Asynchronous request (works correctly)
const xhr = new XMLHttpRequest();
xhr.open('GET', 'https://api.example.com/data', true); // true = asynchronous
xhr.send();

// BETTER: Use fetch or Cypress commands
cy.request('GET', 'https://api.example.com/data');

---

Configuring URL Patterns

Q: How do I specify which URLs to intercept?

A: Use the urls array with strings or regular expressions to filter which requests Stoobly intercepts.

Example:

const stoobly = new Stoobly();

// Exact URL match
const interceptor1 = stoobly.playwrightInterceptor({
  urls: ['https://api.example.com/users'],
  scenarioKey: '<SCENARIO-KEY>',
});

// Regex pattern (match all API endpoints)
const interceptor2 = stoobly.playwrightInterceptor({
  urls: [new RegExp('https://api.example.com/.*')],
  scenarioKey: '<SCENARIO-KEY>',
});

// Multiple URLs
const interceptor3 = stoobly.playwrightInterceptor({
  urls: [
    'https://api.example.com/users',
    'https://api.example.com/products',
    new RegExp('https://cdn.example.com/.*'),
  ],
  scenarioKey: '<SCENARIO-KEY>',
});

Q: How do I change the intercepted URLs dynamically?

A: Pass a new urls array to the apply() method to update which URLs are intercepted.

Example:

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

test.beforeEach(async ({ page }) => {
  await interceptor.withPage(page).apply();
});

test('changes URLs dynamically', async ({ page }) => {
  // Initially intercepts api.example.com
  await page.goto('https://example.com');

  // Change to intercept different URLs
  await interceptor.apply({ 
    urls: [new RegExp('https://cdn.example.com/.*')] 
  });

  // Now intercepts cdn.example.com instead
  await page.goto('https://example.com');
});

---

Scenarios and Sessions

Q: How do I specify a scenario for my tests?

A: Use scenarioKey or scenarioName in the interceptor options to associate requests with a scenario.

Example:

// Using scenario key (recommended)
const interceptor1 = stoobly.playwrightInterceptor({
  scenarioKey: 'p0.ia88b835b1729422b9514de25d9306a12',
  urls: [new RegExp('https://api.example.com/.*')],
});

// Using scenario name (must be unique)
const interceptor2 = stoobly.playwrightInterceptor({
  scenarioName: 'my-test-scenario',
  urls: [new RegExp('https://api.example.com/.*')],
});

Q: How do I change the scenario dynamically?

A: Use withScenarioKey() or withScenarioName() to update the scenario.

Example:

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

test('switches scenarios', async ({ page }) => {
  // Use scenario A
  interceptor.withScenarioKey('scenario-a-key');
  await interceptor.withPage(page).apply();
  await page.goto('https://example.com');

  // Switch to scenario B
  interceptor.withScenarioKey('scenario-b-key');
  await page.goto('https://example.com/other');
});

Q: What is a session ID and how do I use it?

A: A session ID groups requests together within a scenario. It defaults to the current timestamp but can be customized for test reproducibility.

Example:

// Default session ID (auto-generated timestamp)
const interceptor1 = stoobly.playwrightInterceptor({
  scenarioKey: '<SCENARIO-KEY>',
  urls: [new RegExp('https://api.example.com/.*')],
});

// Custom session ID
const interceptor2 = stoobly.playwrightInterceptor({
  scenarioKey: '<SCENARIO-KEY>',
  sessionId: 'test-session-123',
  urls: [new RegExp('https://api.example.com/.*')],
});

// Change session ID dynamically
test('changes session', async ({ page }) => {
  interceptor.withSessionId('session-1');
  await interceptor.withPage(page).apply();
  await page.goto('https://example.com');

  interceptor.withSessionId('session-2');
  await page.goto('https://example.com/other');
});

---

Recording Configuration

Q: What record policies are available?

A: Stoobly supports three record policies: All (record everything), Found (record only if request exists), and NotFound (record only new requests).

Example:

import { RecordPolicy } from 'stoobly/constants';

// Record all requests (default)
const interceptor1 = stoobly.playwrightInterceptor({
  urls: [new RegExp('https://api.example.com/.*')],
  record: { policy: RecordPolicy.All },
});

// Record only if request already exists in scenario
const interceptor2 = stoobly.playwrightInterceptor({
  urls: [new RegExp('https://api.example.com/.*')],
  record: { policy: RecordPolicy.Found },
});

// Record only new requests (not already in scenario)
const interceptor3 = stoobly.playwrightInterceptor({
  urls: [new RegExp('https://api.example.com/.*')],
  record: { policy: RecordPolicy.NotFound },
});

Q: What's the difference between record orders?

A: Overwrite replaces existing requests with the same signature, while Append always creates new request records.

Example:

import { RecordOrder } from 'stoobly/constants';

// Overwrite existing requests (useful for updating mocks)
const interceptor1 = stoobly.playwrightInterceptor({
  urls: [new RegExp('https://api.example.com/.*')],
  record: { order: RecordOrder.Overwrite },
});

// Append new requests (useful for collecting multiple responses)
const interceptor2 = stoobly.playwrightInterceptor({
  urls: [new RegExp('https://api.example.com/.*')],
  record: { order: RecordOrder.Append },
});

Note: Overwrite is sent only once per session. Subsequent requests use Append behavior.

Q: What record strategies are available?

A: Stoobly supports Full (record complete request/response) and Minimal (record only essential data).

Example:

import { RecordStrategy } from 'stoobly/constants';

// Full recording (complete request and response data)
const interceptor1 = stoobly.playwrightInterceptor({
  urls: [new RegExp('https://api.example.com/.*')],
  record: { strategy: RecordStrategy.Full },
});

// Minimal recording (essential data only)
const interceptor2 = stoobly.playwrightInterceptor({
  urls: [new RegExp('https://api.example.com/.*')],
  record: { strategy: RecordStrategy.Minimal },
});

Q: How do I change record settings dynamically?

A: Use withRecordPolicy(), withRecordOrder(), and withRecordStrategy() methods.

Example:

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

test('changes record settings', async ({ page }) => {
  // Set record options
  interceptor.withRecordPolicy(RecordPolicy.All);
  interceptor.withRecordOrder(RecordOrder.Overwrite);
  interceptor.withRecordStrategy(RecordStrategy.Full);
  
  await interceptor.withPage(page).applyRecord();
  await page.goto('https://example.com');

  // Change to minimal strategy
  interceptor.withRecordStrategy(RecordStrategy.Minimal);
  await page.goto('https://example.com/other');
});

---

Controlling Interception

Q: How do I stop recording requests?

A: Use clearRecord() to stop recording while keeping the interceptor active for mocking.

Example:

test('stops recording', async ({ page }) => {
  // Start recording
  await interceptor.withPage(page).applyRecord();
  await page.goto('https://example.com'); // Recorded

  // Stop recording
  await interceptor.clearRecord();
  await page.goto('https://example.com/other'); // Not recorded (uses mock)
});

Q: How do I completely remove the interceptor?

A: Use clear() to remove all interception and clear all headers.

Example:

test('removes interceptor', async ({ page }) => {
  // Apply interceptor
  await interceptor.withPage(page).apply();
  await page.goto('https://example.com'); // Intercepted

  // Remove interceptor
  await interceptor.clear();
  await page.goto('https://example.com/other'); // Not intercepted
});

Q: What's the difference between clear() and clearRecord()?

A: clearRecord() stops recording but keeps mocking active, while clear() removes all interception.

Example:

// clearRecord() - Stops recording, keeps mocking
test('clearRecord example', async ({ page }) => {
  await interceptor.withPage(page).applyRecord();
  await page.goto('https://example.com'); // Records + Mocks
  
  await interceptor.clearRecord();
  await page.goto('https://example.com'); // Only Mocks (no recording)
});

// clear() - Removes everything
test('clear example', async ({ page }) => {
  await interceptor.withPage(page).apply();
  await page.goto('https://example.com'); // Mocks
  
  await interceptor.clear();
  await page.goto('https://example.com'); // No interception
});

---

Advanced Configuration

Q: How do I set a custom Stoobly UI URL?

A: Pass the UI URL to the Stoobly constructor if your agent is running on a different port or host.

Example:

// Default (http://localhost:4200)
const stoobly1 = new Stoobly();

// Custom URL
const stoobly2 = new Stoobly('http://localhost:8080');

// Remote agent
const stoobly3 = new Stoobly('https://stoobly-agent.company.com');

Q: How do I use test titles for request grouping?

A: Set test titles using withTestTitle() to group requests by test name in the Stoobly UI.

Example:

// Playwright (manual test title)
test.beforeEach(async ({ page }, testInfo) => {
  await interceptor.withPage(page).apply();
  interceptor.withTestTitle(testInfo.title);
});

// Cypress (auto-detected test title)
beforeEach(() => {
  interceptor.apply();
  // Test title is automatically detected
});

// Clear test title
interceptor.withTestTitle(undefined);

Q: Can I use the interceptor without a test framework?

A: Yes, use the generic interceptor() method for vanilla JavaScript applications.

Example:

import Stoobly from 'stoobly';

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

// Apply interception
const sessionId = interceptor.apply();
console.log('Session ID:', sessionId);

// Make requests (fetch/XMLHttpRequest will be intercepted)
fetch('https://api.example.com/users');

// Stop interception
interceptor.clear();

---

Troubleshooting

Q: Why aren't my requests being intercepted?

A: Verify the URL patterns match your requests, the interceptor is applied in beforeEach, and stoobly-agent is running.

Example:

// Check URL pattern
const interceptor = stoobly.playwrightInterceptor({
  urls: [new RegExp('https://api.example.com/.*')], // Make sure pattern matches
  scenarioKey: '<SCENARIO-KEY>',
});

test.beforeEach(async ({ page }, testInfo) => {
  // Ensure interceptor is applied
  await interceptor.withPage(page).apply();
  interceptor.withTestTitle(testInfo.title);
});

// Verify stoobly-agent is running
// stoobly-agent run --headless

Q: How do I debug interceptor issues?

A: Check the browser's network tab for Stoobly headers and verify the agent is receiving requests.

Example:

// Add logging to verify interceptor is working
test('debug interceptor', async ({ page }) => {
  const sessionId = await interceptor.withPage(page).apply();
  console.log('Session ID:', sessionId);

  // Check request headers in browser DevTools
  await page.goto('https://example.com');

  // Look for these headers in Network tab:
  // - stoobly-scenario-key
  // - stoobly-session-id
  // - stoobly-test-title
});

Q: Why do I get "page is not defined" errors in Playwright?

A: Ensure you call withPage(page) in beforeEach before apply().

Example:

// BAD: Missing withPage()
test.beforeEach(async ({ page }, testInfo) => {
  await interceptor.apply(); // ERROR: page not set
});

// GOOD: Call withPage() first
test.beforeEach(async ({ page }, testInfo) => {
  await interceptor.withPage(page).apply(); // Correct
  interceptor.withTestTitle(testInfo.title);
});

Q: How do I handle TypeScript errors?

A: The library includes TypeScript definitions. Ensure your tsconfig.json includes the library.

Example:

{
  "compilerOptions": {
    "types": ["@playwright/test", "stoobly"],
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

---

Complete Examples

Q: What's a complete Playwright example with recording and mocking?

A: Here's a full example showing recording and mocking workflows.

Example:

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

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

test.describe('User API', () => {
  test.beforeEach(async ({ page }, testInfo) => {
    await interceptor.withPage(page).apply();
    interceptor.withTestTitle(testInfo.title);
  });

  test('can fetch users (mock mode)', async ({ page }) => {
    await page.goto('https://example.com/users');
    
    // Verify data from mock
    const users = await page.locator('.user-list').count();
    expect(users).toBeGreaterThan(0);
  });

  test('can create user (record mode)', async ({ page }) => {
    // Switch to recording mode for this test
    await interceptor.withPage(page).applyRecord();
    
    await page.goto('https://example.com/users/new');
    await page.fill('input[name="name"]', 'Test User');
    await page.click('button[type="submit"]');
    
    // Request is recorded for future mocking
    await expect(page.locator('.success')).toBeVisible();
  });
});

Q: What's a complete Cypress example with recording and mocking?

A: Here's a full example showing recording and mocking workflows.

Example:

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

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

describe('User API', () => {
  beforeEach(() => {
    interceptor.apply();
  });

  it('can fetch users (mock mode)', () => {
    cy.visit('https://example.com/users');
    
    // Verify data from mock
    cy.get('.user-list .user').should('have.length.greaterThan', 0);
  });

  it('can create user (record mode)', () => {
    // Switch to recording mode for this test
    interceptor.applyRecord();
    
    cy.visit('https://example.com/users/new');
    cy.get('input[name="name"]').type('Test User');
    cy.get('button[type="submit"]').click();
    
    // Request is recorded for future mocking
    cy.get('.success').should('be.visible');
  });
});

---

Quick Reference

Q: What are the key methods for the interceptor?

A: Here's a quick reference of the most common interceptor methods.

Example:

const interceptor = stoobly.playwrightInterceptor(options);

// Apply interception
await interceptor.withPage(page).apply();
await interceptor.applyRecord(); // Enable recording mode

// Configure scenario
interceptor.withScenarioKey('key');
interceptor.withScenarioName('name');
interceptor.withSessionId('session-id');
interceptor.withTestTitle('test title');

// Configure recording
interceptor.withRecordPolicy(RecordPolicy.All);
interceptor.withRecordOrder(RecordOrder.Overwrite);
interceptor.withRecordStrategy(RecordStrategy.Full);

// Control interception
await interceptor.clear(); // Remove all interception
await interceptor.clearRecord(); // Stop recording, keep mocking

// Change URLs
await interceptor.apply({ urls: [new RegExp('...')] });

Q: What constants are available?

A: Stoobly provides enums for record policies, orders, and strategies.

Example:

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

// Record Policies
RecordPolicy.All       // Record all requests
RecordPolicy.Found     // Record only if exists
RecordPolicy.NotFound  // Record only if new

// Record Orders
RecordOrder.Overwrite  // Replace existing
RecordOrder.Append     // Always create new

// Record Strategies
RecordStrategy.Full    // Complete data
RecordStrategy.Minimal // Essential data only

// Intercept Modes
InterceptMode.mock     // Mocking mode
InterceptMode.record   // Recording mode
InterceptMode.replay   // Replay mode
InterceptMode.test     // Testing mode