@stacksjs/testing 0.74.36 → 0.74.38

package/dist/console.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Split a command string the way a shell would, honouring quotes.
+ *
+ * `command('make:model Post --migration')` is the documented form, so the
+ * string has to become argv somewhere. Quoted arguments matter as soon as
+ * anything takes a message: `command('commit -m "two words"')` is otherwise
+ * three arguments and a broken test.
+ */
+export declare function splitCommand(input: string): string[];
+/**
+ * Run a buddy command and capture what it did.
+ *
+ * @example
+ * ```ts
+ * const result = await command('greet John --loud')
+ * expect(result.exitCode).toBe(0)
+ * expect(result.output).toContain('HELLO, JOHN!')
+ * ```
+ *
+ * @example Answering a prompt
+ * ```ts
+ * const result = await command('db:drop').withInput(['yes'])
+ * ```
+ */
+export declare function command(input: string | readonly string[]): CommandBuilder;
+/**
+ * Running a buddy command in a test (stacksjs/stacks#2581).
+ *
+ * Documented in `docs/testing/console-tests.md` and never implemented. The
+ * documentation also had its shape wrong: it imported `withInput` and
+ * `withEnv` as free functions when the samples used them as chained calls on
+ * the result of `command()`. They are methods, and this is the builder they
+ * hang off.
+ *
+ * The command runs in a CHILD PROCESS rather than in-process. A buddy command
+ * writes real files on startup - `storage/framework/runtime`, `storage/cloud` -
+ * and calls `process.exit`, so running one inside the test runner would leave
+ * that state behind and could take the runner down with it. A child process
+ * gets its own exit code and its own mess.
+ */
+/** What a finished command produced. */
+export declare interface CommandResult {
+  exitCode: number
+  output: string
+  stdout: string
+  stderr: string
+  timedOut: boolean
+}
+/** A command that has not run yet. Awaiting it runs it. */
+export declare interface CommandBuilder extends PromiseLike<CommandResult> {
+  withInput: (lines: readonly string[]) => CommandBuilder
+  withEnv: (env: Record<string, string>) => CommandBuilder
+  withCwd: (cwd: string) => CommandBuilder
+  withTimeout: (ms: number) => CommandBuilder
+}

package/dist/database.d.ts

@@ -54,3 +54,146 @@ export declare function useTransactionalTests(): {
   begin: () => Promise<void>
   rollback: () => Promise<void>
 };
+/**
+ * Assert at least one row in `table` matches `criteria`.
+ *
+ * @example
+ * ```ts
+ * await assertDatabaseHas('users', { email: 'john@example.com' })
+ * ```
+ */
+export declare function assertDatabaseHas(table: string, criteria: RowCriteria): Promise<void>;
+/**
+ * Assert no row in `table` matches `criteria`.
+ *
+ * @example
+ * ```ts
+ * await assertDatabaseMissing('users', { id: user.id })
+ * ```
+ */
+export declare function assertDatabaseMissing(table: string, criteria: RowCriteria): Promise<void>;
+/**
+ * Assert exactly `count` rows in `table` match `criteria`.
+ *
+ * Omit `criteria` to count the whole table.
+ *
+ * @example
+ * ```ts
+ * await assertDatabaseCount('orders', 3)
+ * await assertDatabaseCount('orders', 2, { product_id: 1 })
+ * ```
+ */
+export declare function assertDatabaseCount(table: string, count: number, criteria?: RowCriteria): Promise<void>;
+/**
+ * Assert a matching row exists and is soft-deleted.
+ *
+ * Soft deletion is `deleted_at` being set - the column the `useSoftDeletes`
+ * trait adds. A row that is not there at all fails differently from one that is
+ * there and not deleted, because those are different bugs: the first means the
+ * delete removed the row outright, the second that it did nothing.
+ *
+ * @example
+ * ```ts
+ * await assertSoftDeleted('users', { id: user.id })
+ * ```
+ */
+export declare function assertSoftDeleted(table: string, criteria: RowCriteria): Promise<void>;
+/**
+ * Assert a matching row exists and is NOT soft-deleted.
+ *
+ * @example
+ * ```ts
+ * await assertNotSoftDeleted('users', { id: user.id })
+ * ```
+ */
+export declare function assertNotSoftDeleted(table: string, criteria: RowCriteria): Promise<void>;
+/**
+ * Wrap every test in this file in a transaction that is rolled back after it
+ * (stacksjs/stacks#2581).
+ *
+ * The self-wiring form of {@link useTransactionalTests}, and the one six
+ * documentation pages have always shown. It registers its own `beforeEach` and
+ * `afterEach`, so a suite says what it wants once:
+ *
+ * ```ts
+ * import { useTransaction } from '@stacksjs/testing/database'
+ *
+ * describe('Order', () => {
+ *   useTransaction()
+ *
+ *   it('creates an order', async () => {
+ *     // ...rolled back when this returns
+ *   })
+ * })
+ * ```
+ *
+ * Call it at the top of a `describe`, or at the top of the file for every test
+ * in it - `beforeEach` is scoped by where it is registered, and so is this.
+ *
+ * Prefer {@link useTransactionalTests} when the hooks need to interleave with
+ * others in a particular order; this is the common case, not the only one.
+ */
+export declare function useTransaction(): void;
+/**
+ * A factory for `modelName`, e.g. `factory('User')`.
+ *
+ * There is deliberately no singular/plural mode switch: `make` and `create`
+ * always return one row, `makeMany` and `createMany` always return an array.
+ * A helper whose return type depends on whether `.count()` was called earlier
+ * in the chain cannot be typed honestly, and the caller always knows which
+ * one they want.
+ */
+export declare function factory(modelName: string): ModelFactory;
+/**
+ * Rows built from a model's own declared attribute factories.
+ *
+ * `docs/` documented a `Factory` class in four places, with four mutually
+ * incompatible signatures - `new Factory(User, attrs)`, `new Factory({
+ * definition() })`, `new Factory<User>({ definition() })` and
+ * `Factory.define(fn)` - and none of them ever existed. That is a fair sign
+ * nobody had one, and a fifth invented shape would not help.
+ *
+ * What DOES exist is the factory a model already declares:
+ *
+ * ```ts
+ * attributes: {
+ *   email: { factory: faker => faker.internet.email() },
+ * }
+ * ```
+ *
+ * so this exposes that, rather than asking a test to restate it. The rows come
+ * out of the same generator `buddy seed` uses, which is the point: password
+ * columns are hashed, unique columns are disambiguated across the batch, and
+ * relation columns are filled. A test factory that reimplemented this would
+ * differ from the seeder in exactly the ways that are invisible until a test
+ * passes for the wrong reason.
+ *
+ * @example
+ * ```ts
+ * const attrs = await factory('User').make()                 // not persisted
+ * const user = await factory('User').create()                // one row
+ * const admins = await factory('User').createMany(3, { role: 'admin' })
+ * ```
+ */
+export declare interface ModelFactory {
+  make: (overrides?: RowCriteria) => Promise<Record<string, unknown>>
+  makeMany: (count: number, overrides?: RowCriteria) => Promise<Record<string, unknown>[]>
+  create: (overrides?: RowCriteria) => Promise<Record<string, unknown>>
+  createMany: (count: number, overrides?: RowCriteria) => Promise<Record<string, unknown>[]>
+}
+/**
+ * Database assertions (stacksjs/stacks#2581).
+ *
+ * Documented for a long time and never implemented, so every sample teaching
+ * them imported from `@stacksjs/testing` and failed. They live HERE rather than
+ * at the package root for the reason the file header gives: the root
+ * deliberately does not import `@stacksjs/database`, because doing so eagerly
+ * deadlocks bun's module loader outside the framework's preloader.
+ *
+ * Each throws rather than returning a boolean. A test asserting on a database
+ * wants the row it was expecting in the failure message - `expect(true).toBe(
+ * true)` on a helper that returned false tells nobody anything - so the message
+ * carries the table, the criteria, and what was actually there.
+ */
+/** Column/value pairs a row must match. Every pair is ANDed. */
+export type RowCriteria = Record<string, unknown>;

