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: When should I use withContext() instead of withPage()?

A: Use withContext() when you need to intercept requests from all pages in a browser context, including new pages created during tests. Use withPage() when you only want to intercept requests from a specific page.

Key differences:

• withPage() - Intercepts requests only from the specified page. New pages created in the same context will NOT be intercepted.

• withContext() - Intercepts requests from all pages in the browser context, including pages created with context.newPage(), browser extensions, and service workers.

• Both together - You can use both withContext() and withPage() to ensure all pages are intercepted.

Example:

import { test } 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/.*')],
});

// Scenario 1: Single page interception
test.describe('Page-only interception', () => {
  test.beforeEach(async ({ page }, testInfo) => {
    await interceptor.withPage(page).apply();
    interceptor.withTestTitle(testInfo.title);
  });

  test('intercepts only the fixture page', async ({ context, page }) => {
    await page.goto('https://example.com'); // ✓ Intercepted
    
    // Create a new page
    const page2 = await context.newPage();
    await page2.goto('https://example.com'); // ✗ NOT intercepted
    await page2.close();
  });
});

// Scenario 2: Context-wide interception (recommended for multi-page tests)
test.describe('Context-wide interception', () => {
  test.beforeEach(async ({ context }, testInfo) => {
    await interceptor.withContext(context).apply();
    interceptor.withTestTitle(testInfo.title);
  });

  test('intercepts all pages in context', async ({ context }) => {
    const page1 = await context.newPage();
    await page1.goto('https://example.com'); // ✓ Intercepted
    
    const page2 = await context.newPage();
    await page2.goto('https://example.com'); // ✓ Intercepted
    
    await page1.close();
    await page2.close();
  });
});

// Scenario 3: Both page and context interception
test.describe('Dual interception', () => {
  test.beforeEach(async ({ context, page }, testInfo) => {
    await interceptor.withContext(context).withPage(page).apply();
    interceptor.withTestTitle(testInfo.title);
  });

  test('intercepts fixture page and new pages', async ({ context, page }) => {
    await page.goto('https://example.com'); // ✓ Intercepted (via both)
    
    const page2 = await context.newPage();
    await page2.goto('https://example.com'); // ✓ Intercepted (via context)
    await page2.close();
  });
});

Use withContext() when:

1. Your tests create multiple pages (popups, new tabs)

2. You're testing browser extensions that make background requests

3. You're testing service workers

4. You want consistent interception across all pages without calling withPage() for each

Use withPage() when:

1. You only work with the test fixture page

2. You want fine-grained control over which pages are intercepted

3. You're following the typical Playwright test pattern with a single page

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 complete example showing recording and mocking workflows with an environment variable to toggle recording mode.

Example:

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

// Toggle recording via environment variable
// Set STOOBLY_RECORD=true to enable recording, or leave unset/empty for mocking
const isRecording = process.env.STOOBLY_RECORD === 'true';

const stoobly = new Stoobly();
const interceptor = stoobly.playwrightInterceptor({
  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) => {
    // Configure scenario per test suite
    interceptor.withScenarioKey('<SCENARIO-KEY>');
    
    // Set the page and test title
    interceptor.withPage(page).withTestTitle(testInfo.title);
    
    // Apply recording or mocking mode based on environment variable
    // This applies to all tests in the suite
    if (isRecording) {
      await interceptor.applyRecord();
    } else {
      await interceptor.apply();
    }
  });

  test('can fetch users', async ({ page }) => {
    await page.goto('https://example.com/users');
    
    // If recording: requests are captured for future use
    // If mocking: requests use previously recorded responses
    const users = await page.locator('.user-list').count();
    expect(users).toBeGreaterThan(0);
    
    // Verify the user list is displayed
    await expect(page.locator('.user-list')).toBeVisible();
  });

  test('can create user', async ({ page }) => {
    await page.goto('https://example.com/users/new');
    
    // Fill in the form
    await page.fill('input[name="name"]', 'Test User');
    await page.fill('input[name="email"]', '[email protected]');
    await page.click('button[type="submit"]');
    
    // If recording: the POST request is captured
    // If mocking: uses previously recorded response
    await expect(page.locator('.success')).toBeVisible();
    await expect(page.locator('.success')).toContainText('User created successfully');
  });

  test('can update user', async ({ page }) => {
    await page.goto('https://example.com/users/1');
    
    // Edit user details
    await page.click('button:has-text("Edit")');
    await page.fill('input[name="name"]', 'Updated User');
    await page.click('button:has-text("Save")');
    
    // Verify update was successful
    await expect(page.locator('.success')).toBeVisible();
    await expect(page.locator('h1')).toContainText('Updated User');
  });
});

