Lupa

Appearance

Lupa API Reference / network / Network

Class: Network ​

Defined in: src/network/index.ts:85

The developer-facing API for network interception and mocking. Available in browser tests via the network fixture on the TestContext.

Constructors ​

Constructor ​

new Network(context): Network

Defined in: src/network/index.ts:86

Parameters ​

context ​

TestContext

Returns ​

Network

Accessors ​

bypass ​

Get Signature ​

get bypass(): typeof bypass

Defined in: src/network/index.ts:104

A sentinel value to indicate that a request should not be intercepted and should be allowed to proceed normally.

You can use this value in dynamic response handlers to selectively bypass the mock and let the request go through to the actual network.

Example ​
ts
test('bypasses network', async ({ network }) => {
  const mock = await network.mock('/api/data', () => {
    // your logic to decide whether to bypass the mock
    return network.bypass
  })
})
Returns ​

typeof bypass

error ​

Get Signature ​

get error(): typeof NetworkError

Defined in: src/network/index.ts:120

Collection of network error types which can be used to simulate network errors.

Example ​
ts
test('simulates a network connection failure', async ({ network }) => {
  const mock = await network.mock('/api/data', () => {
    return { error: network.error.ConnectionFailed }
  })
})
Returns ​

typeof NetworkError

Methods ​

ignoreCors() ​

ignoreCors(ignore?): Promise<void>

Defined in: src/network/index.ts:142

Tells the network interceptor to automatically bypass CORS rules by intercepting preflight OPTIONS requests and injecting Access-Control-Allow-Origin: * headers into any fulfilled network mock.

This setting automatically reverts at the end of the test.

Parameters ​

ignore? ​

boolean = true

Whether to ignore CORS or enforce it. Defaults to true.

Returns ​

Promise<void>

Example ​

ts
test('ignores CORS', async ({ network, assert }) => {
  await network.ignoreCors()
  const res = await fetch('https://example.com/api/data')
  assert.equal(res.headers.get('access-control-allow-origin'), '*')
})

mock() ​

Call Signature ​

mock(match, respond): Promise<NetworkInterceptor>

Defined in: src/network/index.ts:202

Registers a new network mock to intercept requests matching the provided criteria. Intercepted requests can be bypassed, stubbed with static payloads, or handled by dynamic closures.

Note: All mocks created during a test are automatically restored when the test finishes.

Parameters ​
match ​

NetworkMatch

The matching criteria (e.g. URI string or request options).

respond ​

NetworkRespondPayload | NetworkRespondDynamic

The static payload or dynamic closure used to fulfill the matched request.

Returns ​

Promise<NetworkInterceptor>

A NetworkInterceptor to manage the mock and assert against captured requests.

Example ​
ts
test('handles 500 error', async ({ network }) => {
  const mock = await network.mock('/api/users', {
    status: 500,
    body: { error: 'Internal Server Error' }
  })

  button.click()
  await mock.assert.calledOnce()
})

Call Signature ​

mock(options): Promise<NetworkInterceptor>

Defined in: src/network/index.ts:226

Registers a new network mock to intercept requests using a single configuration object. Intercepted requests can be bypassed, stubbed with static payloads, or handled by dynamic closures.

Note: All mocks created during a test are automatically restored when the test finishes.

Parameters ​
options ​

NetworkMockOptions

The configuration defining the matching criteria and response behavior.

Returns ​

Promise<NetworkInterceptor>

A NetworkInterceptor to manage the mock and assert against captured requests.

Example ​
ts
test('handles 500 error', async ({ network }) => {
  const mock = await network.mock({
    match: '/api/users',
    respond: { status: 500, body: { error: 'Internal Server Error' } }
  })

  button.click()
  await mock.assert.calledOnce()
})

setOffline() ​

setOffline(offline): Promise<void>

Defined in: src/network/index.ts:169

Toggles the offline state of the browser context.

IMPORTANT

Automatic Cleanup: Unlike emulation.setOffline(...), this method is scoped to the current test. The network offline state will automatically revert back to online mode at the end of the test.

Parameters ​

offline ​

boolean

Whether to set the network offline.

Returns ​

Promise<void>

Example ​

ts
test('simulates offline behavior', async ({ network }) => {
  await network.setOffline(true)
  // verify application handles network failure...
})