package/dist/database.js

@@ -1,2 +1,2 @@
 // @bun
-import{config as l}from"@stacksjs/config";import{copyModelFiles as w,db as a,deleteFrameworkModels as y,dropSqliteTables as h,fetchSqliteFile as c,fetchTables as T,migrateAuthTables as S,migrateNotificationTables as g,migrateRbacTables as P,migrateTraitTables as E,ensureUtcDatetimeColumns as x,ensureUtcTimestampDefaults as A,runDatabaseMigration as u}from"@stacksjs/database";import{path as o}from"@stacksjs/path";import{fs as i,globSync as f}from"@stacksjs/storage";function m(){return l.database?.default||""}var r=null;function M(){if(r)return r;return r=`${c()}.snapshot`,r}async function d(){let t=[["auth",S],["notification",g],["RBAC",P],["trait",E],["utc-datetime",x],["utc-defaults",A]];for(let[e,n]of t)try{let s=await n();if(!s.success)console.error(`[testing] Failed to migrate ${e} tables: ${s.error}`)}catch(s){console.error(`[testing] Failed to migrate ${e} tables:`,s)}}async function v(){let t=`${l.database?.connections?.mysql?.name??"stacks"}_testing`;if(m()==="mysql")await a.unsafe(`CREATE DATABASE IF NOT EXISTS ${t}`).execute(),await u(),await d()}async function _(){await v();let t=m();if(t==="mysql")await F();if(t==="sqlite")await q()}async function F(){let t=await T();await a.unsafe("SET FOREIGN_KEY_CHECKS = 0").execute();try{for(let e of t)await a.unsafe(`TRUNCATE TABLE ${e}`).execute()}finally{await a.unsafe("SET FOREIGN_KEY_CHECKS = 1").execute()}}async function k(){let t=c();if(!i.existsSync(t))await Bun.$`touch ${t}`;await h(),await y();let e=f([o.userModelsPath("*.ts"),o.storagePath("framework/defaults/app/Models/**/*.ts")],{absolute:!0});for(let n of e)await w(n);await u(),await d()}async function q(){let t=c(),e=M();if((()=>{if(!i.existsSync(e))return!0;let s=i.statSync(e).mtimeMs,p=f([o.userModelsPath("*.ts"),o.storagePath("framework/defaults/app/Models/**/*.ts"),o.userMigrationsPath("*.ts")],{absolute:!0});for(let b of p)try{if(i.statSync(b).mtimeMs>s)return!0}catch{}return!1})()){await k();try{await a.unsafe("PRAGMA wal_checkpoint(TRUNCATE)").execute(),i.copyFileSync(t,e)}catch{}return}i.copyFileSync(e,t)}function D(){let t=null;return{begin:async()=>{let e=`stacks_test_${Date.now()}_${Math.floor(Math.random()*1e6)}`;await a.unsafe(`SAVEPOINT ${e}`).execute(),t={rollback:async()=>{await a.unsafe(`ROLLBACK TO SAVEPOINT ${e}`).execute(),await a.unsafe(`RELEASE SAVEPOINT ${e}`).execute()}}},rollback:async()=>{if(!t)return;try{await t.rollback()}finally{t=null}}}}export{_ as refreshDatabase,v as setupDatabase,F as truncateMysql,k as truncateSqlite,q as truncateSqliteFast,D as useTransactionalTests};
+import{afterEach as P,beforeEach as R}from"bun:test";import{config as h}from"@stacksjs/config";import{copyModelFiles as v,db as s,deleteFrameworkModels as k,dropSqliteTables as T,fetchSqliteFile as f,fetchTables as S,migrateAuthTables as C,migrateNotificationTables as M,migrateRbacTables as A,migrateTraitTables as F,ensureUtcDatetimeColumns as _,ensureUtcTimestampDefaults as D,runDatabaseMigration as p}from"@stacksjs/database";import{path as u}from"@stacksjs/path";import{fs as c,globSync as y}from"@stacksjs/storage";function b(){return h.database?.default||""}var d=null;function N(){if(d)return d;return d=`${f()}.snapshot`,d}async function E(){let t=[["auth",C],["notification",M],["RBAC",A],["trait",F],["utc-datetime",_],["utc-defaults",D]];for(let[e,n]of t)try{let r=await n();if(!r.success)console.error(`[testing] Failed to migrate ${e} tables: ${r.error}`)}catch(r){console.error(`[testing] Failed to migrate ${e} tables:`,r)}}async function q(){let t=`${h.database?.connections?.mysql?.name??"stacks"}_testing`;if(b()==="mysql")await s.unsafe(`CREATE DATABASE IF NOT EXISTS ${t}`).execute(),await p(),await E()}async function V(){await q();let t=b();if(t==="mysql")await O();if(t==="sqlite")await B()}async function O(){let t=await S();await s.unsafe("SET FOREIGN_KEY_CHECKS = 0").execute();try{for(let e of t)await s.unsafe(`TRUNCATE TABLE ${e}`).execute()}finally{await s.unsafe("SET FOREIGN_KEY_CHECKS = 1").execute()}}async function I(){let t=f();if(!c.existsSync(t))await Bun.$`touch ${t}`;await T(),await k();let e=y([u.userModelsPath("*.ts"),u.storagePath("framework/defaults/app/Models/**/*.ts")],{absolute:!0});for(let n of e)await v(n);await p(),await E()}async function B(){let t=f(),e=N();if((()=>{if(!c.existsSync(e))return!0;let r=c.statSync(e).mtimeMs,a=y([u.userModelsPath("*.ts"),u.storagePath("framework/defaults/app/Models/**/*.ts"),u.userMigrationsPath("*.ts")],{absolute:!0});for(let o of a)try{if(c.statSync(o).mtimeMs>r)return!0}catch{}return!1})()){await I();try{await s.unsafe("PRAGMA wal_checkpoint(TRUNCATE)").execute(),c.copyFileSync(t,e)}catch{}return}c.copyFileSync(e,t)}function K(){let t=null;return{begin:async()=>{let e=`stacks_test_${Date.now()}_${Math.floor(Math.random()*1e6)}`;await s.unsafe(`SAVEPOINT ${e}`).execute(),t={rollback:async()=>{await s.unsafe(`ROLLBACK TO SAVEPOINT ${e}`).execute(),await s.unsafe(`RELEASE SAVEPOINT ${e}`).execute()}}},rollback:async()=>{if(!t)return;try{await t.rollback()}finally{t=null}}}}function i(t){let e=Object.entries(t).map(([n,r])=>`${n}=${JSON.stringify(r)}`);return e.length>0?e.join(", "):"(no criteria)"}async function l(t,e){let n=s.selectFrom(t).selectAll();for(let[r,a]of Object.entries(e))n=n.where(r,"=",a);return await n.execute()}async function J(t,e){if((await l(t,e)).length>0)return;let r=await l(t,{});throw Error(`Expected ${t} to have a row matching ${i(e)}, but none did (${r.length} row(s) in the table).`)}async function Y(t,e){let n=await l(t,e);if(n.length===0)return;throw Error(`Expected ${t} to have no row matching ${i(e)}, but found ${n.length}: ${JSON.stringify(n.slice(0,3))}${n.length>3?" \u2026":""}`)}async function X(t,e,n={}){if(!Number.isInteger(e)||e<0)throw TypeError(`assertDatabaseCount expects a non-negative integer, got ${e}`);let r=await l(t,n);if(r.length===e)return;throw Error(`Expected ${e} row(s) in ${t} matching ${i(n)}, found ${r.length}.`)}async function z(t,e){let n=await l(t,e);if(n.length===0)throw Error(`Expected ${t} to have a soft-deleted row matching ${i(e)}, but no row matched at all - a hard delete removes the row rather than setting deleted_at.`);let r=n.filter((a)=>a.deleted_at===null||a.deleted_at===void 0);if(r.length===0)return;throw Error(`Expected every ${t} row matching ${i(e)} to be soft-deleted, but ${r.length} of ${n.length} still has a null deleted_at.`)}async function Q(t,e){let n=await l(t,e);if(n.length===0)throw Error(`Expected ${t} to have a row matching ${i(e)}, but none did.`);let r=n.filter((a)=>a.deleted_at!==null&&a.deleted_at!==void 0);if(r.length===0)return;throw Error(`Expected no ${t} row matching ${i(e)} to be soft-deleted, but ${r.length} of ${n.length} has a deleted_at set.`)}function W(){let t=K();R(t.begin),P(t.rollback)}function Z(t){async function e(){let{plural:a,snakeCase:o}=await import("@stacksjs/strings");return a(o(t))}async function n(a,o){let{makeModelRecords:w}=await import("@stacksjs/database");return w(t,a,o)}async function r(a){let{db:o}=await import("@stacksjs/database"),w=await e(),m=[];for(let g of a){let x=await o.insertInto(w).values(g).returningAll().executeTakeFirst();m.push(x??g)}return m}return{async make(a={}){return(await n(1,a))[0]},async makeMany(a,o={}){return n(a,o)},async create(a={}){return(await r(await n(1,a)))[0]},async createMany(a,o={}){return r(await n(a,o))}}}export{X as assertDatabaseCount,J as assertDatabaseHas,Y as assertDatabaseMissing,Q as assertNotSoftDeleted,z as assertSoftDeleted,Z as factory,V as refreshDatabase,q as setupDatabase,O as truncateMysql,I as truncateSqlite,B as truncateSqliteFast,W as useTransaction,K as useTransactionalTests};

