Network Recorder Utility

Principle

Record network traffic to HAR files during test execution, then play back from disk for offline testing. Enables frontend tests to run in complete isolation from backend services with intelligent stateful CRUD detection for realistic API behavior.

Rationale

Traditional E2E tests require live backend services:

Slow (real network latency)
Flaky (backend instability affects tests)
Expensive (full stack running for UI tests)
Coupled (UI tests break when API changes)

HAR-based recording/playback provides:

True offline testing: UI tests run without backend
Deterministic behavior: Same responses every time
Fast execution: No network latency
Stateful mocking: CRUD operations work naturally (not just read-only)
Environment flexibility: Map URLs for any environment

Quick Start

1. Record Network Traffic

// Set mode to 'record' to capture network traffic
process.env.PW_NET_MODE = 'record';

test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
  // Setup network recorder - it will record all network traffic
  await networkRecorder.setup(context);

  // Your normal test code
  await page.goto('/');
  await page.fill('#movie-name', 'Inception');
  await page.click('#add-movie');

  // Network traffic is automatically saved to HAR file
});

2. Playback Network Traffic

// Set mode to 'playback' to use recorded traffic
process.env.PW_NET_MODE = 'playback';

test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
  // Setup network recorder - it will replay from HAR file
  await networkRecorder.setup(context);

  // Same test code runs without hitting real backend!
  await page.goto('/');
  await page.fill('#movie-name', 'Inception');
  await page.click('#add-movie');
});

That's it! Your tests now run completely offline using recorded network traffic.

Pattern Examples

Example 1: Basic Record and Playback

Context: The fundamental pattern - record traffic once, play back for all subsequent runs.

Implementation:

import { test } from '@seontechnologies/playwright-utils/network-recorder/fixtures';

// Set mode in test file (recommended)
process.env.PW_NET_MODE = 'playback'; // or 'record'

test('CRUD operations work offline', async ({ page, context, networkRecorder }) => {
  // Setup recorder (records or plays back based on PW_NET_MODE)
  await networkRecorder.setup(context);

  await page.goto('/');

  // First time (record mode): Records all network traffic to HAR
  // Subsequent runs (playback mode): Plays back from HAR (no backend!)
  await page.fill('#movie-name', 'Inception');
  await page.click('#add-movie');

  // Intelligent CRUD detection makes this work offline!
  await expect(page.getByText('Inception')).toBeVisible();
});

Key Points:

PW_NET_MODE=record captures traffic to HAR files
PW_NET_MODE=playback replays from HAR files
Set mode in test file or via environment variable
HAR files auto-organized by test name
Stateful mocking detects CRUD operations

Example 2: Complete CRUD Flow with HAR

Context: Full create-read-update-delete flow that works completely offline.

Implementation:

process.env.PW_NET_MODE = 'playback';

test.describe('Movie CRUD - offline with network recorder', () => {
  test.beforeEach(async ({ page, networkRecorder, context }) => {
    await networkRecorder.setup(context);
    await page.goto('/');
  });

  test('should add, edit, delete movie browser-only', async ({ page, interceptNetworkCall }) => {
    // Create
    await page.fill('#movie-name', 'Inception');
    await page.fill('#year', '2010');
    await page.click('#add-movie');

    // Verify create (reads from stateful HAR)
    await expect(page.getByText('Inception')).toBeVisible();

    // Update
    await page.getByText('Inception').click();
    await page.fill('#movie-name', "Inception Director's Cut");

    const updateCall = interceptNetworkCall({
      method: 'PUT',
      url: '/movies/*',
    });

    await page.click('#save');
    await updateCall; // Wait for update

    // Verify update (HAR reflects state change!)
    await page.click('#back');
    await expect(page.getByText("Inception Director's Cut")).toBeVisible();

    // Delete
    await page.click(`[data-testid="delete-Inception Director's Cut"]`);

    // Verify delete (HAR reflects removal!)
    await expect(page.getByText("Inception Director's Cut")).not.toBeVisible();
  });
});

Key Points:

Full CRUD operations work offline
Stateful HAR mocking tracks creates/updates/deletes
Combine with interceptNetworkCall for deterministic waits
First run records, subsequent runs replay

Example 3: Common Patterns

Recording Only API Calls:

await networkRecorder.setup(context, {
  recording: {
    urlFilter: /\/api\// // Only record API calls, ignore static assets
  }
});

Playback with Fallback:

