Playwright

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
  });
});