package/dist/dynamodb.d.ts

@@ -1,3 +1,2 @@
-export declare function launchServer(): Promise<void>;
 export declare function createStacksTable(): Promise<void>;
 export declare function deleteStacksTable(): Promise<void>;

package/dist/dynamodb.js

@@ -1,2 +1,2 @@
 // @bun
-import r from"process";import{DynamoDBClient as o}from"@stacksjs/ts-cloud";var i=await import("@stacksjs/cache").then((e)=>e.dynamoDbTool),t=new o("us-east-1");async function y(){if(!r.env.GITHUB_ACTIONS)await i.dynamoDb.launch();await n(5000),await c()}async function n(e){return new Promise((a)=>setTimeout(a,e))}async function c(){try{await t.createTable({TableName:"stacks",KeySchema:[{AttributeName:"key",KeyType:"HASH"}],AttributeDefinitions:[{AttributeName:"key",AttributeType:"S"}],ProvisionedThroughput:{ReadCapacityUnits:5,WriteCapacityUnits:5}})}catch(e){console.error("Error Creating Table",e)}}async function l(){try{await t.deleteTable({TableName:"stacks"})}catch(e){console.error("Error deleting table:",e)}}export{c as createStacksTable,l as deleteStacksTable,y as launchServer};
+import{DynamoDBClient as a}from"@stacksjs/ts-cloud";var t=new a("us-east-1");async function i(){try{await t.createTable({TableName:"stacks",KeySchema:[{AttributeName:"key",KeyType:"HASH"}],AttributeDefinitions:[{AttributeName:"key",AttributeType:"S"}],ProvisionedThroughput:{ReadCapacityUnits:5,WriteCapacityUnits:5}})}catch(e){console.error("Error Creating Table",e)}}async function o(){try{await t.deleteTable({TableName:"stacks"})}catch(e){console.error("Error deleting table:",e)}}export{i as createStacksTable,o as deleteStacksTable};