Usage:

# Run tests in mock mode (default - uses recorded responses)
npm test

# Run tests in record mode (captures new requests)
STOOBLY_RECORD=true npm test

# Or set in your .env file
echo "STOOBLY_RECORD=true" >> .env

Workflow:

1. First run (recording): Set STOOBLY_RECORD=true to capture all API requests and responses

2. Subsequent runs (mocking): Leave STOOBLY_RECORD unset to use recorded responses for fast, reliable tests

3. Update recordings: Set STOOBLY_RECORD=true again when APIs change to refresh the recorded data

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

A: Here's a complete example showing recording and mocking workflows with an environment variable to toggle recording mode.

Example:

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

// Toggle recording via environment variable
// Set STOOBLY_RECORD=true to enable recording, or leave unset/empty for mocking
const isRecording = Cypress.env('STOOBLY_RECORD') === true || process.env.STOOBLY_RECORD === 'true';

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

describe('User API', () => {
  beforeEach(() => {
    // Configure scenario per test suite
    interceptor.withScenarioKey('<SCENARIO-KEY>');
    
    // Apply recording or mocking mode based on environment variable
    // This applies to all tests in the suite
    if (isRecording) {
      interceptor.applyRecord();
    } else {
      interceptor.apply();
    }
  });

  it('can fetch users', () => {
    cy.visit('https://example.com/users');
    
    // If recording: requests are captured for future use
    // If mocking: requests use previously recorded responses
    cy.get('.user-list .user').should('have.length.greaterThan', 0);
    
    // Verify the user list is displayed
    cy.get('.user-list').should('be.visible');
  });

  it('can create user', () => {
    cy.visit('https://example.com/users/new');
    
    // Fill in the form
    cy.get('input[name="name"]').type('Test User');
    cy.get('input[name="email"]').type('[email protected]');
    cy.get('button[type="submit"]').click();
    
    // If recording: the POST request is captured
    // If mocking: uses previously recorded response
    cy.get('.success').should('be.visible');
    cy.get('.success').should('contain', 'User created successfully');
  });

  it('can update user', () => {
    cy.visit('https://example.com/users/1');
    
    // Edit user details
    cy.get('button:contains("Edit")').click();
    cy.get('input[name="name"]').clear().type('Updated User');
    cy.get('button:contains("Save")').click();
    
    // Verify update was successful
    cy.get('.success').should('be.visible');
    cy.get('h1').should('contain', 'Updated User');
  });
});

Usage:

# Run tests in mock mode (default - uses recorded responses)
npm test

# Run tests in record mode (captures new requests)
STOOBLY_RECORD=true npm test

# Or set in Cypress config (cypress.config.js)
export default defineConfig({
  env: {
    STOOBLY_RECORD: true
  }
});

# Or set in your .env file
echo "STOOBLY_RECORD=true" >> .env

Workflow:

1. First run (recording): Set STOOBLY_RECORD=true to capture all API requests and responses

2. Subsequent runs (mocking): Leave STOOBLY_RECORD unset to use recorded responses for fast, reliable tests

3. Update recordings: Set STOOBLY_RECORD=true again when APIs change to refresh the recorded data

---

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