@shaferllc/keel 0.68.0 → 0.74.0

package/dist/core/testing.d.ts

@@ -33,17 +33,79 @@ export declare class TestResponse {
     assertHeader(name: string, value: string): this;
     /** Assert a redirect (3xx) to `location`. */
     assertRedirect(location?: string): this;
+    assertCreated(): this;
+    assertNoContent(): this;
+    assertBadRequest(): this;
+    assertUnauthorized(): this;
+    assertForbidden(): this;
+    assertNotFound(): this;
+    /** 422 — the status a failed `validate()` returns. */
+    assertUnprocessable(): this;
+    assertServerError(): this;
+    /**
+     * Assert the JSON body *contains* `expected` — a subset match, so a test can
+     * pin the fields it cares about without breaking every time an unrelated one
+     * is added.
+     *
+     *   res.assertJsonContains({ user: { email: "a@b.com" } });
+     */
+    assertJsonContains(expected: unknown): this;
+    /** Assert the body contains `text` anywhere. */
+    assertSee(text: string): this;
+    /** Assert the body does *not* contain `text`. */
+    assertDontSee(text: string): this;
+    /**
+     * Assert a 422 carrying an error on each named field. With no fields, it just
+     * asserts that validation failed.
+     *
+     *   res.assertValidationErrors("email", "password");
+     */
+    assertValidationErrors(...fields: string[]): this;
+    /** Assert there is *no* validation error on `field`. */
+    assertNoValidationError(field: string): this;
+    assertHeaderMissing(name: string): this;
+    /** The cookies this response set, by name. */
+    cookies(): Record<string, string>;
+    /** Assert the response set a cookie — with `value`, if you give one. */
+    assertCookie(name: string, value?: string): this;
+    assertCookieMissing(name: string): this;
+    /** Print status, headers, and body — for when a test fails and you're stuck. */
+    dump(): this;
+}
+/** Defaults applied to every request a `TestClient` makes. */
+interface ClientDefaults {
+    headers: Record<string, string>;
+    cookies: Record<string, string>;
 }
 /** Injects requests into an app and returns `TestResponse`s. */
 export declare class TestClient {
     private target;
-    constructor(target: Requestable);
+    private defaults;
+    constructor(target: Requestable, defaults?: ClientDefaults);
+    /** A copy of this client with extra default headers. */
+    withHeaders(headers: Record<string, string>): TestClient;
+    withHeader(name: string, value: string): TestClient;
+    /** A copy of this client that sends these cookies. */
+    withCookies(cookies: Record<string, string>): TestClient;
+    withCookie(name: string, value: string): TestClient;
+    /** Send `Authorization: Bearer <token>` — the shorthand for an API test. */
+    withToken(token: string): TestClient;
+    /** Send HTTP basic credentials. */
+    withBasicAuth(username: string, password: string): TestClient;
+    /** Ask for JSON back — sets `Accept: application/json`. */
+    acceptJson(): TestClient;
+    /** Merge the client's defaults into one request's init. */
+    private init;
     request(path: string, init?: RequestInit): Promise<TestResponse>;
     get(path: string, init?: RequestInit): Promise<TestResponse>;
     delete(path: string, init?: RequestInit): Promise<TestResponse>;
     post(path: string, body?: unknown, init?: RequestInit): Promise<TestResponse>;
     put(path: string, body?: unknown, init?: RequestInit): Promise<TestResponse>;
     patch(path: string, body?: unknown, init?: RequestInit): Promise<TestResponse>;
+    /** POST a URL-encoded form, the way a browser would. */
+    form(path: string, fields: Record<string, string | number | boolean>, init?: RequestInit): Promise<TestResponse>;
+    /** POST a multipart form — for file uploads. */
+    multipart(path: string, fields: Record<string, string | Blob>, init?: RequestInit): Promise<TestResponse>;
 }
 /**
  * Build a `TestClient` from an `Application`, an `HttpKernel`, or anything with a
@@ -51,4 +113,111 @@ export declare class TestClient {
  * `HttpKernel`; pass a kernel yourself if you need global middleware registered.
  */
 export declare function testClient(target: Application | HttpKernel | Requestable): TestClient;