package/dist/events.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Record every dispatched event and stop the real listeners from running.
+ *
+ * Suppression is the point, not a side effect. A feature test asserting that
+ * an event fired should not also send the welcome email, write the audit row,
+ * and reindex the model - those are the listeners' own tests. The handlers are
+ * taken off the shared emitter and put back by `restoreEvents()`, which is
+ * wired to `afterEach` automatically so a test that forgets cannot leak a
+ * silenced event bus into the next one.
+ */
+export declare function eventFake(): void;
+/** Whether a fake is currently installed. */
+export declare function eventsAreFaked(): boolean;
+/**
+ * Events dispatched since `eventFake()`, optionally filtered by type.
+ *
+ * Returns a copy, so a test holding the result across further dispatches sees
+ * what it asked for rather than a list that keeps growing under it.
+ */
+export declare function getDispatchedEvents(type?: string): DispatchedEvent[];
+/** Whether an event of this type was dispatched at least once. */
+export declare function hasDispatchedEvent(type: string): boolean;
+/** Put the real listeners back and forget what was recorded. */
+export declare function restoreEvents(): void;
+/**
+ * Event fakes for feature tests (stacksjs/stacks#2581).
+ *
+ * `docs/testing/feature-tests.md` has documented `eventFake()` and
+ * `getDispatchedEvents()` for a long time against a package that exported
+ * neither. They are worth having rather than deleting: asserting that
+ * registering a user FIRES `UserRegistered` is a different test from asserting
+ * what the listener then did, and without a fake the two are stuck together.
+ *
+ * `@stacksjs/queue` already has the same pair for jobs (`fake()`,
+ * `getFakeQueue()`, `restore()`), so this follows it.
+ */
+/** One event as it was dispatched. */
+export declare interface DispatchedEvent {
+  type: string
+  payload: unknown
+}

