Skip to main content

respond

Overview​

Overrides responses to matching requests while the rule is active. BiDi still sends the original request to the server; this is not a way to prevent request side effects.

Usage​

mock.respond(overwrites, params)

Command parameters​

ParameterBiDiClassic/CDP
overwritesBody string or JSON object/array. Body callbacks are not supported.String, JSON or function receiving the request entry and client. The function may return a Promise.
params.headersResponse-header object or synchronous function of the response event. Replaces the header set.Object or function. Adds to original headers.
params.statusCodeNumber or synchronous function of the response event.Number or function.
params.cookiesWebDriver-format Cookie[] or synchronous function of the response event.Not supported by this implementation.
params.fetchResponseNot applied: overrides happen at the response stage, so the request reaches the server.Boolean, default true. false overrides before the original body is fetched.

For params.cookies, pass a string value and the expiry field (Unix time in seconds), not a BiDi value object and expires. The library converts the cookies to BiDi itself.

The parameter is headers, not header. Metadata defaults to the original values when not overridden.

Limitations​

In BiDi, a file path or URL string remains response text. It does not read a file or redirect the request; use redirect to change the URL. In Classic/CDP, an existing path is read as a local file, while an HTTP(S) URL string creates a redirect response.

Do not mix persistent and one-shot rules without accounting for the implementation. In BiDi, respond() replaces the response queue with a persistent rule. respondOnce() removes a persistent rule and appends to other one-shot rules. CDP appends rules, so an earlier persistent rule can mask later ones.

Result​

BiDi synchronously returns the same mock. Classic/CDP has no useful return value. Call await mock.restore() to remove overrides and the interceptor.

Example​

The example uses Chrome with WebDriver BiDi. Point baseUrl to a test HTTP server: / serves an HTML page, and /api/items returns JSON with source: "original" and status 200. The explicit event subscription supports new sessions in the same worker in WDIO 9.6.2.

const assert = require("node:assert/strict");

it("mock.respond: replace response data and metadata in BiDi", async ({ browser }) => {
    await browser.url("/");
    await browser.sessionSubscribe({
        events: ["network.beforeRequestSent", "network.responseStarted"],
    });
    const mock = await browser.mock("/api/items");
    try {
        mock.respond(
            { source: "mocked" },
            {
                statusCode: 201,
                headers: { "content-type": "application/json", "x-example": "response" },
                cookies: [
                    {
                        name: "mock-example",
                        value: "ready",
                        domain: new URL(await browser.getUrl()).hostname,
                        path: "/",
                    },
                ],
            },
        );
        for (let i = 0; i < 2; i++) {
            const result = await browser.execute(async () => {
                const response = await fetch("/api/items", { cache: "no-store" });
                return {
                    status: response.status,
                    header: response.headers.get("x-example"),
                    body: await response.json(),
                };
            });
            assert.deepEqual(result, {
                status: 201,
                header: "response",
                body: { source: "mocked" },
            });
        }
    } finally {
        await mock.restore();
    }
});

References​

This page draws on the original WebdriverIO article.

On this page