@askrjs/testing

Test Askr applications by passing Web Request objects directly to their fetch handler. No port is opened and no network request is made.

For browser/integration coverage of production widgets and responsive shells, see browser harness guidance. Fallback DOM tests do not replace real-browser focus and keyboard verification.

The package works with any Node test runner and includes no custom matchers. It requires Node 22.12 or newer; browser and edge runtimes are not supported.

Install

npm install --save-dev @askrjs/testing

Inject a request

import { createServerApp, json } from "@askrjs/server";
import { inject } from "@askrjs/testing";

const app = createServerApp({
  routes: [{ path: "/health", handler: () => json({ status: "ok" }) }],
});

const response = await inject(app, "/health");

expect(response).toBeInstanceOf(Response);
expect(response.status).toBe(200);
expect(await response.json()).toEqual({ status: "ok" });

inject accepts a handler function or an object with a fetch(request) method. The second argument may also be an existing Request. The target's native Response and thrown errors are returned unchanged, including streaming bodies and abort behavior.

Construct requests and clients

import { createTestClient, createTestRequest } from "@askrjs/testing";

const request = createTestRequest("/items", {
  method: "POST",
  query: { tag: ["desk", "hardware"] },
  json: { name: "keyboard" },
});

const client = createTestClient(app, {
  baseUrl: "https://example.test/api/",
  headers: { "x-test-suite": "items" },
});

const response = await client.post("items", {
  headers: { "x-test-suite": "create-item" },
  form: { enabled: true, tag: ["desk", "hardware"] },
});

The default base URL is https://askr.test/. Per-request headers override client headers. Query objects may contain arrays for repeated values. Exactly one of json, form, or body may be used; body accepts native Web API body types including FormData and streams. JSON undefined and GET/HEAD bodies are rejected.

Clients are stateless by default. Each method returns a native Response, so use the assertion library supplied by your test runner.

Opt-in cookie sessions

import { createTestClient, createTestCookieJar } from "@askrjs/testing";

const jar = createTestCookieJar();
await jar.setCookie("seed=yes; Path=/; Secure", "https://example.test/");

const client = createTestClient(app, { baseUrl: "https://example.test", cookies: jar });
await client.post("/login", { json: { email: "person@example.test" } });
const account = await client.get("/account");

const cookies = await jar.getCookies("https://example.test/account");
await jar.clear();

Use cookies: true for a private jar, or pass a jar when two clients should share a session. The jar enforces domain, host, path, secure, expiry, public-suffix, and cookie-prefix rules. It captures every Set-Cookie header, including headers from redirect responses. A cookie supplied on the request overrides a jar cookie with the same name. SameSite navigation policy is not emulated.

Redirects

Redirects are manual by default, keeping the first 3xx Response visible. Set redirect: "follow" to follow 301, 302, 303, 307, and 308 responses inside the same target, or redirect: "error" to reject them. Relative locations, standard method/body rewriting, cross-origin credential stripping, and cookies set during redirects are supported. The default limit is 10 hops and can be changed with maxRedirects.

Followed requests are sent back to the same in-process target; redirects never reach the network.

Injection boundary

inject uses the same Web Request, Response, Headers, body-stream, and abort-signal types that the Node adapter presents to an Askr application. It preserves native header normalization, repeated Set-Cookie values, streaming response bodies, thrown errors, and abort reasons. An unconsumed caller-owned Request may be injected repeatedly because each dispatch receives a clone. If a caller has already consumed that original body, construct a new Request before injecting it.

This is intentionally not a socket emulator. Unlike @askrjs/node, injection does not exercise HTTP parsing, the adapter-authenticated client-address header, socket backpressure, server timeout options, connection errors, or network timing. Response bodies remain streams but are consumed directly by the test rather than written through a Node socket. Use an actual @askrjs/node listener when those transport properties are part of the behavior under test.