@ingenioz-it/caits 0.0.0-stage → 0.5.0

package/src/messaging/Controller.ts

@@ -0,0 +1,109 @@
+import type { Input } from "./Input.js";
+import type { MessageBus } from "./MessageBus.js";
+import { reportToConsole, type ReportError } from "./ReportError.js";
+
+export class InvalidInputError extends Error {
+  constructor(message: string, readonly details?: unknown) {
+    super(message);
+    this.name = "InvalidInputError";
+  }
+}
+
+export class MalformedBodyError extends InvalidInputError {}
+
+export class UnsupportedMediaTypeError extends InvalidInputError {}
+
+export class BodyTooLargeError extends InvalidInputError {}
+
+/** The largest body that readBody reads by default, in bytes: 1 MB. */
+export const MAX_BODY_SIZE = 1024 * 1024;
+
+/**
+ * A JSON media type, in any case: application/json, or a type with the suffix +json (application/merge-patch+json). Parameters can
+ * follow, after a ";". A parameter is not the type: a browser sends `text/plain;x+json` from any site, as text/plain.
+ */
+const JSON_MEDIA_TYPE = /^(?:application\/json|[^\s/]+\/[^\s/;]+\+json)\s*(?:;|$)/i;
+
+/**
+ * The JSON of the body. The request must say that its body is JSON: content-type application/json, or a type with the suffix +json.
+ * A browser sends a body of another type (text/plain, a form) from any site, without asking the server first: such a request cannot
+ * change the data of the app. The body must not be larger than `maxSize` bytes (MAX_BODY_SIZE, 1 MB, by default): the rest of a
+ * larger body is not read. The request stays readable.
+ * @throws {UnsupportedMediaTypeError} when the request does not say that its body is JSON: the Controller answers 415.
+ * @throws {BodyTooLargeError} when the body is larger than `maxSize`: the Controller answers 413.
+ * @throws {MalformedBodyError} when the body is not JSON: the Controller answers 400.
+ */
+export async function readBody(request: Request, maxSize = MAX_BODY_SIZE): Promise<unknown> {
+  const contentType = request.headers.get("content-type");
+  if (!contentType?.match(JSON_MEDIA_TYPE)) throw new UnsupportedMediaTypeError("The content type must be application/json");
+  const text = await textOf(request.clone(), maxSize);
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new MalformedBodyError("Invalid JSON");
+  }
+}
+
+/** The text of the body, read chunk by chunk: the reading stops at the first chunk after `maxSize` bytes. */
+async function textOf(request: Request, maxSize: number): Promise<string> {
+  const decoder = new TextDecoder();
+  let text = "";
+  let size = 0;
+  const reader = request.body?.getReader();
+  for (let chunk = await reader?.read(); chunk && !chunk.done; chunk = await reader?.read()) {
+    size += chunk.value.byteLength;
+    if (size > maxSize) throw new BodyTooLargeError(`The body is larger than ${maxSize} bytes`);
+    text += decoder.decode(chunk.value, { stream: true });
+  }
+  return text + decoder.decode();
+}
+
+const problemType = (slug: string) => `urn:caits:problem:${slug}`;
+
+export function problem(status: number, slug: string, title: string, detail?: string, extensions: Record<string, unknown> = {}): Response {
+  return new Response(JSON.stringify({ type: problemType(slug), title, status, detail, ...extensions }), {
+    status,
+    headers: { "content-type": "application/problem+json" }
+  });
+}
+
+/** Turns a request into an input DTO, sends it to the message bus of the request, and turns the output or the error into a response. */
+export abstract class Controller<Dto extends Input<Output>, Output> {
+  constructor(private bus: MessageBus, private reportError: ReportError = reportToConsole) {}
+
+  protected abstract toDto(request: Request): Dto | Promise<Dto>;
+
+  protected abstract toResponse(output: Output, request: Request): Response | Promise<Response>;
+
+  /**
+   * The response to an error of the request or of the application. A body that does not say it is JSON is a 415, a body too large a 413,
+   * a body that is not JSON a 400, a body that toDto refuses a 422 with its issues, and any other error is an internal server error. A
+   * controller answers its own errors first, then calls super.
+   */
+  protected toErrorResponse(error: unknown, _request: Request): Response | Promise<Response> {
+    if (error instanceof UnsupportedMediaTypeError) return problem(415, "unsupported-media-type", "Unsupported media type", error.message);
+    if (error instanceof BodyTooLargeError) return problem(413, "request-body-too-large", "Request body too large", error.message);
+    if (error instanceof MalformedBodyError) return problem(400, "invalid-request-body", "Invalid request body", error.message);
+    if (error instanceof InvalidInputError) return problem(422, "invalid-request-body", "Invalid request body", error.message, { issues: error.details });
+    return this.internalServerError(error);
+  }
+
+  async handle(request: Request): Promise<Response> {
+    try {
+      let output: Output;
+      try {
+        output = await this.bus.send(await this.toDto(request));
+      } catch (error) {
+        return await this.toErrorResponse(error, request);
+      }
+      return await this.toResponse(output, request);
+    } catch (failure) {
+      return this.internalServerError(failure);
+    }
+  }
+
+  private internalServerError(error: unknown): Response {
+    this.reportError(error);
+    return problem(500, "internal-server-error", "Internal server error");
+  }
+}

