@tapico/msw-webarchive

@tapico/msw-webarchive

A utility to drive requests handlers through a .har web-archive file for the Mock Service Worker library. This utility allows you to mock server handlers by using .har web-archive file which can be created by using applications like Charles, ProxyMan or the Chrome Developer Tools.

Why you use this?

We have been using it during the development of web-applications, while the backend API endpoints weren't available yet or when we want to reproduce a problem of a customer. This way we can request the customer to send us a .har web-archive file and let this file drive the network requests to our back-end, this has greatly eased reproducing problems reported.

Getting started

To use this library you need to have a HAR (*.har) file generated from the network traffic of your application. Follow the instructions below to learn how to do that.

Install

npm install @tapico/msw-webarchive --save-dev

Install Mock Service Worker

Follow the Installation instructions from the Mock Service Worker documentation.

Create a HAR file

Chrome

• Open the DevTools in Chrome (Option + Command + I / Shift + CTRL + J).
• Go to the "Network" tab in the DevTools.
• Click on the downward-facing arrow icon to "Export HAR".
• Save the HAR archive on your disk.

Firefox

• Open the DevTools in Firefox (Option + Command + I / Shift + CTRL + I).
• Go to the "Network" tab in the DevTools.
• Click on the cog icon on the left of the top bar.
• Click "Save All As HAR" option in the dropdown menu.
• Save the HAR archive on your disk.

Generate request handlers

import { setupWorker } from 'msw'
import { setRequestHandlersByWebarchive } from '@tapico/msw-webarchive'
import * as traffic from './example.har'

const worker = setupWorker()
setRequestHandlersByWebarchive(worker, traffic)

worker.start()

Options

quiet: boolean

• Default: false

Disables the logging of debugging messages of the library.

setRequestHandlersByWebarchive(worker, har, {
  quiet: true,
})

strictQueryString: boolean

• Default: true

Stricly match a request URL query parameters during request URL matching. When set to false, request URL query parameters are ignored during matching.

setRequestHandlersByWebarchive(worker, har, {
  strictQueryString: false,
})

resolveCrossOrigins: (origin: string) => string

• Default: undefined

Override the Access-Control-Allow-Origin response header whenever it's present.

setRequestHandlersByWebarchive(worker, har, {
  resolveCrossOrigins(origin) {
    return '*'
  },
})

domainMappings: Record<string, string>

• Default: undefined

Allow mapping the domains in your har file to something else. This may be useful if you are making relative requests against the origin (eg. fetch('/hello')), you may want to use a domainMapping configuration like:

setRequestHandlersByWebarchive(worker, har, {
  domainMappings: {
    'http://example.com': 'http://localhost',
  },
})

responseDelay: 'real' | 'none' | ResponseDelayFunction

• Default: real

Controls the mock response delay behavior.

• real: Responses will be delayed based on the time property in the HAR
• none: Responses will not be delayed
• ResponseDelayFunction: Responses will be delayed by the value returned by the function
  • Signature: (timeDelay: number, requestContext: Request) => number
  • Parameters:
    • timeDelay: the value of the time property in the HAR, or 0 if there is no time property
    • requestContext: the request intercepted by Mock Service Worker
  • Return value:
    • The amount of time that the response should be delayed, in milliseconds. The response will not be delayed if a value <= 0 is returned

setRequestHandlersByWebarchive(worker, har, {
  responseDelay: 'none'
})

setRequestHandlersByWebarchive(worker, har, {
  responseDelay: (timeDelay: number, requestContext: Request) => {
    if (requestContext.url === 'http://example.com') {
      return timeDelay * 2
    }
    return 0
  }
})

Changelog

1.1.0 (2024-06-08)

Features

• Add responseDelay option (#60) (bb08a6f)