@client-compose/client 0.3.0 → 0.4.0

package/README.md

@@ -66,6 +66,25 @@ Props aren't validated at runtime; generate types with
 [`@client-compose/codegen`](https://www.npmjs.com/package/@client-compose/codegen) to keep them in
 sync with the composer.
 
+## Testing
+
+`@client-compose/client/testing` is a fake composer for tests, with no test framework of its own.
+`createFakeGateway` answers screen and action requests from handlers and records them; pass its
+`fetch` to the client. Build responses with `island`, `islandError`, `screen`, `screenError`,
+`actionOk`, `actionError` and `actionFailure`, typed by the generated descriptors.
+
+```ts
+import { actionError, createFakeGateway } from "@client-compose/client/testing";
+
+const gateway = createFakeGateway({
+  actions: { follow: () => actionError(FollowUserV1, { code: "blocked" }) },
+});
+const res = await callAction(baseUrl, FollowUserV1, { userId }, { client, fetch: gateway.fetch });
+assert.equal(gateway.actionRequests()[0].input.userId, userId);
+```
+
+For React, `@client-compose/react/testing` adds a provider config built around it.
+
 ## Links
 
 - [Protocol spec](https://github.com/client-compose/client-compose/blob/main/spec/PROTOCOL.md)

package/dist/testing.d.ts

@@ -0,0 +1,61 @@
+import { type ActionDescriptor, type ActionEffects, type Capabilities, type ClientContext, type DeclaredError, type IslandDescriptor, type IslandEntry, type IslandError, type ScreenMeta } from "@client-compose/protocol";
+/** A response for the fake composer to send. */
+export interface FakeResponse {
+    status: number;
+    body: unknown;
+}
+/** A request the fake composer received. */
+export interface RecordedRequest {
+    url: string;
+    method: string;
+    /** Header names are lower case. */
+    headers: Record<string, string>;
+    /** The JSON body, parsed; or the raw body when it isn't JSON (e.g. a multipart upload). */
+    body: unknown;
+}
+export interface RecordedScreenRequest extends RecordedRequest {
+    screen: string;
+    params: Record<string, string>;
+    client: ClientContext | undefined;
+    islands: Capabilities;
+}
+export interface RecordedActionRequest extends RecordedRequest {
+    action: string;
+    version: number;
+    input: unknown;
+    client: ClientContext | undefined;
+    idempotencyKey: string | undefined;
+}
+export interface FakeGatewayHandlers {
+    /** By screen id. */
+    screens?: Record<string, (request: RecordedScreenRequest) => FakeResponse>;
+    /** By action name. */
+    actions?: Record<string, (request: RecordedActionRequest) => FakeResponse>;
+    /** Anything else, e.g. uploads to storage: return undefined to leave a request to the others. */
+    other?: (request: RecordedRequest) => FakeResponse | undefined;
+}
+export interface FakeGateway {
+    /** Use as the client's `fetch`. Requests without a handler reject, failing the test. */
+    fetch: typeof fetch;
+    /** Every request received, in order. */
+    requests: RecordedRequest[];
+    screenRequests(): RecordedScreenRequest[];
+    actionRequests(): RecordedActionRequest[];
+}
+/** A composer whose screens and actions are the handlers given. */
+export declare function createFakeGateway(handlers?: FakeGatewayHandlers): FakeGateway;
+/** An island in a screen response, typed by its generated descriptor. */
+export declare function island<P>(key: string, descriptor: IslandDescriptor<P>, props: P): IslandEntry<P>;
+/** An island that failed on the composer (spec §3.4). */
+export declare function islandError(key: string, descriptor: IslandDescriptor<unknown>, error: IslandError): IslandEntry;
+/** A screen response. */
+export declare function screen(id: string, islands: IslandEntry<unknown>[], meta?: ScreenMeta): FakeResponse;
+/** A screen request that fails, e.g. `screenError(404, "not_found")` or `screenError(401, "unauthenticated")`. */
+export declare function screenError(status: number, code: string): FakeResponse;
+/** An action that succeeded, with its result typed by the descriptor. */
+export declare function actionOk<I, R, E extends DeclaredError>(action: ActionDescriptor<I, R, E>, result: R, effects?: ActionEffects): FakeResponse;
+/** An action that ended with one of its declared errors. */
+export declare function actionError<I, R, E extends DeclaredError>(action: ActionDescriptor<I, R, E>, error: E): FakeResponse;
+/** An action the composer didn't perform, e.g. `actionFailure(401, "unauthenticated")` (spec §5.4). */
+export declare function actionFailure(status: number, code: string): FakeResponse;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAUA,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,0BAA0B,CAAC;AAElC,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAED,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,2FAA2F;IAC3F,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC;IAClC,OAAO,EAAE,YAAY,CAAC;CACvB;AAED,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC;IAClC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,oBAAoB;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,YAAY,CAAC,CAAC;IAC3E,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,YAAY,CAAC,CAAC;IAC3E,iGAAiG;IACjG,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,YAAY,GAAG,SAAS,CAAC;CAChE;AAED,MAAM,WAAW,WAAW;IAC1B,wFAAwF;IACxF,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,wCAAwC;IACxC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,cAAc,IAAI,qBAAqB,EAAE,CAAC;IAC1C,cAAc,IAAI,qBAAqB,EAAE,CAAC;CAC3C;AA6ED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,QAAQ,GAAE,mBAAwB,GAAG,WAAW,CA2BjF;AAID,yEAAyE;AACzE,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAEhG;AAED,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,WAAW,GAAG,WAAW,CAE/G;AAED,yBAAyB;AACzB,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,YAAY,CAEnG;AAED,kHAAkH;AAClH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAEtE;AAED,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,aAAa,EACpD,MAAM,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjC,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,aAAa,GACtB,YAAY,CAGd;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,aAAa,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,YAAY,CAGpH;AAED,uGAAuG;AACvG,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAExE"}

package/dist/testing.js

@@ -0,0 +1,143 @@
+// Test helpers for apps built on Client Compose: a fake composer that answers screen and action
+// requests from handlers and records them, and builders for the responses it returns. No test
+// framework of its own, so it works with node:test, Jest, Vitest, Playwright and others.
+//
+//     const gateway = createFakeGateway({
+//       screens: { profile: () => screen("profile", [island("header", ProfileHeaderV1, { name: "Ada" })]) },
+//       actions: { follow: () => actionOk(FollowUserV1, { followers: 8 }) },
+//     });
+//     // pass gateway.fetch as the client's fetch, then assert on gateway.actionRequests()
+import { PROTOCOL_VERSION, } from "@client-compose/protocol";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function strings(value) {
+    if (!isRecord(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter((e) => typeof e[1] === "string"));
+}
+function capabilities(value) {
+    if (!isRecord(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).map(([type, versions]) => [
+        type,
+        Array.isArray(versions) ? versions.filter((v) => typeof v === "number") : [],
+    ]));
+}
+function clientContext(value) {
+    if (!isRecord(value) || typeof value.platform !== "string" || typeof value.appVersion !== "string")
+        return undefined;
+    return { ...value, platform: value.platform, appVersion: value.appVersion };
+}
+function parseBody(body) {
+    if (typeof body !== "string")
+        return body;
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return body;
+    }
+}
+function urlOf(input) {
+    if (typeof input === "string")
+        return input;
+    return input instanceof URL ? input.href : input.url;
+}
+function headersOf(init) {
+    const out = {};
+    new Headers(init).forEach((value, name) => (out[name] = value));
+    return out;
+}
+function asScreenRequest(request) {
+    const { body } = request;
+    if (!request.url.includes("/screens/") || !isRecord(body) || typeof body.screen !== "string")
+        return undefined;
+    return {
+        ...request,
+        screen: body.screen,
+        params: strings(body.params),
+        client: clientContext(body.client),
+        islands: capabilities(body.islands),
+    };
+}
+function asActionRequest(request) {
+    const { body } = request;
+    if (!request.url.includes("/actions/") || !isRecord(body) || typeof body.action !== "string")
+        return undefined;
+    return {
+        ...request,
+        action: body.action,
+        version: typeof body.version === "number" ? body.version : 0,
+        input: body.input,
+        client: clientContext(body.client),
+        idempotencyKey: typeof body.idempotencyKey === "string" ? body.idempotencyKey : undefined,
+    };
+}
+function respond(response) {
+    return new Response(JSON.stringify(response.body), {
+        status: response.status,
+        headers: { "content-type": "application/json" },
+    });
+}
+/** A composer whose screens and actions are the handlers given. */
+export function createFakeGateway(handlers = {}) {
+    const requests = [];
+    async function fakeFetch(input, init) {
+        const request = {
+            url: urlOf(input),
+            method: init?.method ?? "GET",
+            headers: headersOf(init?.headers),
+            body: parseBody(init?.body),
+        };
+        requests.push(request);
+        const other = handlers.other?.(request);
+        if (other)
+            return respond(other);
+        const screenRequest = asScreenRequest(request);
+        const screenHandler = screenRequest && handlers.screens?.[screenRequest.screen];
+        if (screenRequest && screenHandler)
+            return respond(screenHandler(screenRequest));
+        const actionRequest = asActionRequest(request);
+        const actionHandler = actionRequest && handlers.actions?.[actionRequest.action];
+        if (actionRequest && actionHandler)
+            return respond(actionHandler(actionRequest));
+        throw new Error(`fake gateway: no handler for ${request.method} ${request.url} ${JSON.stringify(request.body)}`);
+    }
+    return {
+        fetch: fakeFetch,
+        requests,
+        screenRequests: () => requests.flatMap((r) => asScreenRequest(r) ?? []),
+        actionRequests: () => requests.flatMap((r) => asActionRequest(r) ?? []),
+    };
+}
+// ---- Responses ----
+/** An island in a screen response, typed by its generated descriptor. */
+export function island(key, descriptor, props) {
+    return { key, type: descriptor.type, version: descriptor.version, status: "ok", props };
+}
+/** An island that failed on the composer (spec §3.4). */
+export function islandError(key, descriptor, error) {
+    return { key, type: descriptor.type, version: descriptor.version, status: "error", error };
+}
+/** A screen response. */
+export function screen(id, islands, meta) {
+    return { status: 200, body: { protocol: PROTOCOL_VERSION, screen: id, islands, ...(meta && { meta }) } };
+}
+/** A screen request that fails, e.g. `screenError(404, "not_found")` or `screenError(401, "unauthenticated")`. */
+export function screenError(status, code) {
+    return { status, body: { protocol: PROTOCOL_VERSION, error: { code } } };
+}
+/** An action that succeeded, with its result typed by the descriptor. */
+export function actionOk(action, result, effects) {
+    const base = { protocol: PROTOCOL_VERSION, action: action.action, version: action.version };
+    return { status: 200, body: { ...base, status: "ok", result, ...(effects && { effects }) } };
+}
+/** An action that ended with one of its declared errors. */
+export function actionError(action, error) {
+    const base = { protocol: PROTOCOL_VERSION, action: action.action, version: action.version };
+    return { status: 200, body: { ...base, status: "error", error } };
+}
+/** An action the composer didn't perform, e.g. `actionFailure(401, "unauthenticated")` (spec §5.4). */
+export function actionFailure(status, code) {
+    return { status, body: { protocol: PROTOCOL_VERSION, error: { code } } };
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@client-compose/client",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Framework-agnostic Client Compose client: island registry, screen requests and render planning.",
   "keywords": [
     "client-compose",
@@ -26,6 +26,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [

package/src/testing.ts

@@ -0,0 +1,219 @@
+// Test helpers for apps built on Client Compose: a fake composer that answers screen and action
+// requests from handlers and records them, and builders for the responses it returns. No test
+// framework of its own, so it works with node:test, Jest, Vitest, Playwright and others.
+//
+//     const gateway = createFakeGateway({
+//       screens: { profile: () => screen("profile", [island("header", ProfileHeaderV1, { name: "Ada" })]) },
+//       actions: { follow: () => actionOk(FollowUserV1, { followers: 8 }) },
+//     });
+//     // pass gateway.fetch as the client's fetch, then assert on gateway.actionRequests()
+
+import {
+  PROTOCOL_VERSION,
+  type ActionDescriptor,
+  type ActionEffects,
+  type Capabilities,
+  type ClientContext,
+  type DeclaredError,
+  type IslandDescriptor,
+  type IslandEntry,
+  type IslandError,
+  type ScreenMeta,
+} from "@client-compose/protocol";
+
+/** A response for the fake composer to send. */
+export interface FakeResponse {
+  status: number;
+  body: unknown;
+}
+
+/** A request the fake composer received. */
+export interface RecordedRequest {
+  url: string;
+  method: string;
+  /** Header names are lower case. */
+  headers: Record<string, string>;
+  /** The JSON body, parsed; or the raw body when it isn't JSON (e.g. a multipart upload). */
+  body: unknown;
+}
+
+export interface RecordedScreenRequest extends RecordedRequest {
+  screen: string;
+  params: Record<string, string>;
+  client: ClientContext | undefined;
+  islands: Capabilities;
+}
+
+export interface RecordedActionRequest extends RecordedRequest {
+  action: string;
+  version: number;
+  input: unknown;
+  client: ClientContext | undefined;
+  idempotencyKey: string | undefined;
+}
+
+export interface FakeGatewayHandlers {
+  /** By screen id. */
+  screens?: Record<string, (request: RecordedScreenRequest) => FakeResponse>;
+  /** By action name. */
+  actions?: Record<string, (request: RecordedActionRequest) => FakeResponse>;
+  /** Anything else, e.g. uploads to storage: return undefined to leave a request to the others. */
+  other?: (request: RecordedRequest) => FakeResponse | undefined;
+}
+
+export interface FakeGateway {
+  /** Use as the client's `fetch`. Requests without a handler reject, failing the test. */
+  fetch: typeof fetch;
+  /** Every request received, in order. */
+  requests: RecordedRequest[];
+  screenRequests(): RecordedScreenRequest[];
+  actionRequests(): RecordedActionRequest[];
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+function strings(value: unknown): Record<string, string> {
+  if (!isRecord(value)) return {};
+  return Object.fromEntries(Object.entries(value).filter((e): e is [string, string] => typeof e[1] === "string"));
+}
+
+function capabilities(value: unknown): Capabilities {
+  if (!isRecord(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value).map(([type, versions]) => [
+      type,
+      Array.isArray(versions) ? versions.filter((v): v is number => typeof v === "number") : [],
+    ]),
+  );
+}
+
+function clientContext(value: unknown): ClientContext | undefined {
+  if (!isRecord(value) || typeof value.platform !== "string" || typeof value.appVersion !== "string") return undefined;
+  return { ...value, platform: value.platform, appVersion: value.appVersion } as ClientContext;
+}
+
+function parseBody(body: unknown): unknown {
+  if (typeof body !== "string") return body;
+  try {
+    return JSON.parse(body) as unknown;
+  } catch {
+    return body;
+  }
+}
+
+function urlOf(input: RequestInfo | URL): string {
+  if (typeof input === "string") return input;
+  return input instanceof URL ? input.href : input.url;
+}
+
+function headersOf(init: HeadersInit | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  new Headers(init).forEach((value, name) => (out[name] = value));
+  return out;
+}
+
+function asScreenRequest(request: RecordedRequest): RecordedScreenRequest | undefined {
+  const { body } = request;
+  if (!request.url.includes("/screens/") || !isRecord(body) || typeof body.screen !== "string") return undefined;
+  return {
+    ...request,
+    screen: body.screen,
+    params: strings(body.params),
+    client: clientContext(body.client),
+    islands: capabilities(body.islands),
+  };
+}
+
+function asActionRequest(request: RecordedRequest): RecordedActionRequest | undefined {
+  const { body } = request;
+  if (!request.url.includes("/actions/") || !isRecord(body) || typeof body.action !== "string") return undefined;
+  return {
+    ...request,
+    action: body.action,
+    version: typeof body.version === "number" ? body.version : 0,
+    input: body.input,
+    client: clientContext(body.client),
+    idempotencyKey: typeof body.idempotencyKey === "string" ? body.idempotencyKey : undefined,
+  };
+}
+
+function respond(response: FakeResponse): Response {
+  return new Response(JSON.stringify(response.body), {
+    status: response.status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+/** A composer whose screens and actions are the handlers given. */
+export function createFakeGateway(handlers: FakeGatewayHandlers = {}): FakeGateway {
+  const requests: RecordedRequest[] = [];
+  async function fakeFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+    const request: RecordedRequest = {
+      url: urlOf(input),
+      method: init?.method ?? "GET",
+      headers: headersOf(init?.headers),
+      body: parseBody(init?.body),
+    };
+    requests.push(request);
+
+    const other = handlers.other?.(request);
+    if (other) return respond(other);
+    const screenRequest = asScreenRequest(request);
+    const screenHandler = screenRequest && handlers.screens?.[screenRequest.screen];
+    if (screenRequest && screenHandler) return respond(screenHandler(screenRequest));
+    const actionRequest = asActionRequest(request);
+    const actionHandler = actionRequest && handlers.actions?.[actionRequest.action];
+    if (actionRequest && actionHandler) return respond(actionHandler(actionRequest));
+    throw new Error(`fake gateway: no handler for ${request.method} ${request.url} ${JSON.stringify(request.body)}`);
+  }
+  return {
+    fetch: fakeFetch,
+    requests,
+    screenRequests: () => requests.flatMap((r) => asScreenRequest(r) ?? []),
+    actionRequests: () => requests.flatMap((r) => asActionRequest(r) ?? []),
+  };
+}
+
+// ---- Responses ----
+
+/** An island in a screen response, typed by its generated descriptor. */
+export function island<P>(key: string, descriptor: IslandDescriptor<P>, props: P): IslandEntry<P> {
+  return { key, type: descriptor.type, version: descriptor.version, status: "ok", props };
+}
+
+/** An island that failed on the composer (spec §3.4). */
+export function islandError(key: string, descriptor: IslandDescriptor<unknown>, error: IslandError): IslandEntry {
+  return { key, type: descriptor.type, version: descriptor.version, status: "error", error };
+}
+
+/** A screen response. */
+export function screen(id: string, islands: IslandEntry<unknown>[], meta?: ScreenMeta): FakeResponse {
+  return { status: 200, body: { protocol: PROTOCOL_VERSION, screen: id, islands, ...(meta && { meta }) } };
+}
+
+/** A screen request that fails, e.g. `screenError(404, "not_found")` or `screenError(401, "unauthenticated")`. */
+export function screenError(status: number, code: string): FakeResponse {
+  return { status, body: { protocol: PROTOCOL_VERSION, error: { code } } };
+}
+
+/** An action that succeeded, with its result typed by the descriptor. */
+export function actionOk<I, R, E extends DeclaredError>(
+  action: ActionDescriptor<I, R, E>,
+  result: R,
+  effects?: ActionEffects,
+): FakeResponse {
+  const base = { protocol: PROTOCOL_VERSION, action: action.action, version: action.version };
+  return { status: 200, body: { ...base, status: "ok", result, ...(effects && { effects }) } };
+}
+
+/** An action that ended with one of its declared errors. */
+export function actionError<I, R, E extends DeclaredError>(action: ActionDescriptor<I, R, E>, error: E): FakeResponse {
+  const base = { protocol: PROTOCOL_VERSION, action: action.action, version: action.version };
+  return { status: 200, body: { ...base, status: "error", error } };
+}
+
+/** An action the composer didn't perform, e.g. `actionFailure(401, "unauthenticated")` (spec §5.4). */
+export function actionFailure(status: number, code: string): FakeResponse {
+  return { status, body: { protocol: PROTOCOL_VERSION, error: { code } } };
+}