package/src/messaging/EventPublisher.ts

@@ -0,0 +1,12 @@
+import { Token } from "../Token.js";
+
+/**
+ * Publishes the events of a context: the handlers get it, and the views of the frontend. It cannot subscribe, and it gives nothing back.
+ * In the backend, the events go later to the other contexts, through the context map. In the frontend, they go at once to the store of
+ * the same context.
+ */
+export interface EventPublisher<E> {
+  publish(event: E): void;
+}
+
+export const EventPublisher = new Token<EventPublisher<unknown>>();

package/src/messaging/EventSubscriber.ts

@@ -0,0 +1,4 @@
+/** Subscribes to the events of a frontend context: the store gets it. It cannot publish. */
+export interface EventSubscriber<E> {
+  subscribe(listener: (event: E) => void): () => void;
+}

package/src/messaging/FrontendEventBus.ts

@@ -0,0 +1,38 @@
+import type { EventPublisher } from "./EventPublisher.js";
+import type { EventSubscriber } from "./EventSubscriber.js";
+import { reportToConsole, type ReportError } from "./ReportError.js";
+
+/**
+ * The event bus of a frontend context. Delivers each event to every subscriber. An event published during a delivery waits for its turn:
+ * every subscriber receives the events in the order they were published. Only the kernel builds it: the others get it as an
+ * EventPublisher or as an EventSubscriber.
+ */
+export class FrontendEventBus<E> implements EventPublisher<E>, EventSubscriber<E> {
+  private listeners = new Set<(event: E) => void>();
+  private waiting: E[] = [];
+  private delivering = false;
+
+  constructor(private reportError: ReportError = reportToConsole) {}
+
+  publish(event: E): void {
+    this.waiting.push(event);
+    if (this.delivering) return;
+    this.delivering = true;
+    try {
+      while (this.waiting.length > 0) this.deliver(this.waiting.shift() as E);
+    } finally {
+      this.delivering = false;
+    }
+  }
+
+  subscribe(listener: (event: E) => void): () => void {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+
+  private deliver(event: E): void {
+    for (const listener of [...this.listeners]) {
+      try { listener(event); } catch (error) { this.reportError(error); }
+    }
+  }
+}

package/src/messaging/InProcessMessageBus.ts

@@ -0,0 +1,35 @@
+import type { Input } from "./Input.js";
+import type { MessageBus } from "./MessageBus.js";
+
+export type OutputOf<I> = I extends Input<infer Output> ? Output : never;
+type InputClass<I extends Input<unknown>> = abstract new (...args: never[]) => I;
+
+export class UnknownInputError extends Error {
+  constructor(readonly inputName: string) {
+    super(`No handler subscribes to ${inputName}`);
+    this.name = "UnknownInputError";
+  }
+}
+
+export class DuplicateHandlerError extends Error {
+  constructor(readonly inputName: string) {
+    super(`A handler already subscribes to ${inputName}`);
+    this.name = "DuplicateHandlerError";
+  }
+}
+
+/** The message bus of one context, in the process: each handler subscribes to the class of the input DTO it handles. */
+export class InProcessMessageBus implements MessageBus {
+  private handlers = new Map<unknown, (input: never) => unknown>();
+
+  subscribe<I extends Input<unknown>>(input: InputClass<I>, handler: (input: I) => OutputOf<I> | Promise<OutputOf<I>>): void {
+    if (this.handlers.has(input)) throw new DuplicateHandlerError(input.name);
+    this.handlers.set(input, handler);
+  }
+
+  async send<Output>(input: Input<Output>): Promise<Output> {
+    const handler = this.handlers.get(input.constructor);
+    if (!handler) throw new UnknownInputError(input.constructor.name);
+    return (await handler(input as never)) as Output;
+  }
+}

package/src/messaging/Input.ts

@@ -0,0 +1,4 @@
+/** An input DTO of a context, a command or a query. `Output` is the DTO its handler answers with. */
+export abstract class Input<Output> {
+  declare protected readonly output?: Output;
+}

package/src/messaging/MessageBus.ts

@@ -0,0 +1,12 @@
+import { Token } from "../Token.js";
+import type { Input } from "./Input.js";
+
+/**
+ * Where a controller or a store sends an input DTO: the message bus gives it to the handler of its class, and gives back the output of
+ * the handler.
+ */
+export interface MessageBus {
+  send<Output>(input: Input<Output>): Promise<Output>;
+}
+
+export const MessageBus = new Token<MessageBus>();

package/src/messaging/ReportError.ts

@@ -0,0 +1,9 @@
+import { Token } from "../Token.js";
+
+/** Reports a failure that nobody waits for: a reaction to an event, or an error that a controller hides from its client. */
+export type ReportError = (error: unknown) => void;
+
+export const ReportError = new Token<ReportError>();
+
+/** Where a failure goes when nobody says where: the console. */
+export const reportToConsole: ReportError = error => { console.error(error); };

package/src/state/Loadable.ts

@@ -0,0 +1,13 @@
+/** Data that a view asked for: nobody asked yet, the answer is on its way, or it came back loaded or failed. */
+export type Loadable<T> =
+  | { status: "idle" }
+  | { status: "loading" }
+  | { status: "loaded"; data: T }
+  | { status: "failed"; message: string };
+
+export type Settled<T> = Extract<Loadable<T>, { status: "loaded" | "failed" }>;
+
+/** The answer, loaded or failed; undefined while nobody asked or the answer is on its way. */
+export function settled<T>(loadable: Loadable<T>): Settled<T> | undefined {
+  return loadable.status === "loaded" || loadable.status === "failed" ? loadable : undefined;
+}

package/src/state/createStore.ts

@@ -0,0 +1,45 @@
+import type { EventSubscriber } from "../messaging/EventSubscriber.js";
+import type { Input } from "../messaging/Input.js";
+import type { MessageBus } from "../messaging/MessageBus.js";
+import { reportToConsole, type ReportError } from "../messaging/ReportError.js";
+
+/** How the store of a frontend context reacts to each event of its event bus. */
+export interface StoreDefinition<S, E> {
+  initialState: S;
+  /** The state after the event. */
+  reduce(state: S, event: E): S;
+  /** The input DTO that the event asks the store to send to the message bus, or undefined. It reads the state before the event. */
+  send(state: S, event: E): Input<unknown> | undefined;
+}
+
+export interface Store<S> {
+  getState(): S;
+  subscribe(listener: (state: S) => void): () => void;
+  subscriberCount(): number;
+}
+
+export type StoreLinks<E> = {
+  events: EventSubscriber<E>;
+  bus: MessageBus;
+  reportError?: ReportError;
+};
+
+/** The store receives every event of the event bus: it keeps the state that the views subscribe to, and sends the input DTOs that the events ask for. */
+export function createStore<S, E>(definition: StoreDefinition<S, E>, { events, bus, reportError = reportToConsole }: StoreLinks<E>): Store<S> {
+  let state = definition.initialState;
+  const listeners = new Set<(state: S) => void>();
+  events.subscribe(event => {
+    const input = definition.send(state, event);
+    state = definition.reduce(state, event);
+    for (const listener of [...listeners]) listener(state);
+    if (input) bus.send(input).catch(reportError);
+  });
+  return {
+    getState: () => state,
+    subscriberCount: () => listeners.size,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => { listeners.delete(listener); };
+    }
+  };
+}

