Implementation:Microsoft Playwright Client HarRouter

Knowledge Sources	Microsoft_Playwright
Domains	Browser Automation, Network Mocking
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for replaying network requests from HAR (HTTP Archive) files to mock network traffic provided by the Playwright library.

Description

The HarRouter class enables routing network requests through a recorded HAR file. It uses the LocalUtils service to open and look up entries in HAR files. The static create() factory method opens a HAR file and returns a configured HarRouter instance. The private _handle() method processes each intercepted route by looking up the request in the HAR archive based on URL, method, headers, post data, and navigation status. It handles three response actions:

• redirect: Redirects navigation requests to a different URL.
• fulfill: Fulfills the request with the recorded response status, headers, and body. Requests with status -1 (canceled/stalled) are silently stalled.
• error/not found: Either aborts or falls back based on the configured notFoundAction.

The class provides addContextRoute() and addPageRoute() to attach the HAR router to a BrowserContext or Page respectively. It supports URL pattern matching and implements Symbol.asyncDispose for cleanup.

Usage

Use HarRouter when you need to replay recorded network traffic from HAR files in tests. This is useful for deterministic testing against recorded API responses, offline testing, or performance testing without real network calls.

Code Reference

Source Location

• Repository: Microsoft_Playwright
• File: packages/playwright-core/src/client/harRouter.ts

Signature

export class HarRouter {
  static async create(
    localUtils: LocalUtils,
    file: string,
    notFoundAction: 'abort' | 'fallback',
    options: { urlMatch?: URLMatch }
  ): Promise<HarRouter>;

  async addContextRoute(context: BrowserContext): Promise<void>;
  async addPageRoute(page: Page): Promise<void>;
  async [Symbol.asyncDispose](): Promise<void>;
  dispose(): void;
}

Import

import { HarRouter } from 'playwright-core/src/client/harRouter';

I/O Contract

Inputs

Name	Type	Required	Description
localUtils	LocalUtils	Yes	The local utilities service for HAR file operations
file	string	Yes	Path to the HAR file to replay
notFoundAction	'fallback'	Yes	Action to take when a request is not found in the HAR: abort the request or fall through to the next handler
options.urlMatch	URLMatch	No	URL pattern to filter which requests are handled by the HAR router

Outputs

Name	Type	Description
create()	Promise<HarRouter>	A configured HarRouter instance ready to be attached to a context or page
addContextRoute()	Promise<void>	Registers the HAR handler on a browser context
addPageRoute()	Promise<void>	Registers the HAR handler on a specific page

Usage Examples

// Route from HAR file on a page
await page.routeFromHAR('recorded.har', {
  url: '**/api/**',
  notFound: 'abort',
});

// Internal usage via HarRouter directly
const router = await HarRouter.create(localUtils, 'recorded.har', 'fallback', {
  urlMatch: /api\/.*/,
});
await router.addContextRoute(context);

// Clean up
router.dispose();

Related Pages

• Environment:Microsoft_Playwright_Node_Runtime_Environment