Lupa API Reference / network / NetworkInterceptor
Interface: NetworkInterceptor
Defined in: src/network/network_interceptor.ts:8
An active network interception object. Provides APIs to assert against captured traffic and manage the mock's lifecycle.
Properties
assert
assert:
NetworkAssert
Defined in: src/network/network_interceptor.ts:148
The dedicated assertion API for this network mock. Contains robust, built-in polling methods to prevent flakiness during asynchronous UI updates.
Example
await mock.assert.calledOnceWith({ method: 'POST' })requests
requests:
CapturedRequest[] =[]
Defined in: src/network/network_interceptor.ts:19
The complete chronological list of requests captured by this specific interceptor. This is the raw array used internally by assert methods.
Example
const requests = mock.requests
console.log(`Intercepted ${requests.length} requests`)Methods
firstRequest()
firstRequest():
CapturedRequest|undefined
Defined in: src/network/network_interceptor.ts:113
Retrieves the very first captured request.
Returns
CapturedRequest | undefined
The first CapturedRequest, or undefined if no requests have been intercepted.
Remarks
This is a strictly synchronous method. Make sure to await a network assertion first to ensure the network state has settled before reading this value.
Example
await locator('.load-app').click()
await mock.assert.called() // Wait for network
const initialLoadReq = mock.firstRequest()
assert.equal(initialLoadReq?.query.page, '1')Use When
Inspecting initial load behaviors, such as the first polling request or an application configuration fetch.
getRequests()
getRequests():
CapturedRequest[]
Defined in: src/network/network_interceptor.ts:65
Retrieves a shallow copy of all tracked requests captured by this interceptor.
Returns
An array of CapturedRequest objects in the order they were intercepted.
Remarks
This is a strictly synchronous method. If called immediately after a UI interaction that triggers a background network request, it may return an incomplete array. Always await a network assertion (e.g. mock.assert.called()) to allow the network to settle before calling this method.
Example
await locator('button').click()
await mock.assert.calledOnce() // 1. Wait for request to settle
const requests = mock.getRequests() // 2. Safely read snapshot
assert.equal(requests[0].method, 'GET')Use When
You need to perform complex manual iterations or custom assertions across the entire request history.
lastRequest()
lastRequest():
CapturedRequest|undefined
Defined in: src/network/network_interceptor.ts:89
Retrieves the most recently captured request.
Returns
CapturedRequest | undefined
The last CapturedRequest, or undefined if no requests have been intercepted.
Remarks
This is a strictly synchronous method. If called immediately after a UI interaction, it may return undefined because the background request hasn't been processed yet. Always await a network assertion first.
Example
await locator('button[type="submit"]').click()
await mock.assert.calledOnce() // 1. Wait for request to settle
const req = mock.lastRequest() // 2. Safely read snapshot
assert.deepEqual(JSON.parse(req!.body as string), { username: 'alice' })Use When
You want to manually assert specific, deeply nested properties of a payload after a sequence of events.
restore()
restore():
Promise<void>
Defined in: src/network/network_interceptor.ts:135
Manually unregisters this mock, preventing it from intercepting future requests.
Note: Mocks are automatically restored at the end of each test by the runner's cleanup hooks. You only need to call this if you want to unregister a mock mid-test.
Returns
Promise<void>
Example
const mock = await network.mock({ match: '/api/user', respond: { status: 500 } })
await mock.assert.calledOnce()
// Stop simulating the 500 error for the rest of the test
await mock.restore()Use When
You need to test fault recovery (e.g. failing a request once, restoring the mock, and verifying the retry succeeds).