package/src/state/follow.ts

@@ -0,0 +1,7 @@
+import type { Store } from "./createStore.js";
+
+/** A view follows the store: it shows what the current state presents, then what each new state presents, until it calls the returned stop. */
+export function follow<S, V>(store: Store<S>, present: (state: S) => V, show: (view: V) => void): () => void {
+  show(present(store.getState()));
+  return store.subscribe(state => { show(present(state)); });
+}

package/src/state/request.ts

@@ -0,0 +1,21 @@
+import type { EventPublisher } from "../messaging/EventPublisher.js";
+import type { Store } from "./createStore.js";
+
+/** What a view holds of a frontend context: the EventPublisher it publishes on, and the store it subscribes to. */
+export interface Frontend<S, E> {
+  events: EventPublisher<E>;
+  store: Store<S>;
+}
+
+/** A view asks for something: it publishes the event, then waits for the first state in which `answer` finds the answer. */
+export function request<S, E, T>({ events, store }: Frontend<S, E>, event: E, answer: (state: S) => T | undefined): Promise<T> {
+  return new Promise(resolve => {
+    const stop = store.subscribe(state => {
+      const found = answer(state);
+      if (found === undefined) return;
+      stop();
+      resolve(found);
+    });
+    events.publish(event);
+  });
+}