await networkRecorder.setup(context, {
  playback: {
    fallback: true // Fall back to live requests if HAR entry missing
  }
});

Custom HAR File Location:

await networkRecorder.setup(context, {
  harFile: {
    harDir: 'recordings/api-calls',
    baseName: 'user-journey',
    organizeByTestFile: false // Optional: flatten directory structure
  }
});

Directory Organization:

organizeByTestFile: true (default): har-files/test-file-name/baseName-test-title.har
organizeByTestFile: false: har-files/baseName-test-title.har

Example 4: Response Content Storage - Embed vs Attach

Context: Choose how response content is stored in HAR files.

embed (Default - Recommended):

await networkRecorder.setup(context, {
  recording: {
    content: 'embed' // Store content inline (default)
  }
});

Pros:

Single self-contained file - Easy to share, version control
Better for small-medium responses (API JSON, HTML pages)
HAR specification compliant

Cons:

Larger HAR files
Not ideal for large binary content (images, videos)

attach (Alternative):

await networkRecorder.setup(context, {
  recording: {
    content: 'attach' // Store content separately
  }
});

Pros:

Smaller HAR files
Better for large responses (images, videos, documents)

Cons:

Multiple files to manage
Harder to share

When to Use Each:

Use `embed` (default) when	Use `attach` when
Recording API responses (JSON, XML)	Recording large images, videos
Small to medium HTML pages	HAR file size >50MB
You want a single, portable file	Maximum disk efficiency needed
Sharing HAR files with team	Working with ZIP archive output

Example 5: Cross-Environment Compatibility (URL Mapping)

Context: Record in dev environment, play back in CI with different base URLs.

The Problem: HAR files contain URLs for the recording environment (e.g., dev.example.com). Playing back on a different environment fails.

Simple Hostname Mapping:

await networkRecorder.setup(context, {
  playback: {
    urlMapping: {
      hostMapping: {
        'preview.example.com': 'dev.example.com',
        'staging.example.com': 'dev.example.com',
        'localhost:3000': 'dev.example.com'
      }
    }
  }
});

Pattern-Based Mapping (Recommended):

await networkRecorder.setup(context, {
  playback: {
    urlMapping: {
      patterns: [
        // Map any preview-XXXX subdomain to dev
        { match: /preview-\d+\.example\.com/, replace: 'dev.example.com' }
      ]
    }
  }
});

Custom Function:

await networkRecorder.setup(context, {
  playback: {
    urlMapping: {
      mapUrl: (url) => url.replace('staging.example.com', 'dev.example.com')
    }
  }
});

Complex Multi-Environment Example:

await networkRecorder.setup(context, {
  playback: {
    urlMapping: {
      hostMapping: {
        'localhost:3000': 'admin.seondev.space',
        'admin-staging.seon.io': 'admin.seondev.space',
        'admin.seon.io': 'admin.seondev.space',
      },
      patterns: [
        { match: /admin-\d+\.seondev\.space/, replace: 'admin.seondev.space' },
        { match: /admin-staging-pr-\w+-\d\.seon\.io/, replace: 'admin.seondev.space' }
      ]
    }
  }
});

Benefits:

Record once on dev, all environments map back to recordings
CORS headers automatically updated based on request origin
Debug with: LOG_LEVEL=debug npm run test

Why Use This Instead of Native Playwright?

Native Playwright (`routeFromHAR`)	network-recorder Utility
~80 lines setup boilerplate	~5 lines total
Manual HAR file management	Automatic file organization
Complex setup/teardown	Automatic cleanup via fixtures
Read-only tests only	Full CRUD support
Stateless	Stateful mocking
Manual URL mapping	Automatic environment mapping

The game-changer: Stateful CRUD detection

Native Playwright HAR playback is stateless - a POST create followed by GET list won't show the created item. This utility intelligently tracks CRUD operations in memory to reflect state changes, making offline tests behave like real APIs.

How Stateful CRUD Detection Works

When in playback mode, the Network Recorder automatically analyzes your HAR file to detect CRUD patterns. If it finds:

Multiple GET requests to the same resource endpoint (e.g., /movies)
Mutation operations (POST, PUT, DELETE) to those resources
Evidence of state changes between identical requests

It automatically switches from static HAR playback to an intelligent stateful mock that:

Maintains state across requests
Auto-generates IDs for new resources
Returns proper 404s for deleted resources
Supports polling scenarios where state changes over time