+/**
+ * Put the framework's global state back the way it was, so one test can't leak
+ * into the next. Call it in an `afterEach`.
+ *
+ *   afterEach(() => resetState());
+ *
+ * It restores every fake (disk, queue, mail, hash, time), drops event listeners,
+ * empties the cache, and gives you a fresh lock store. It does **not** touch the
+ * database — see `refreshDatabase()`.
+ */
+export declare function resetState(): void;
+/** Whether time is currently frozen. */
+export declare function timeIsFrozen(): boolean;
+/**
+ * Freeze the clock, so anything that reads the time sees the same instant —
+ * which is how you test a token that expires in an hour without waiting an hour.
+ *
+ *   freezeTime("2026-07-11T12:00:00Z");
+ *   timeTravel(3600_000);            // an hour later
+ *   restoreTime();
+ *
+ * Mocks `Date` and `Date.now()`. It does **not** mock timers: a `setTimeout` still
+ * fires on the real clock.
+ */
+export declare function freezeTime(at?: Date | number | string): number;
+/** Move the frozen clock forward (or back, with a negative value) by milliseconds. */
+export declare function timeTravel(ms: number): number;
+/** Hand the real clock back. */
+export declare function restoreTime(): void;
+/** Assert at least one row in `table` matches `where` (an exact `count` if given). */
+export declare function assertDatabaseHas(table: string, where: Record<string, unknown>, count?: number): Promise<void>;
+/** Assert no row in `table` matches `where`. */
+export declare function assertDatabaseMissing(table: string, where: Record<string, unknown>): Promise<void>;
+/** Assert `table` holds exactly `count` rows. */
+export declare function assertDatabaseCount(table: string, count: number): Promise<void>;
+/** Assert `table` is empty. */
+export declare function assertDatabaseEmpty(table: string): Promise<void>;
+/**
+ * Empty tables between tests. Order matters when foreign keys do — pass children
+ * before parents.
+ *
+ *   afterEach(() => truncate("comments", "posts", "users"));
+ *
+ * This deletes rows; it doesn't roll back a transaction, so it works on every
+ * driver (D1, Postgres, libSQL) rather than only the ones with savepoints.
+ */
+export declare function truncate(...tables: string[]): Promise<void>;
+/** A recording stand-in for a function. */
+export interface Spy<A extends unknown[] = unknown[], R = unknown> {
+    (...args: A): R;
+    /** The arguments of every call, in order. */
+    readonly calls: A[];
+    readonly callCount: number;
+    /** Whether it was called at all. */
+    readonly called: boolean;
+    /** Whether any call had exactly these arguments. */
+    calledWith(...args: A): boolean;
+    /** Make it return something (or something new). */
+    returns(value: R): Spy<A, R>;
+    reset(): void;
+}
+/**
+ * A function that records how it was called — the smallest useful test double.
+ *
+ *   const send = spy<[string], void>();
+ *   notify(send);
+ *   assert.equal(send.callCount, 1);
+ *   assert.ok(send.calledWith("hello"));
+ */
+export declare function spy<A extends unknown[] = unknown[], R = unknown>(implementation?: (...args: A) => R): Spy<A, R>;
+export declare function spyOn<T extends object, K extends keyof T>(target: T, method: K): Spy<unknown[], unknown>;
+/** Undo every `spyOn()`. */
+export declare function restoreSpies(): void;
+/** What a command did: its output, its error output, and its exit code. */
+export declare class CommandResult {
+    readonly stdout: string[];
+    readonly stderr: string[];
+    readonly exitCode: number;
+    constructor(stdout: string[], stderr: string[], exitCode: number);
+    /** Everything written to stdout, joined. */
+    output(): string;
+    assertExitCode(expected: number): this;
+    /** Exit code 0. */
+    assertSucceeded(): this;
+    /** A non-zero exit code. */
+    assertFailed(): this;
+    /** Assert a line of output contains `text`. */
+    assertOutputContains(text: string): this;
+    assertOutputMatches(pattern: RegExp): this;
+    assertErrorContains(text: string): this;
+}
+/**
+ * Run a console command in-process and capture what it printed and the exit code
+ * it set — no subprocess, so it's fast and you can assert on it.
+ *
+ * You pass the command in, because the console entry point belongs to your app
+ * (it's the thing that knows how to build your application), not to the core:
+ *
+ *   import { run } from "@shaferllc/keel/core/cli";   // or your own bin
+ *
+ *   const result = await runCommand(() => run(["node", "keel", "routes"]));
+ *   result.assertSucceeded().assertOutputContains("GET  /users");
+ *
+ * `console.log`/`warn` are captured as stdout, `console.error` as stderr, and
+ * `process.exitCode` is read and then restored.
+ */
+export declare function runCommand(command: () => unknown | Promise<unknown>): Promise<CommandResult>;
 export {};