package/dist/feature.d.ts

@@ -1,5 +1,52 @@
 export declare function setupTestEnvironment(): void;
+/**
+ * `?a=1&b=2` for `options.query`, or `''` when there is nothing to append.
+ *
+ * `undefined` and `null` are dropped rather than sent as the strings
+ * `"undefined"` / `"null"`, so an optional filter can be passed through
+ * without the caller building the object conditionally. An array repeats the
+ * key (`tag=a&tag=b`), which is what every server-side parser in this
+ * repository expects.
+ */
+export declare function queryString(query: Record<string, QueryValue> | undefined): string;
+/**
+ * Reject an options object that is really a body.
+ *
+ * `http.post('/api/users', { name: 'Jane' })` is the mistake this package
+ * would otherwise make silently: the object looks like a body, is treated as
+ * options, matches no known key, and the request goes out empty. Failing
+ * loudly costs one comparison and saves a debugging session.
+ */
+export declare function assertRequestOptions(options: RequestOptions, method: string, path: string): void;
 export declare function featureTest(baseUrl?: string): FeatureTestClient;
+/**
+ * Authenticate as `user`, then make requests.
+ *
+ * Shorthand for `featureTest().actingAs(user)`, which is how nearly every
+ * feature test starts. The returned client is fresh per call, so two tests
+ * acting as two users never share a token.
+ */
+export declare function actingAs(user: { id: number | string, [k: string]: unknown }, baseUrl?: string): FeatureTestClient;
+/**
+ * A request-at-a-time HTTP client for feature tests.
+ *
+ * Each call constructs its own `featureTest()` client, so `http` holds no
+ * state at all: nothing an earlier test set can reach a later one, which is
+ * the failure mode a shared module-level client would have.
+ *
+ * ```ts
+ * await http.get('/api/users', { query: { page: 1 } })
+ * await http.post('/api/users', { body: { name: 'Jane' } })
+ * await http.post('/api/upload', { formData: { file: new File(['x'], 'a.txt') } })
+ * ```
+ *
+ * Note the body is WRAPPED. The fluent client takes a bare body
+ * (`featureTest().post('/api/users', { name: 'Jane' })`) because it has no
+ * options to disambiguate it from; `http` has, so it cannot. Passing a bare
+ * body here throws rather than sending an empty request - see
+ * `assertRequestOptions`.
+ */
+export declare const http: HttpClient;
 /**
  * Lightweight feature-test helper. Returns a fluent client that wraps
  * the request flow (`actingAs`, `json`, `assertStatus`, etc.) so test
@@ -28,6 +75,7 @@ export declare function featureTest(baseUrl?: string): FeatureTestClient;
  */
 export declare interface FeatureTestResponse {
   status: number
+  ok: boolean
   headers: Headers
   text: () => Promise<string>
   json: <T = unknown>() => Promise<T>
@@ -38,9 +86,42 @@ export declare interface FeatureTestResponse {
 export declare interface FeatureTestClient {
   actingAs: (user: { id: number | string, [k: string]: unknown }) => FeatureTestClient
   withHeaders: (headers: Record<string, string>) => FeatureTestClient
+  request: (method: string, path: string, spec?: Omit<RequestOptions, 'actingAs'>) => Promise<FeatureTestResponse>
   get: (path: string) => Promise<FeatureTestResponse>
   post: (path: string, body?: unknown) => Promise<FeatureTestResponse>
   put: (path: string, body?: unknown) => Promise<FeatureTestResponse>
   patch: (path: string, body?: unknown) => Promise<FeatureTestResponse>
   delete: (path: string, body?: unknown) => Promise<FeatureTestResponse>
 }
+/**
+ * One request, described rather than built up by chaining.
+ *
+ * This is the shape `http.*` takes. It exists next to the fluent client
+ * because the two answer different questions: `featureTest()` is for a
+ * sequence of requests that share an identity, `http` is for a single
+ * self-contained one.
+ */
+export declare interface RequestOptions {
+  headers?: Record<string, string>
+  query?: Record<string, QueryValue>
+  body?: unknown
+  formData?: Record<string, string | Blob>
+  actingAs?: { id: number | string, [k: string]: unknown }
+}
+/**
+ * A stateless HTTP client for feature tests.
+ *
+ * Every method takes `(path, options?)` and builds a fresh request, so
+ * nothing leaks between tests and there is no client to construct.
+ */
+export declare interface HttpClient {
+  get: (path: string, options?: RequestOptions) => Promise<FeatureTestResponse>
+  post: (path: string, options?: RequestOptions) => Promise<FeatureTestResponse>
+  put: (path: string, options?: RequestOptions) => Promise<FeatureTestResponse>
+  patch: (path: string, options?: RequestOptions) => Promise<FeatureTestResponse>
+  delete: (path: string, options?: RequestOptions) => Promise<FeatureTestResponse>
+  head: (path: string, options?: RequestOptions) => Promise<FeatureTestResponse>
+  options: (path: string, options?: RequestOptions) => Promise<FeatureTestResponse>
+}
+/** A value a query string can carry, before it is stringified. */
+export type QueryValue = string | number | boolean | null | undefined | Array<string | number | boolean>;

package/dist/index.d.ts

@@ -18,4 +18,13 @@
 // Tests that don't need them get a fast, hang-free import from
 // '@stacksjs/testing'.
 export * from './feature';
+// Clock control (stacksjs/stacks#2581). No database dependency, so unlike the
+// fixtures it is safe at the root.
+export * from './console';
+// Event fakes (stacksjs/stacks#2581). `@stacksjs/events` is a leaf package with
+// no database dependency, so unlike the fixtures it is safe at the root.
+export * from './events';
+// Mail fakes (stacksjs/stacks#2581), on top of the email package's capture driver.
+export * from './mail';
+export * from './time';
 export * from 'bun:test';

package/dist/index.js

@@ -1,2 +1,3 @@
 // @bun
-import p from"process";function R(){p.env.NODE_ENV="test",p.env.APP_ENV="test"}async function h(){let o=await import("@stacksjs/router");return o.serverResponse}function T(o){let a={status:o.status,headers:o.headers,text:()=>o.text(),json:async()=>await o.clone().json(),assertStatus(s){if(this.status!==s)throw Error(`Expected status ${s}, got ${this.status}`);return a},async assertJson(s){let n=await o.clone().json();for(let[i,u]of Object.entries(s))if(JSON.stringify(n[i])!==JSON.stringify(u))throw Error(`assertJson: expected ${i}=${JSON.stringify(u)}, got ${JSON.stringify(n[i])}`);return a},assertHeader(s,n){let i=o.headers.get(s);if(i===null)throw Error(`assertHeader: missing header '${s}'`);if(n!==void 0){if(!(typeof n==="string"?i===n:n.test(i)))throw Error(`assertHeader: expected ${s}=${String(n)}, got '${i}'`)}return a}};return a}function k(o="http://localhost"){let a=null,s={},n=null;async function i(){if(!a)return null;if(n)return n;let{Auth:t}=await import("@stacksjs/auth"),e=Number(a.id);if(!Number.isFinite(e))throw TypeError(`actingAs() needs a user with a numeric id; got ${JSON.stringify(a.id)}`);let r=await t.loginUsingId(e);if(!r)throw Error(`actingAs() could not authenticate user ${e}: no such user. Create the row first (e.g. via a factory) so a token can be issued against it.`);return n=String(r.token),n}async function u(t){let e={Accept:"application/json",...s};if(t!==void 0)e["Content-Type"]="application/json";let r=await i();if(r&&!e.Authorization&&!e.authorization)e.Authorization=`Bearer ${r}`;return e}async function c(t,e,r){let d=await h(),l=e.startsWith("http")?e:`${o}${e}`,f={method:t,headers:await u(r),body:r===void 0?void 0:typeof r==="string"?r:JSON.stringify(r)},w=await d(new Request(l,f));return T(w)}let g={actingAs(t){return a=t,n=null,g},withHeaders(t){return s={...s,...t},g},get:(t)=>c("GET",t),post:(t,e)=>c("POST",t,e),put:(t,e)=>c("PUT",t,e),patch:(t,e)=>c("PATCH",t,e),delete:(t,e)=>c("DELETE",t,e)};return g}export*from"bun:test";export{k as featureTest,R as setupTestEnvironment};
+import R from"process";function z(){R.env.NODE_ENV="test",R.env.APP_ENV="test"}var b=new Set(["headers","query","body","formData","actingAs"]);function q(e){if(!e)return"";let t=new URLSearchParams;for(let[s,o]of Object.entries(e)){if(o===void 0||o===null)continue;if(Array.isArray(o)){for(let u of o)t.append(s,String(u));continue}t.append(s,String(o))}let n=t.toString();return n?`?${n}`:""}function D(e,t,n){let s=Object.keys(e).filter((o)=>!b.has(o));if(s.length===0)return;throw TypeError(`http.${t.toLowerCase()}('${n}', \u2026) got unknown option(s) ${s.map((o)=>`'${o}'`).join(", ")}. Did you mean to send a body? Wrap it: { body: { ${s[0]}: \u2026 } }. `+`Valid options are ${[...b].join(", ")}.`)}async function S(){let e=await import("@stacksjs/router");return e.serverResponse}function N(e){let t={status:e.status,ok:e.ok,headers:e.headers,text:()=>e.text(),json:async()=>await e.clone().json(),assertStatus(n){if(this.status!==n)throw Error(`Expected status ${n}, got ${this.status}`);return t},async assertJson(n){let s=await e.clone().json();for(let[o,u]of Object.entries(n))if(JSON.stringify(s[o])!==JSON.stringify(u))throw Error(`assertJson: expected ${o}=${JSON.stringify(u)}, got ${JSON.stringify(s[o])}`);return t},assertHeader(n,s){let o=e.headers.get(n);if(o===null)throw Error(`assertHeader: missing header '${n}'`);if(s!==void 0){if(!(typeof s==="string"?o===s:s.test(o)))throw Error(`assertHeader: expected ${n}=${String(s)}, got '${o}'`)}return t}};return t}function k(e="http://localhost"){let t=null,n={},s=null;async function o(){if(!t)return null;if(s)return s;let{Auth:r}=await import("@stacksjs/auth"),i=Number(t.id);if(!Number.isFinite(i))throw TypeError(`actingAs() needs a user with a numeric id; got ${JSON.stringify(t.id)}`);let d=await r.loginUsingId(i);if(!d)throw Error(`actingAs() could not authenticate user ${i}: no such user. Create the row first (e.g. via a factory) so a token can be issued against it.`);return s=String(d.token),s}async function u(r){let i={Accept:"application/json",...n,...r.headers};if(r.body!==void 0&&r.formData===void 0)i["Content-Type"]="application/json";let d=await o();if(d&&!i.Authorization&&!i.authorization)i.Authorization=`Bearer ${d}`;return i}function l(r){if(r.formData!==void 0){if(r.body!==void 0)throw TypeError("A request carries either `body` or `formData`, not both.");let i=new FormData;for(let[d,m]of Object.entries(r.formData))i.append(d,m);return i}if(r.body===void 0)return;return typeof r.body==="string"?r.body:JSON.stringify(r.body)}async function c(r,i,d={}){let m=await S(),w=i.startsWith("http")?i:`${e}${i}`,y=q(d.query),P=y&&w.includes("?")?`${w}&${y.slice(1)}`:`${w}${y}`,C={method:r,headers:await u(d),body:l(d)},A=await m(new Request(P,C));return N(A)}let a={actingAs(r){return t=r,s=null,a},withHeaders(r){return n={...n,...r},a},request:(r,i,d)=>c(r,i,d),get:(r)=>c("GET",r),post:(r,i)=>c("POST",r,{body:i}),put:(r,i)=>c("PUT",r,{body:i}),patch:(r,i)=>c("PATCH",r,{body:i}),delete:(r,i)=>c("DELETE",r,{body:i})};return a}function Q(e,t){return k(t).actingAs(e)}var G=Object.freeze(["GET","POST","PUT","PATCH","DELETE","HEAD","OPTIONS"].reduce((e,t)=>{let n=async(s,o={})=>{D(o,t,s);let{actingAs:u,...l}=o,c=k();if(u)c.actingAs(u);return c.request(t,s,l)};return{...e,[t.toLowerCase()]:n}},{}));import x from"process";var j=60000;function H(e){let t=[],n="",s=null,o=!1,u=!1;for(let l of e){if(o){n+=l,o=!1;continue}if(l==="\\"){o=!0,u=!0;continue}if(s){if(l===s)s=null;else n+=l;continue}if(l==='"'||l==="'"){s=l,u=!0;continue}if(/\s/.test(l)){if(u)t.push(n),n="",u=!1;continue}n+=l,u=!0}if(s)throw Error(`Unterminated ${s} in command: ${e}`);if(u)t.push(n);return t}function Y(e){let t=typeof e==="string"?H(e):[...e],n,s={},o=x.cwd(),u=j;async function l(){if(t.length===0)throw Error("command() needs something to run");let a=Bun.spawn(["./buddy",...t],{cwd:o,env:{...x.env,...s},stdin:n===void 0?"ignore":new TextEncoder().encode(n),stdout:"pipe",stderr:"pipe"}),r=!1,i=setTimeout(()=>{r=!0,a.kill()},u);try{let[d,m,w]=await Promise.all([new Response(a.stdout).text(),new Response(a.stderr).text(),a.exited]);return{exitCode:w,stdout:d,stderr:m,output:d+m,timedOut:r}}finally{clearTimeout(i)}}let c={withInput(a){return n=a.map((r)=>`${r}
+`).join(""),c},withEnv(a){return s={...s,...a},c},withCwd(a){return o=a,c},withTimeout(a){if(!Number.isFinite(a)||a<=0)throw TypeError(`withTimeout expects a positive number of milliseconds, got ${a}`);return u=a,c},then(a,r){return l().then(a,r)}};return c}import{afterEach as B}from"bun:test";import{events as g}from"@stacksjs/events";var p=null,h=[],E=(e,t)=>{h.push({type:String(e),payload:t})};function te(){if(p)return;p=[...g.all.entries()],g.all.clear(),h=[],g.on("*",E)}function ne(){return p!==null}function L(e){if(!p)throw Error('getDispatchedEvents() was called without eventFake(). Nothing is recording, so an empty result would look like "the event did not fire".');return e===void 0?[...h]:h.filter((t)=>t.type===e)}function re(e){return L(e).length>0}function J(){if(!p)return;g.off("*",E),g.all.clear();for(let[e,t]of p)g.all.set(e,t);p=null,h=[]}B(()=>{J()});import{afterEach as I}from"bun:test";import{CaptureEmailDriver as T,mail as v}from"@stacksjs/email";var f=null;function ae(){if(f!==null)return;f=v.fake(),T.clear()}function ue(){return f!==null}function O(){if(f===null)throw Error('sentEmails() was called without mailFake(). Nothing is capturing, so an empty result would look like "no email was sent".');return[...T.all()]}function de(){return O().at(-1)}function le(e){let t=(n)=>{if(n===void 0||n===null)return!1;return(Array.isArray(n)?n:[n]).some((o)=>(typeof o==="string"?o:o?.address)===e)};return O().filter((n)=>t(n.to)||t(n.cc)||t(n.bcc))}function M(){if(f===null)return;v.restoreDriver(f),f=null,T.clear()}I(()=>{M()});import{setSystemTime as F}from"bun:test";function U(e){let t=e instanceof Date?e:new Date(e);if(Number.isNaN(t.getTime()))throw TypeError(`Not a valid time: ${JSON.stringify(e)}`);return t}function _(e=new Date){let t=U(e);return F(t),t}function fe(e){return _(e)}function me(){F()}export*from"bun:test";export{Q as actingAs,D as assertRequestOptions,Y as command,le as emailsTo,te as eventFake,ne as eventsAreFaked,k as featureTest,_ as freezeTime,L as getDispatchedEvents,re as hasDispatchedEvent,G as http,de as lastEmail,ae as mailFake,ue as mailIsFaked,q as queryString,J as restoreEvents,M as restoreMail,O as sentEmails,z as setupTestEnvironment,H as splitCommand,fe as travelTo,me as useRealTime};

package/dist/mail.d.ts

@@ -0,0 +1,23 @@
+import type { CapturedMessage } from '@stacksjs/email';
+/**
+ * Send every email into memory instead of a transport.
+ *
+ * Redirects the shared `mail` singleton - the one the code under test uses -
+ * and clears anything a previous test captured.
+ */
+export declare function mailFake(): void;
+/** Whether a mail fake is currently installed. */
+export declare function mailIsFaked(): boolean;
+/**
+ * Every message sent since `mailFake()`, oldest first.
+ *
+ * A copy, so a test holding the result across further sends sees what it
+ * asked for.
+ */
+export declare function sentEmails(): CapturedMessage[];
+/** The most recent message, or `undefined` if none was sent. */
+export declare function lastEmail(): CapturedMessage | undefined;
+/** Messages addressed to `address`, matching any of to/cc/bcc. */
+export declare function emailsTo(address: string): CapturedMessage[];
+/** Put the real transport back and drop what was captured. */
+export declare function restoreMail(): void;

package/dist/time.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Stop the clock, at `at` or at the current moment.
+ *
+ * **Restore it when the test ends.** The system time is process-wide and bun
+ * does not roll it back between test files, so a frozen clock leaks into every
+ * later suite in the same run - where it surfaces as a token that is
+ * inexplicably expired, or a `created_at` in the wrong year, a long way from
+ * the test that caused it.
+ *
+ * @example
+ * ```ts
+ * import { afterEach, freezeTime, useRealTime } from '@stacksjs/testing'
+ *
+ * afterEach(useRealTime)
+ *
+ * it('expires after an hour', () => {
+ *   freezeTime('2024-01-15T10:00:00Z')
+ *   // ...
+ * })
+ * ```
+ */
+export declare function freezeTime(at?: TimeLike): Date;
+/**
+ * Move the clock to `at`, leaving it frozen there.
+ *
+ * The same operation as {@link freezeTime} with an argument; both exist because
+ * a test that has already frozen reads better as travelling than as freezing
+ * again. Restore with {@link useRealTime}.
+ *
+ * @example
+ * ```ts
+ * travelTo(new Date('2024-06-01'))
+ * ```
+ */
+export declare function travelTo(at: TimeLike): Date;
+/**
+ * Hand the clock back to the operating system.
+ *
+ * Not in the documentation this implements, and that was the documentation's
+ * bug: without it the clock stays where the last test put it for the rest of
+ * the process.
+ */
+export declare function useRealTime(): void;
+/**
+ * Controlling the clock in a test (stacksjs/stacks#2581).
+ *
+ * Documented in `docs/packages/testing.md` and never implemented, so the sample
+ * teaching it imported two names that did not exist.
+ *
+ * Thin on purpose: `bun:test` already has `setSystemTime`, and these exist
+ * because the intent of a test reads better as "freeze time" than as "set the
+ * system time to now". The one thing they add over calling it directly is
+ * {@link useRealTime} and the insistence on restoring - see below.
+ */
+/** What a caller may name a moment with. */
+export type TimeLike = Date | string | number;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/testing",
   "type": "module",
   "sideEffects": false,
-  "version": "0.74.36",
+  "version": "0.74.38",
   "description": "The Stacks way of testing.",
   "author": "Chris Breuer",
   "contributors": [
@@ -27,7 +27,6 @@
     "testing",
     "utilities",
     "functions",
-    "playwright",
     "stacks"
   ],
   "exports": {
@@ -74,14 +73,17 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/auth": "0.74.36",
-    "@stacksjs/cache": "0.74.36",
-    "@stacksjs/config": "0.74.36",
-    "@stacksjs/database": "0.74.36",
-    "@stacksjs/path": "0.74.36",
-    "@stacksjs/router": "0.74.36",
-    "@stacksjs/storage": "0.74.36",
-    "@stacksjs/ts-cloud": "^0.14.0"
+    "@stacksjs/auth": "0.74.38",
+    "@stacksjs/cache": "0.74.38",
+    "@stacksjs/config": "0.74.38",
+    "@stacksjs/database": "0.74.38",
+    "@stacksjs/email": "0.74.38",
+    "@stacksjs/events": "0.74.38",
+    "@stacksjs/path": "0.74.38",
+    "@stacksjs/router": "0.74.38",
+    "@stacksjs/storage": "0.74.38",
+    "@stacksjs/strings": "0.74.38",
+    "@stacksjs/ts-cloud": "^0.15.1"
   },
   "devDependencies": {
     "better-dx": "^0.2.24"