This happens automatically - no configuration needed!

API Reference

NetworkRecorder Methods

Method	Return Type	Description
`setup(context)`	`Promise<void>`	Sets up recording/playback on browser context
`cleanup()`	`Promise<void>`	Flushes data to disk and cleans up memory
`getContext()`	`NetworkRecorderContext`	Gets current recorder context information
`getStatusMessage()`	`string`	Gets human-readable status message
`getHarStats()`	`Promise<HarFileStats>`	Gets HAR file statistics and metadata

Understanding `cleanup()`

The cleanup() method performs memory and resource cleanup - it does NOT delete HAR files:

What it does:

Flushes recorded data to disk (writes HAR file in recording mode)
Releases file locks
Clears in-memory data
Resets internal state

What it does NOT do:

Delete HAR files from disk
Remove recorded network traffic
Clear browser context or cookies

Configuration Options

type NetworkRecorderConfig = {
  harFile?: {
    harDir?: string // Directory for HAR files (default: 'har-files')
    baseName?: string // Base name for HAR files (default: 'network-traffic')
    organizeByTestFile?: boolean // Organize by test file (default: true)
  }

  recording?: {
    content?: 'embed' | 'attach' // Response content handling (default: 'embed')
    urlFilter?: string | RegExp // URL filter for recording
    update?: boolean // Update existing HAR files (default: false)
  }

  playback?: {
    fallback?: boolean // Fall back to live requests (default: false)
    urlFilter?: string | RegExp // URL filter for playback
    updateMode?: boolean // Update mode during playback (default: false)
  }

  forceMode?: 'record' | 'playback' | 'disabled'
}

Environment Configuration

Control the recording mode using the PW_NET_MODE environment variable:

# Record mode - captures network traffic to HAR files
PW_NET_MODE=record npm run test:pw

# Playback mode - replays network traffic from HAR files
PW_NET_MODE=playback npm run test:pw

# Disabled mode - no network recording/playback
PW_NET_MODE=disabled npm run test:pw

# Default behavior (when PW_NET_MODE is empty/unset) - same as disabled
npm run test:pw

Tip: We recommend setting process.env.PW_NET_MODE directly in your test file for better control.

Troubleshooting

HAR File Not Found

If you see "HAR file not found" errors during playback:

Ensure you've recorded the test first with PW_NET_MODE=record
Check the HAR file exists in the expected location (usually har-files/)
Enable fallback mode: playback: { fallback: true }

Authentication and Network Recording

The network recorder works seamlessly with authentication:

test('Authenticated recording', async ({ page, context, authSession, networkRecorder }) => {
  // First authenticate
  await authSession.login('testuser', 'password');

  // Then setup network recording with authenticated context
  await networkRecorder.setup(context);

  // Test authenticated flows
  await page.goto('/dashboard');
});

Concurrent Test Issues

The recorder includes built-in file locking for safe parallel execution. Each test gets its own HAR file based on the test name.

Integration with Other Utilities

With interceptNetworkCall (deterministic waits):

test('use both utilities', async ({ page, context, networkRecorder, interceptNetworkCall }) => {
  await networkRecorder.setup(context);

  const createCall = interceptNetworkCall({
    method: 'POST',
    url: '/api/movies',
  });

  await page.click('#add-movie');
  await createCall; // Wait for create (works with HAR!)

  // Network recorder provides playback, intercept provides determinism
});

Related Fragments

overview.md - Installation and fixture patterns
intercept-network-call.md - Combine for deterministic offline tests
auth-session.md - Record authenticated traffic
network-first.md - Core pattern for intercept-before-navigate

Anti-Patterns

DON'T mix record and playback in same test:

process.env.PW_NET_MODE = 'record';
// ... some test code ...
process.env.PW_NET_MODE = 'playback'; // Don't switch mid-test

DO use one mode per test:

process.env.PW_NET_MODE = 'playback'; // Set once at top

test('my test', async ({ page, context, networkRecorder }) => {
  await networkRecorder.setup(context);
  // Entire test uses playback mode
});

DON'T forget to call setup:

test('broken', async ({ page, networkRecorder }) => {
  await page.goto('/'); // HAR not active!
});

DO always call setup before navigation:

test('correct', async ({ page, context, networkRecorder }) => {
  await networkRecorder.setup(context); // Must setup first
  await page.goto('/'); // Now HAR is active
});

network-recorder.md 15 KB História Raw