package/src/testing/backend/application.ts

@@ -0,0 +1,12 @@
+import { test as base } from "vitest";
+import { createTestApplication, type TestApplication } from "./applications.js";
+
+/** Everything an application test of the backend imports: the test of a use case, written as a scenario. */
+export { afterAll, afterEach, beforeAll, beforeEach, describe, expect, vi } from "vitest";
+export { applicationScenario } from "./applicationScenario.js";
+export type { TestApplication } from "./applications.js";
+
+/** A test with `app`: every context, each one alone, built from its di.ts with its test.di.ts over it. */
+export const test = base.extend<{ app: TestApplication }>({
+  app: async ({}, use) => { await use(createTestApplication()); }
+});

package/src/testing/backend/applicationScenario.ts

@@ -0,0 +1,60 @@
+import { expect } from "vitest";
+import type { DomainEvent } from "../../DomainEvent.js";
+import type { Input } from "../../messaging/Input.js";
+import type { TestApplication } from "./applications.js";
+
+type Result<Output> = { output: Output } | { error: unknown };
+
+/**
+ * An application test, written as a presentation test: the input DTO, the events the handler publishes, then the output DTO or the error
+ * that the message bus gives. The events are checked only when the test says which ones it expects.
+ */
+export class ApplicationScenario<Output> {
+  private readonly expected: DomainEvent[] = [];
+  private checksEvents = false;
+
+  constructor(private readonly app: TestApplication, private readonly dto: Input<Output>) {}
+
+  expectItToPublish(event: DomainEvent): this {
+    this.expected.push(event);
+    this.checksEvents = true;
+    return this;
+  }
+
+  expectItToPublishNothing(): this {
+    this.checksEvents = true;
+    return this;
+  }
+
+  async expectTheOutputToBe(output: Output): Promise<void> {
+    const from = this.app.published.length;
+    const result = await this.run();
+    if ("error" in result) throw result.error;
+    this.checkTheEventsFrom(from);
+    expect(result.output).toStrictEqual(output);
+  }
+
+  async expectTheErrorToBe(error: Error): Promise<void> {
+    const from = this.app.published.length;
+    const result = await this.run();
+    if (!("error" in result)) throw new Error(`The message bus gave an output instead of an error: ${JSON.stringify(result.output)}`);
+    this.checkTheEventsFrom(from);
+    expect(result.error).toStrictEqual(error);
+  }
+
+  private async run(): Promise<Result<Output>> {
+    try {
+      return { output: await this.app.send(this.dto) };
+    } catch (error) {
+      return { error };
+    }
+  }
+
+  private checkTheEventsFrom(from: number): void {
+    if (this.checksEvents) expect(this.app.published.slice(from), "the published events").toStrictEqual(this.expected);
+  }
+}
+
+export const applicationScenario = (app: TestApplication) => ({
+  givenTheDto: <Output>(dto: Input<Output>) => new ApplicationScenario(app, dto)
+});

