Network

Tapsmith supports Playwright-style network interception. Route handlers let you mock, modify, or abort HTTP/HTTPS requests made by the app under test.

device.route(url, handler, options?): Promise<void>

Intercept network requests matching a URL pattern. Requires network tracing to be recording the test (a trace mode that records the attempt — 'on' or a 'retain-on-…' mode for every attempt; 'on-first-retry' / 'on-all-retries' start it only on retries — with network: true, which is the default). trace defaults to 'off', and without a running proxy route handlers never fire; Tapsmith then prints a warning at the end of the test that registered them (or, for a hook, the first test after it), naming it (see Network prerequisites). If capture was attempted and failed to start, route() throws Network capture disabled: … instead. Route handlers only see traffic Tapsmith can decrypt; hosts that are configured for passthrough, or dynamically tunneled because an HTTP/2-capable client rejects the generated MITM certificate, cannot be matched.

See also: device.unroute(), device.unrouteAll().

• url: string | RegExp | ((url: URL) => boolean) — URL pattern (glob), regex, or predicate
• handler: (route: Route) => Promise<void> | void — handler that decides how to handle the request
• options.times?: number — how many times to intercept (then auto-remove)

await device.route('**/api/posts*', async (route) => {
  await route.fulfill({ json: [{ id: 1, title: 'Mocked' }] })
})

A route lasts as long as the scope that registered it: one registered in a test, beforeEach, afterEach or a test fixture is removed when the test ends; one registered in beforeAll (or afterAll) stays for every test of its describe block, or of the file at the top level, and is removed when that block ends. See Route lifetime.

device.unroute(url, handler?): Promise<void>

Remove a previously registered route handler. If handler is omitted, all handlers for the pattern are removed.

device.unrouteAll(): Promise<void>

Remove all registered route handlers, including those registered in beforeAll.

device.waitForRequest(urlOrPredicate, options?): Promise<TapsmithRequest>

Wait for a network request matching the pattern. Requires network tracing to be enabled (same prerequisite as device.route()).

• urlOrPredicate: string | RegExp | ((request: TapsmithRequest) => boolean)
• options.timeout?: number — timeout in ms (default: device timeout)

device.waitForResponse(urlOrPredicate, options?): Promise<NetworkResponseEventData>

Wait for a network response matching the pattern. Requires network tracing to be enabled (same prerequisite as device.route()).

A waiter belongs to the test that creates it. If the test ends first (say, a step before await fails), the waiter ends with it and can’t time out later in another test. A waiter that times out while its test is still running, without being awaited, fails that test. Waiters created in a beforeAll hook last until the file ends.

device.on(event, handler): void

Subscribe to network events: 'request' or 'response'.

device.on('request', (req) => console.log(req.url))
device.on('response', (resp) => console.log(resp.status))

device.off(event, handler): void

Unsubscribe from network events.

Route

The Route object is passed to route handlers. It provides methods to decide how to handle the intercepted request.

route.request(): TapsmithRequest

Returns the intercepted request.

route.abort(errorCode?): Promise<void>

Abort the request. Optional errorCode: 'connectionrefused', 'connectionreset', 'timedout'.

route.continue(overrides?): Promise<void>

Continue the request to the server with optional modifications.

• overrides.url?: string — override the request URL. Supports both same-origin path changes (e.g. /v2/posts) and cross-origin redirection (e.g. https://staging.example.com/api/posts). When the host differs, the Host header is automatically updated.
• overrides.method?: string — override the HTTP method
• overrides.headers?: Record<string, string> — override headers
• overrides.postData?: string | Buffer — override request body

route.fulfill(options?): Promise<void>

Return a mock response without contacting the server.

• options.status?: number — HTTP status code (default: 200)
• options.headers?: Record<string, string> — response headers
• options.body?: string | Buffer — response body
• options.contentType?: string — content-type header
• options.json?: unknown — convenience: JSON-serializes and sets content-type
• options.path?: string — read body from a file

route.fetch(overrides?): Promise<FetchedAPIResponse>

Fetch the actual response from the server. Returns a FetchedAPIResponse that you can inspect and modify before calling route.fulfill().

• overrides.url?: string — override the URL to fetch from (supports cross-origin, same as route.continue())
• overrides.method?: string — override the HTTP method
• overrides.headers?: Record<string, string> — override headers
• overrides.postData?: string | Buffer — override request body

await device.route('**/api/users/*', async (route) => {
  const response = await route.fetch()
  const data = response.json()
  data.name = 'Modified'
  await route.fulfill({ json: data })
})

TapsmithRequest

Properties: method, url, headers, postData, isHttps.

FetchedAPIResponse

Returned by route.fetch(). Properties: status, headers. Methods: body(), text(), json().