@dotpress/testing 0.0.0-stage → 2.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Renaud Guyon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# @dotpress/testing
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Testing helpers for [Dotpress](https://dotpress.dev): a test app, the adapter conformance suite, and assertions for events and mail.
+
+> 🚧 Dotpress V2 is in alpha (`2.0.0-alpha`): the API may still change before 2.0.0.
+
+## Adapter conformance suite
+
+Every Dotpress HTTP adapter must pass the conformance suite, which checks that routing, request parsing, validation, errors, middlewares and responses (including streams and Server-Sent Events) behave the same on every server.
+
+```ts
+// conformance.test.ts (run with vitest)
+import type { AddressInfo } from 'node:net'
+import { createApp } from '@dotpress/core'
+import { createHttpTarget, runConformanceSuite } from '@dotpress/testing'
+import { myAdapter } from '../src/index.js'
+
+runConformanceSuite({
+  name: 'my-adapter',
+  async setup(options) {
+    const adapter = myAdapter()
+    const app = await createApp({ ...options, adapter })
+    await app.listen(0, '127.0.0.1')
+
+    const { port } = adapter.server().address() as AddressInfo
+    return createHttpTarget(`http://127.0.0.1:${port}`, () => app.close())
+  },
+})
+```
+
+`setup()` is called once per test with the app options of the scenario. Adapters that do not listen on a port return `createFetchTarget(handle, close)`, where `handle` takes a Web `Request` and returns a `Response` (in-memory `fetch()`).
+
+### AWS Lambda
+
+`createLambdaTarget(handler, { format, close })` sends each request to a Lambda handler as a simulated event, and converts the result back: `format` is `'v1'` (API Gateway REST API), `'v2'` (HTTP API, Function URLs) or `'alb'` (Application Load Balancer, with multi-value headers). A failed invocation gets a `502` response, like API Gateway. `toLambdaEvent()` and `fromLambdaResult()` are exported for handler tests.
+
+```ts
+runConformanceSuite({
+  name: 'my-adapter (AWS Lambda)',
+  // Responses sent once complete: skips the scenarios that need incremental
+  // streaming or client disconnects.
+  bufferedResponses: true,
+  setup: async (options) => {
+    let app
+    const handler = createLambdaHandler(async () => (app = await createApp({ ...options, adapter: myAdapter() })))
+    return createLambdaTarget(handler, { format: 'v2', close: async () => app?.close() })
+  },
+})
+```
+
+## Memory logger
+
+`createMemoryLogger()` records log entries instead of printing them:
+
+```ts
+const logger = createMemoryLogger()
+await createApp({ adapter, logger })
+expect(logger.entries).toContainEqual({ level: 'error', args: [error, 'Unhandled error while processing request'] })
+```
+
+## Event assertions
+
+`expectEventEmitted(source, event, payload?, options?)` asserts that an event was emitted, and returns the last matching emission. The source is a fake event bus (`createFakeEventBus()` of `@dotpress/events`: it checks emissions like a real bus, without running listeners), or a memory transport (`createMemoryTransport()`: it only sees the events that have listeners on it).
+
+```ts
+import { createFakeEventBus } from '@dotpress/events'
+import { expectEventEmitted, expectEventNotEmitted } from '@dotpress/testing'
+
+const events = createFakeEventBus()
+await signUp(events, 'ada@example.com')
+
+expectEventEmitted(events, userCreated, { email: 'ada@example.com' })
+expectEventEmitted(events, 'user.created', undefined, { times: 1, metadata: { requestId: 'req-1' } })
+expectEventNotEmitted(events, userDeleted)
+```
+
+- `event`: the definition, or its name.
+- `payload`: objects are matched partially (like `toMatchObject()`), other values exactly; asymmetric matchers are accepted (`expect.any(String)`). Without it, any payload matches.
+- `options`: `times` (exact number of emissions; at least one by default), `metadata` (matched partially), `delay` (fake event bus only).
+
+With the Dotpress plugin, pass the fake bus to `eventsPlugin()`: `ctx.events` records into it, with the `requestId` in the metadata.
+
+## Mail assertions
+
+`expectMailSent(outbox, criteria?, options?)` asserts that a message was sent through the memory provider of the mailer (`createMemoryProvider()` of `@dotpress/mailer`), and returns the last matching message.
+
+```ts
+import { createMailer, createMemoryProvider } from '@dotpress/mailer'
+import { expectMailSent, expectNoMailSent } from '@dotpress/testing'
+
+const outbox = createMemoryProvider()
+const mailer = createMailer({ provider: outbox, from: 'noreply@example.com' })
+await signUp(mailer, 'ada@example.com')
+
+const mail = expectMailSent(outbox, { to: 'ada@example.com', template: welcomeMail, locale: 'en' })
+expect(mail.html).toContain('https://example.com/confirm')
+expectNoMailSent(outbox, { to: 'grace@example.com' })
+```
+
+- `to`, `cc`, `bcc`, `replyTo`: an address or an array of addresses, all among the recipients (any case). `from`: the address of the sender.
+- `template`: the template, or its name.
+- `subject`, `html`, `text`, `locale`, `tags`, `metadata`, `headers`, `attachments`: matched like `toMatchObject()`, with asymmetric matchers (`expect.stringContaining('invoice')`).
+- `options.times`: exact number of messages; at least one by default.
+
+Failed assertions throw an `ExpectationError` that lists what was emitted or sent.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,270 @@
+import { AppOptions, Logger, HttpAdapter, CompiledRoute, App } from '@dotpress/core';
+
+/** Error of a failed assertion, shown by the test runner. */
+declare class ExpectationError extends Error {
+    name: string;
+}
+
+/**
+ * Running application under test.
+ */
+interface ConformanceTarget {
+    /** Sends a request to the application. `path` includes the query. */
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+    /** Stops the application. */
+    close(): Promise<void>;
+}
+type ConformanceAppOptions = Omit<AppOptions, 'adapter'>;
+interface ConformanceSuiteOptions {
+    /** Adapter name, used in test titles. */
+    name: string;
+    /**
+     * Creates an app with the adapter under test and the given options, and
+     * starts it. Called once per test.
+     */
+    setup(options: ConformanceAppOptions): Promise<ConformanceTarget>;
+    /**
+     * The adapter sends responses once complete (AWS Lambda without response
+     * streaming). The scenarios that need incremental streaming or client
+     * disconnects are skipped.
+     */
+    bufferedResponses?: boolean;
+}
+/**
+ * Target for adapters listening on an HTTP port.
+ */
+declare const createHttpTarget: (baseUrl: string, close: () => Promise<void>) => ConformanceTarget;
+/**
+ * Target for adapters handling Web requests in memory (`fetch()` of the
+ * adapter, serverless handlers). `path` is relative to `http://localhost`.
+ */
+declare const createFetchTarget: (handle: (request: Request) => Promise<Response>, close: () => Promise<void>) => ConformanceTarget;
+/**
+ * Registers the adapter conformance suite (vitest). An adapter is ready
+ * when it passes every test.
+ */
+declare const runConformanceSuite: (options: ConformanceSuiteOptions) => void;
+
+/**
+ * Lambda event formats: API Gateway REST API (payload v1), HTTP API and
+ * Function URLs (payload v2), Application Load Balancer (with multi-value
+ * headers, required for repeated query keys and several cookies).
+ */
+type LambdaEventFormat = 'v1' | 'v2' | 'alb';
+interface LambdaTargetOptions {
+    format: LambdaEventFormat;
+    /** Stops the application. */
+    close: () => Promise<void>;
+    /** Client IP address of the events. Defaults to `127.0.0.1`. */
+    sourceIp?: string;
+}
+/** Lambda handler under test (`createLambdaHandler()` of an adapter). */
+type LambdaTestHandler = (event: never, context: never) => Promise<unknown>;
+/** Creates the Lambda event of a request. */
+declare const toLambdaEvent: (request: Request, format: LambdaEventFormat, sourceIp?: string) => Promise<Record<string, unknown>>;
+/** Converts the result of a Lambda handler into a Web response. */
+declare const fromLambdaResult: (result: unknown) => Response;
+/**
+ * Target for AWS Lambda handlers: each request is sent as a simulated
+ * event of the given format, and the result converted back. A failed
+ * invocation gets a `502` response, like API Gateway.
+ */
+declare const createLambdaTarget: (handler: LambdaTestHandler, options: LambdaTargetOptions) => ConformanceTarget;
+
+interface LogEntry {
+    readonly level: 'debug' | 'info' | 'warn' | 'error';
+    readonly args: readonly unknown[];
+}
+interface MemoryLogger extends Logger {
+    /** Entries logged by this logger and its children. */
+    readonly entries: LogEntry[];
+}
+/**
+ * Logger that records entries instead of printing them.
+ */
+declare const createMemoryLogger: () => MemoryLogger;
+
+interface MemoryAdapterOptions {
+    /** Maximum request body size, in bytes. Defaults to 1 MiB. */
+    bodyLimit?: number;
+    /** Client IP address given to requests. Defaults to `127.0.0.1`. */
+    ip?: string;
+}
+interface MemoryAdapter extends HttpAdapter<{
+    readonly routes: readonly CompiledRoute[];
+}> {
+    /** Handles a Web `Request` in memory, without opening a port. */
+    fetch(request: Request): Promise<Response>;
+}
+/**
+ * HTTP adapter running requests in memory, for tests. It follows the
+ * adapter contract like any other adapter, and passes the conformance
+ * suite.
+ */
+declare const memoryAdapter: (options?: MemoryAdapterOptions) => MemoryAdapter;
+interface TestAppOptions extends Omit<AppOptions, 'adapter' | 'logger'> {
+    /** Options of the memory adapter. */
+    adapter?: MemoryAdapterOptions;
+    /** Defaults to a new memory logger. */
+    logger?: MemoryLogger;
+}
+interface TestApp {
+    readonly app: App<{
+        readonly routes: readonly CompiledRoute[];
+    }>;
+    readonly adapter: MemoryAdapter;
+    /** Logger of the app, recording the log entries. */
+    readonly logger: MemoryLogger;
+    /**
+     * Sends a request to the app, like `fetch()`. `path` is relative to
+     * `http://localhost`.
+     */
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+    close(): Promise<void>;
+}
+/**
+ * Creates an app on the memory adapter.
+ *
+ * @example
+ * const { fetch } = await createTestApp({ routers: [router], plugins: [authPlugin(auth)] })
+ * const res = await fetch('/auth/me', { headers: { authorization: `Bearer ${token}` } })
+ * expect(res.status).toBe(200)
+ */
+declare const createTestApp: (options?: TestAppOptions) => Promise<TestApp>;
+
+/** An emission, as recorded by `createFakeEventBus()` of `@dotpress/events`. */
+interface Emission {
+    readonly emissionId: string;
+    readonly event: string;
+    readonly payload: unknown;
+    readonly delay: number | undefined;
+    readonly metadata: Readonly<Record<string, string>>;
+    readonly emittedAt: Date;
+}
+/** The fields of an envelope read here (`Envelope` of `@dotpress/events`). */
+interface EnvelopeLike {
+    readonly emissionId: string;
+    readonly event: string;
+    readonly payload: unknown;
+    readonly metadata: Readonly<Record<string, string>>;
+    readonly emittedAt: string;
+}
+/**
+ * Where emissions are read: a fake event bus (`createFakeEventBus()`), or a
+ * memory transport (`createMemoryTransport()`), which only sees the events
+ * that have listeners on it.
+ */
+type EmissionSource<E extends Emission = Emission> = {
+    readonly emitted: readonly E[];
+} | {
+    readonly sent: readonly EnvelopeLike[];
+};
+/** Options of `expectEventEmitted()`. */
+interface ExpectEventOptions {
+    /** Exact number of matching emissions. Defaults to at least one. */
+    times?: number | undefined;
+    /** Metadata of the emission, matched partially. */
+    metadata?: Readonly<Record<string, unknown>> | undefined;
+    /** Delay of the emission, in seconds (fake event bus only). */
+    delay?: number | undefined;
+}
+/**
+ * Asserts that an event was emitted, at least once or exactly `times`
+ * times, with a payload (and metadata) matching the expected values:
+ * objects are matched partially, and asymmetric matchers are accepted.
+ * Without payload (or with `undefined`), any payload matches.
+ * Returns the last matching emission.
+ *
+ * ```ts
+ * const events = createFakeEventBus()
+ * await signUp(events, 'ada@example.com')
+ * expectEventEmitted(events, userCreated, { email: 'ada@example.com' })
+ * ```
+ */
+declare function expectEventEmitted<E extends Emission>(source: EmissionSource<E>, event: {
+    readonly name: string;
+} | string, ...rest: [payload?: unknown, options?: ExpectEventOptions]): E;
+/**
+ * Asserts that an event was not emitted (with this payload, if given).
+ *
+ * ```ts
+ * expectEventNotEmitted(events, userCreated)
+ * ```
+ */
+declare function expectEventNotEmitted(source: EmissionSource, event: {
+    readonly name: string;
+} | string, ...rest: [payload?: unknown]): void;
+
+interface Address {
+    readonly name?: string;
+    readonly address: string;
+}
+/** The fields of a message read here (`SentMail` of `@dotpress/mailer`). */
+interface SentMail {
+    readonly from: Address;
+    readonly to: readonly Address[];
+    readonly cc: readonly Address[];
+    readonly bcc: readonly Address[];
+    readonly replyTo: readonly Address[];
+    readonly subject: string;
+    readonly template: string | undefined;
+}
+/** Where messages are read: `createMemoryProvider()` of `@dotpress/mailer`. */
+interface MailOutbox<M extends SentMail = SentMail> {
+    readonly sent: readonly M[];
+}
+/** Recipients: every expected address must be among them (any case). */
+type ExpectedAddresses = string | readonly string[];
+/**
+ * Expected properties of a message. Recipients and `from` are compared by
+ * address; the other properties are matched like `toMatchObject()`
+ * (asymmetric matchers accepted: `expect.stringContaining()`…).
+ */
+interface MailCriteria {
+    to?: ExpectedAddresses | undefined;
+    cc?: ExpectedAddresses | undefined;
+    bcc?: ExpectedAddresses | undefined;
+    replyTo?: ExpectedAddresses | undefined;
+    from?: string | undefined;
+    /** The template, or its name. */
+    template?: string | {
+        readonly name: string;
+    } | undefined;
+    locale?: unknown;
+    subject?: unknown;
+    html?: unknown;
+    text?: unknown;
+    tags?: unknown;
+    metadata?: unknown;
+    headers?: unknown;
+    attachments?: unknown;
+}
+/** Options of `expectMailSent()`. */
+interface ExpectMailOptions {
+    /** Exact number of matching messages. Defaults to at least one. */
+    times?: number | undefined;
+}
+/**
+ * Asserts that a message matching the criteria was sent, at least once or
+ * exactly `times` times. Returns the last matching message.
+ *
+ * ```ts
+ * const outbox = createMemoryProvider()
+ * const mailer = createMailer({ provider: outbox, from: 'noreply@example.com' })
+ * await signUp(mailer, 'ada@example.com')
+ * const mail = expectMailSent(outbox, { to: 'ada@example.com', template: welcomeMail })
+ * expect(mail.html).toContain('https://example.com/confirm')
+ * ```
+ */
+declare const expectMailSent: <M extends SentMail>(outbox: MailOutbox<M>, criteria?: MailCriteria, options?: ExpectMailOptions) => M;
+/**
+ * Asserts that no message (matching the criteria, if given) was sent.
+ *
+ * ```ts
+ * expectNoMailSent(outbox, { to: 'ada@example.com' })
+ * ```
+ */
+declare const expectNoMailSent: (outbox: MailOutbox, criteria?: MailCriteria) => void;
+
+export { ExpectationError, createFetchTarget, createHttpTarget, createLambdaTarget, createMemoryLogger, createTestApp, expectEventEmitted, expectEventNotEmitted, expectMailSent, expectNoMailSent, fromLambdaResult, memoryAdapter, runConformanceSuite, toLambdaEvent };
+export type { ConformanceAppOptions, ConformanceSuiteOptions, ConformanceTarget, Emission, EmissionSource, ExpectEventOptions, ExpectMailOptions, LambdaEventFormat, LambdaTargetOptions, LambdaTestHandler, LogEntry, MailCriteria, MailOutbox, MemoryAdapter, MemoryAdapterOptions, MemoryLogger, SentMail, TestApp, TestAppOptions };