package/src/testing/backend/applications.ts

@@ -0,0 +1,62 @@
+/// <reference path="../../virtual-modules.d.ts" />
+import { bindings as testDi } from "virtual:kernel/backend-test";
+import type { Binding } from "../../di/Container.js";
+import { createBackend } from "../../di/createBackend.js";
+import { discovered } from "../../di/discovered.js";
+import type { DomainEvent } from "../../DomainEvent.js";
+import type { Published } from "../../messaging/BackendEventBus.js";
+
+/** The test.di.ts of each context, and of shared: the bindings that replace, in tests, those that reach outside the process. */
+const testBindings: Record<string, readonly Binding[]> = Object.fromEntries(
+  Object.entries(testDi)
+    .map(([path, bindings]) => [/backend\/([^/]+)\//.exec(path)![1], bindings])
+);
+
+type EventType<E extends DomainEvent> = abstract new (...args: never[]) => E;
+
+/** The whole backend, built from the bindings of its contexts with their test.di.ts over them, and predictable ids. For the tests of the context map. */
+export function createTestBackendApplication() {
+  const reportedErrors: unknown[] = [];
+  const published: Published[] = [];
+  let eventIds = 0;
+  const backend = createBackend(discovered, {
+    replace: testBindings,
+    reportError: error => { reportedErrors.push(error); },
+    nextEventId: () => `evt-${++eventIds}`
+  });
+  backend.subscribe(event => { published.push(event); });
+
+  return {
+    ...backend,
+    reportedErrors,
+    /** Every event the contexts published, in its envelope, in the order they were published. */
+    published,
+    publishedNames: () => published.map(({ event }) => event.constructor.name),
+    publishedOf: <E extends DomainEvent>(type: EventType<E>): E[] => published.flatMap(({ event }) => event instanceof type ? [event] : [])
+  };
+}
+
+/**
+ * Every context, built from its di.ts with its test.di.ts over it, but alone: no event reaches another context. A test sends input DTOs
+ * and reads the events the handlers published.
+ */
+export function createTestApplication() {
+  const published: DomainEvent[] = [];
+  const backend = createBackend({ ...discovered, map: [] }, { replace: testBindings, reportError: () => undefined });
+  backend.subscribe(({ event }) => { published.push(event); });
+
+  return {
+    /** Sends an input DTO to the message bus of the context that handles it. */
+    send: backend.send,
+    /** The dependency with this token, built now if no handler needed it before. */
+    get: backend.get,
+    /** Gives the dependency that the app uses from now on: a test builds its own Fake, and keeps it to arrange and check it. */
+    use: backend.use,
+    /** Every event the handlers published, in the order they published them. */
+    published,
+    publishedOf: <E extends DomainEvent>(type: EventType<E>): E[] => published.flatMap(event => event instanceof type ? [event] : [])
+  };
+}
+
+export type TestBackendApplication = ReturnType<typeof createTestBackendApplication>;
+export type TestApplication = ReturnType<typeof createTestApplication>;

package/src/testing/backend/context-map.ts

@@ -0,0 +1,12 @@
+import { test as base } from "vitest";
+import { createTestBackendApplication, type TestBackendApplication } from "./applications.js";
+
+/** Everything a test of the context map imports. `test` checks the Input DTOs that the `ContextMap` gives for an Event. */
+export { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
+export { ContextMap } from "../../messaging/ContextMap.js";
+export type { TestBackendApplication } from "./applications.js";
+
+/** A test of a flow, with `app`: it connects the contexts with the context map, and uses the Fakes of the test.di.ts files. */
+export const backendTest = base.extend<{ app: TestBackendApplication }>({
+  app: async ({}, use) => { await use(createTestBackendApplication()); }
+});

package/src/testing/backend/infra.ts

@@ -0,0 +1,6 @@
+/**
+ * Everything an infra test of the backend imports: the contract of a port, and the test of each implementation that runs it.
+ * `useTempDirectories` gives empty folders to the implementations that write files.
+ */
+export { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
+export { useTempDirectories } from "../shared/tempDirectories.js";

package/src/testing/backend/integration.ts

@@ -0,0 +1,8 @@
+import { createBackend } from "../../di/createBackend.js";
+import { discovered } from "../../di/discovered.js";
+
+/** Everything an integration test imports: flows of the context map again, with the real infra implementations. */
+export { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
+
+/** The whole backend, built from the di.ts of the contexts only: the real infra implementations, as in production. */
+export const productionBackend = () => createBackend(discovered);

package/src/testing/backend/presentation.ts

@@ -0,0 +1,14 @@
+import { test as base } from "vitest";
+import { startPresentationApplication } from "./presentationApplication.js";
+
+/** Everything a presentation test of the backend imports: the test of a Controller, through its route. */
+export { afterAll, afterEach, beforeAll, beforeEach, describe, expect, vi } from "vitest";
+export { presentationScenario } from "./presentationScenario.js";
+
+/**
+ * A test with `app`: the real routes and Controllers, over a Fake MessageBus. `presentationScenario(app)` sends the Request, checks the
+ * Input DTO, gives the reply, and checks the Response.
+ */
+export const test = base.extend<{ app: ReturnType<typeof startPresentationApplication> }>({
+  app: async ({}, use) => { await use(startPresentationApplication()); }
+});

package/src/testing/backend/presentationApplication.ts

@@ -0,0 +1,25 @@
+/// <reference path="../../virtual-modules.d.ts" />
+import "virtual:marko-run/__marko-run__router.js";
+import { fetch } from "@marko/run/router";
+import { startBackend } from "../../di/backend.js";
+import { bind } from "../../di/Container.js";
+import { MessageBus } from "../../messaging/MessageBus.js";
+import { FakeMessageBus } from "../shared/FakeMessageBus.js";
+
+/** The real routes and controllers, over a bus that only records: each test says what the application answers. */
+export function startPresentationApplication() {
+  const messageBus = new FakeMessageBus();
+  const reportedErrors: unknown[] = [];
+  const reportError = (error: unknown) => { reportedErrors.push(error); };
+  startBackend({ reportError, replace: { shared: [bind(MessageBus).toValue(messageBus)] } });
+
+  return {
+    messageBus,
+    reportedErrors,
+    async fetch(request: Request): Promise<Response> {
+      const response = await fetch(request, {} as never);
+      if (!response) throw new Error(`No route answers ${request.method} ${new URL(request.url).pathname}`);
+      return response;
+    }
+  };
+}

package/src/testing/backend/presentationScenario.ts

@@ -0,0 +1,47 @@
+import { expect } from "vitest";
+import type { startPresentationApplication } from "./presentationApplication.js";
+
+type PresentationApplication = ReturnType<typeof startPresentationApplication>;
+
+export class PresentationScenario {
+  private request: Request | undefined;
+
+  constructor(private readonly app: PresentationApplication) {}
+
+  /** A request with a body sends it as JSON: a string is the text of the body as it is (`"{not json"`), any other value its JSON. */
+  givenTheRequest(method: string, path: string, body?: unknown): this {
+    this.request = new Request(`http://localhost${path}`, {
+      method,
+      ...(body === undefined ? {} : { body: typeof body === "string" ? body : JSON.stringify(body), headers: { "content-type": "application/json" } })
+    });
+    return this;
+  }
+
+  expectItToSend(message: object): this {
+    this.app.messageBus.expect(message);
+    return this;
+  }
+
+  givenTheApplicationReplies(output: unknown): this {
+    this.app.messageBus.replyToTheLast(output);
+    return this;
+  }
+
+  givenTheApplicationFails(error: Error): this {
+    this.app.messageBus.failTheLast(error);
+    return this;
+  }
+
+  async expectTheResponseToBe(status: number, body?: unknown, headers: Record<string, string> = {}): Promise<void> {
+    if (this.request === undefined) throw new Error("PresentationScenario: call givenTheRequest(...) before expectTheResponseToBe(...).");
+    const response = await this.app.fetch(this.request);
+
+    expect(response.status).toBe(status);
+    for (const [name, value] of Object.entries(headers)) expect(response.headers.get(name), `header ${name}`).toBe(value);
+    if (body === undefined) expect(await response.text()).toBe("");
+    else expect(await response.json()).toEqual(body);
+    this.app.messageBus.verify();
+  }
+}
+
+export const presentationScenario = (app: PresentationApplication): PresentationScenario => new PresentationScenario(app);

package/src/testing/frontend/application.ts

@@ -0,0 +1,12 @@
+import { test as base } from "vitest";
+import { createTestApplication, type TestApplication } from "./applications.js";
+
+/** Everything an application test of the frontend imports: the test of a use case, written as a scenario. */
+export { afterAll, afterEach, beforeAll, beforeEach, describe, expect, vi } from "vitest";
+export { applicationScenario } from "./applicationScenario.js";
+export type { TestApplication } from "./applications.js";
+
+/** A test with `app`: every context, each one alone, built from its di.ts with its test.di.ts over it. */
+export const test = base.extend<{ app: TestApplication }>({
+  app: async ({}, use) => { await use(createTestApplication()); }
+});

package/src/testing/frontend/applicationScenario.ts

@@ -0,0 +1,36 @@
+import { expect } from "vitest";
+import type { Input } from "../../messaging/Input.js";
+import type { TestApplication } from "./applications.js";
+
+/**
+ * An application test, written as in the backend: the input DTO, then the events that the handler must publish, one by one. Each of
+ * them must be among the events that the handler published, in any order: the handler can publish other events too. A handler of the
+ * frontend gives no output, thus the scenario runs when the test awaits it.
+ */
+export class ApplicationScenario implements PromiseLike<void> {
+  private readonly expected: object[] = [];
+
+  constructor(private readonly app: TestApplication, private readonly dto: Input<void>) {}
+
+  expectItToPublish(event: object): this {
+    this.expected.push(event);
+    return this;
+  }
+
+  then<Fulfilled = void, Rejected = never>(
+    onFulfilled?: ((value: void) => Fulfilled | PromiseLike<Fulfilled>) | null,
+    onRejected?: ((reason: unknown) => Rejected | PromiseLike<Rejected>) | null
+  ): Promise<Fulfilled | Rejected> {
+    return this.run().then(onFulfilled, onRejected);
+  }
+
+  private async run(): Promise<void> {
+    const from = this.app.published.length;
+    await this.app.send(this.dto);
+    expect(this.app.published.slice(from), "the published events").toEqual(expect.arrayContaining(this.expected));
+  }
+}
+
+export const applicationScenario = (app: TestApplication) => ({
+  givenTheDto: (dto: Input<void>) => new ApplicationScenario(app, dto)
+});