@zerotal/testing 1.6.3 → 1.7.2

package/api-surface.md

@@ -0,0 +1,360 @@
+# @zerotal/testing — public API surface
+
+<!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
+     Run `bun run api:surface` to regenerate after an intentional API change. -->
+
+## .  `(./src/index.ts)`
+
+class EventFake = {
+  new (_app: Application, _original: Binding<unknown> | undefined): EventFake
+  static install: () => EventFake
+  assertEmitted: <T extends object>(EventType: EventClass<T>, filter?: (event: T) => boolean) => void
+  assertEmittedCount: <T extends object>(EventType: EventClass<T>, count: number) => void
+  assertNotEmitted: <T extends object>(EventType: EventClass<T>, filter?: (event: T) => boolean) => void
+  assertNothingEmitted: () => void
+  clear: () => void
+  dispatchQueuedListener: (listenerName: string, eventPayload: any) => Promise<void>
+  emit: <T extends object>(event: T) => Promise<void>
+  emitSync: <T extends object>(event: T) => Promise<void>
+  emitted: () => object[]
+  emittedOf: <T extends object>(EventType: EventClass<T>) => T[]
+  hasListeners: <T extends object>(eventClass: new (...args: unknown[]) => T) => boolean
+  off: <T extends object>(eventClass: new (...args: unknown[]) => T, listenerClass: new (...args: unknown[]) => {    handle(event: T): Promise<void> | void;    queue?: boolean | string;    maxAttempts?: number;    retryDelay?: number;}) => void
+  on: <T extends object>(eventClass: new (...args: unknown[]) => T, listenerClass: new (...args: unknown[]) => {    handle(event: T): Promise<void> | void;    queue?: boolean | string;    maxAttempts?: number;    retryDelay?: number;}) => void
+  registrations: () => Array<{    event: string;    listeners: string[];}>
+  restore: () => void
+  setBroadcaster: (fn: ((event: object) => void) | null) => void
+}
+
+class Factory = {
+  new <T extends BaseModel>(_ModelClass: ModelCtor<T>, _definition: DefinitionFn<T>, _config: FactoryConfig<T>): Factory<T>
+  static define: <T extends BaseModel>(ModelClass: ModelCtor<T>, definition: DefinitionFn<T>) => Factory<T>
+  afterCreate: (callback: (instance: T) => Promise<void> | void) => Factory<T>
+  count: (n: number) => FactoryBatch<T>
+  create: (overrides?: Partial<InsertPayload<T>>) => Promise<T>
+  createMany: (n: number, overrides?: Partial<InsertPayload<T>>) => Promise<T[]>
+  dispatchEvents: () => Factory<T>
+  for: (model: BaseModel, foreignKey?: string) => Factory<T>
+  make: (overrides?: Partial<InsertPayload<T>>) => T
+  state: (stateName: string) => Factory<T>
+}
+
+class FactoryBatch = {
+  new <T extends BaseModel>(_ModelClass: ModelCtor<T>, _definition: DefinitionFn<T>, _config: FactoryConfig<T>, _n: number): FactoryBatch<T>
+  afterCreate: (callback: (instance: T) => Promise<void> | void) => FactoryBatch<T>
+  create: (overrides?: Partial<InsertPayload<T>>) => Promise<T[]>
+  dispatchEvents: () => FactoryBatch<T>
+  for: (model: BaseModel, foreignKey?: string) => FactoryBatch<T>
+  state: (stateName: string) => FactoryBatch<T>
+}
+
+class FakeDisk = {
+  new (baseUrl?: string): FakeDisk
+  append: (path: string, content: string | Uint8Array) => Promise<void>
+  assertContentType: (path: string, contentType: string) => FakeDisk
+  assertCount: (expected: number) => FakeDisk
+  assertExists: (path: string, contents?: string | Uint8Array) => FakeDisk
+  assertExistsMatching: (pattern: RegExp) => FakeDisk
+  assertMissing: (path: string) => FakeDisk
+  assertNothingStored: () => FakeDisk
+  clear: () => void
+  copy: (source: string, destination: string) => Promise<void>
+  count: number
+  delete: (path: string) => Promise<void>
+  exists: (path: string) => Promise<boolean>
+  file: (path: string) => FakeStoredFile | undefined
+  get: (path: string) => Promise<string | null>
+  getBuffer: (path: string) => Promise<Uint8Array | null>
+  lastModified: (path: string) => Promise<number | null>
+  move: (source: string, destination: string) => Promise<void>
+  paths: () => string[]
+  put: (path: string, content: string | Uint8Array | Blob, options?: PutOptions) => Promise<void>
+  size: (path: string) => Promise<number | null>
+  stream: (path: string) => Promise<Blob | null>
+  temporaryUrl: (path: string, expiresInSeconds: number) => Promise<string>
+  url: (path: string) => string
+}
+
+class Http = {
+  new (): Http
+  static assertNotSent: (predicate: (req: {    method: string;    url: string;}) => boolean) => void
+  static assertNothingSent: () => void
+  static assertSent: (predicate: (req: {    method: string;    url: string;}) => boolean) => void
+  static assertSentCount: (count: number) => void
+  static delete: (url: string) => PendingRequest
+  static fake: (stubs?: FakeStub[]) => void
+  static get: (url: string) => PendingRequest
+  static head: (url: string) => PendingRequest
+  static patch: (url: string, data?: unknown) => PendingRequest
+  static post: (url: string, data?: unknown) => PendingRequest
+  static put: (url: string, data?: unknown) => PendingRequest
+  static recorded: () => Array<{    method: string;    url: string;    options: RequestInit;}>
+  static resetFakes: () => void
+  static retry: (times: number, delay?: number) => _Builder
+  static timeout: (milliseconds: number) => _Builder
+  static withBasicAuth: (username: string, password: string) => _Builder
+  static withHeaders: (headers: Record<string, string>) => _Builder
+  static withToken: (token: string) => _Builder
+}
+
+class NotificationFake = {
+  new (app: Application, original: Binding): NotificationFake
+  static install: () => NotificationFake
+  assertNotSentTo: <T extends Notification>(notifiable: Notifiable, NotificationClass: new (...args: never[]) => T) => void
+  assertNothingSent: () => void
+  assertQueued: <T extends Notification>(notifiable: Notifiable, NotificationClass: new (...args: never[]) => T) => void
+  assertSentCount: (count: number) => void
+  assertSentOn: <T extends Notification>(notifiable: Notifiable, NotificationClass: new (...args: never[]) => T, channel: string) => void
+  assertSentTimes: <T extends Notification>(NotificationClass: new (...args: never[]) => T, count: number) => void
+  assertSentTo: <T extends Notification>(notifiable: Notifiable, NotificationClass: new (...args: never[]) => T, callback?: (notification: T) => boolean) => void
+  channels: () => string[]
+  database: {    all(): Promise<NotificationRecord[]>;    unread(): Promise<NotificationRecord[]>;    unreadCount(): Promise<number>;    markAllAsRead(): Promise<void>;    markAsRead(): Promise<void>;    markAsUnread(): Promise<void>;    delete(): Promise<void>;    clear(): Promise<void>;}
+  extend: () => NotificationFake
+  queue: (notifiable: Notifiable, notification: Notification) => Promise<void>
+  queueMany: (notifiables: Iterable<Notifiable>, notification: Notification) => Promise<void>
+  restore: () => void
+  route: (routes: OnDemandRoutes) => {    notify(notification: Notification): Promise<void>;    notifyLater(notification: Notification): Promise<void>;}
+  send: (notifiable: Notifiable, notification: Notification) => Promise<void>
+  sendMany: (notifiables: Iterable<Notifiable>, notification: Notification) => Promise<void>
+  sent: () => CapturedNotification[]
+  sentTo: (notifiable: Notifiable) => CapturedNotification[]
+}
+
+class QueueFake = {
+  new (app: Application, original: Binding): QueueFake
+  static install: () => QueueFake
+  assertDispatched: <T extends Job>(JobClass: new (...args: never[]) => T, callback?: (job: T) => boolean) => void
+  assertDispatchedCount: (count: number) => void
+  assertNotDispatched: <T extends Job>(JobClass: new (...args: never[]) => T) => void
+  assertNothingDispatched: () => void
+  dispatch: (job: Job) => Promise<void>
+  dispatched: () => Job[]
+  drain: () => Promise<void>
+  flush: () => Promise<void>
+  isShuttingDown: boolean
+  processNext: () => Promise<boolean>
+  restore: () => void
+  size: () => Promise<number>
+}
+
+class TestApp = {
+  new (_app: Application, _errors?: TestExceptionHandler | undefined): TestApp
+  _shared: boolean
+  actingAs: (user: {    id: number | string;}) => TestApp
+  actingAsGuest: () => TestApp
+  app: Application
+  asJson: () => TestApp
+  baseUrl: string
+  close: () => Promise<void>
+  delete: (url: string, headers?: Record<string, string>) => Promise<TestResponse>
+  followingRedirects: () => TestApp
+  get: (url: string, headers?: Record<string, string>) => Promise<TestResponse>
+  head: (url: string, headers?: Record<string, string>) => Promise<TestResponse>
+  multipart: (url: string, body?: Record<string, TestFormValue>, headers?: Record<string, string>, method?: 'POST' | 'PUT' | 'PATCH') => Promise<TestResponse>
+  options: (url: string, headers?: Record<string, string>) => Promise<TestResponse>
+  patch: (url: string, body: unknown, headers?: Record<string, string>) => Promise<TestResponse>
+  patchForm: (url: string, body?: Record<string, TestFormValue>, headers?: Record<string, string>) => Promise<TestResponse>
+  port: number
+  post: (url: string, body: unknown, headers?: Record<string, string>) => Promise<TestResponse>
+  postForm: (url: string, body?: Record<string, TestFormValue>, headers?: Record<string, string>) => Promise<TestResponse>
+  put: (url: string, body: unknown, headers?: Record<string, string>) => Promise<TestResponse>
+  putForm: (url: string, body?: Record<string, TestFormValue>, headers?: Record<string, string>) => Promise<TestResponse>
+  request: (url: string, init?: RequestInit) => Promise<TestResponse>
+  withCookie: (name: string, value: string) => TestApp
+  withCookies: (cookies: Record<string, string>) => TestApp
+  withExceptionHandling: () => TestApp
+  withHeaders: (headers: Record<string, string>) => TestApp
+  withSession: (data: Record<string, unknown>) => TestApp
+  withoutCookies: () => TestApp
+  withoutExceptionHandling: () => TestApp
+  withoutFollowingRedirects: () => TestApp
+}
+
+class TestResponse = {
+  new (_res: Response, _body: string, context?: TestResponseContext & { decodedSession?: Record<string, unknown> | null | undefined; }): TestResponse
+  static of: (res: Response, context?: TestResponseContext) => Promise<TestResponse>
+  assertAuthenticated: () => TestResponse
+  assertAuthenticatedAs: (user: {    id: number | string;} | number | string) => TestResponse
+  assertBodyContains: (needle: string) => TestResponse
+  assertCookie: (name: string, value?: string) => TestResponse
+  assertCookieMissing: (name: string) => TestResponse
+  assertCreated: () => TestResponse
+  assertDontSee: (needle: string) => TestResponse
+  assertDontSeeText: (needle: string) => TestResponse
+  assertForbidden: () => TestResponse
+  assertGuest: () => TestResponse
+  assertHeader: (name: string, value?: string) => TestResponse
+  assertHeaderMissing: (name: string) => TestResponse
+  assertInertia: (component?: string, props?: Record<string, unknown>) => TestResponse
+  assertInertiaProp: (key: string, value?: unknown) => TestResponse
+  assertInvalid: (fields?: string | string[] | Record<string, string>) => TestResponse
+  assertJson: (expected: Record<string, unknown>) => TestResponse
+  assertJsonCount: (count: number, key?: string) => TestResponse
+  assertJsonPath: (path: string, expected: unknown) => TestResponse
+  assertMovedPermanently: () => TestResponse
+  assertNoContent: () => TestResponse
+  assertNotFound: () => TestResponse
+  assertOk: () => TestResponse
+  assertRedirect: (url: string) => TestResponse
+  assertSee: (needle: string) => TestResponse
+  assertSeeText: (needle: string) => TestResponse
+  assertServerError: () => TestResponse
+  assertSessionHas: (key: string, value?: unknown) => TestResponse
+  assertSessionHasErrors: (fields?: string | string[]) => TestResponse
+  assertSessionHasNoErrors: () => TestResponse
+  assertSessionMissing: (key: string) => TestResponse
+  assertStatus: (expected: number) => TestResponse
+  assertSuccessful: () => TestResponse
+  assertUnauthorized: () => TestResponse
+  assertUnprocessable: () => TestResponse
+  assertValid: (fields?: string | string[]) => TestResponse
+  exception: () => unknown
+  headers: Headers
+  inertia: () => InertiaPage | null
+  json: <T = unknown>() => T
+  ok: boolean
+  session: () => Record<string, unknown> | null
+  status: number
+  text: () => string
+  validationErrors: () => Record<string, string[]> | null
+}
+
+const fake = {    pick<T>(arr: readonly T[]): T;    shuffle<T>(arr: readonly T[]): T[];    sample<T>(arr: readonly T[], n: number): T[];    number(min?: number, max?: number): number;    float(min?: number, max?: number, decimals?: number): number;    boolean(trueWeight?: number): boolean;    uuid(): string;    string(length?: number): string;    maybe<T>(value: T, probability?: number): T | null;    date(from?: Date, to?: Date): Date;    pastDate(years?: number): Date;    futureDate(years?: number): Date;    isoDate(from?: Date, to?: Date): string;    timestamp(): number;    firstName(): string;    lastName(): string;    name(): string;    email(opts?: {        name?: string;        corporate?: boolean;        number?: boolean;    }): string;    phone(): string;    city(): string;    province(): string;    suburb(): string;    streetAddress(): string;    postalCode(): string;    address(): string;    company(): string;    jobTitle(): string;    department(): string;    word(): string;    words(n?: number): string;    sentence(opts?: {        length?: TextLength;        words?: number;    }): string;    sentences(n?: number, opts?: {        length?: TextLength;    }): string;    paragraph(opts?: {        length?: TextLength;    }): string;    paragraphs(n?: number, opts?: {        length?: TextLength;    }): string;    title(): string;    slug(text?: string): string;    url(opts?: {        path?: boolean;    }): string;    password(opts?: {        length?: number;        simple?: boolean;    }): string;}
+
+const fakeFile = {    create(name: string, content?: string | Uint8Array, type?: string): File;    sized(name: string, size: number, type?: string): File;    image(name?: string, options?: {        width?: number;        height?: number;    }): File;    jpeg(name?: string): File;    gif(name?: string): File;    pdf(name?: string): File;}
+
+function assertDatabaseCount = (table: string, expected: number, where?: Record<string, unknown>) => Promise<void>
+
+function assertDatabaseHas = (table: string, where: Record<string, unknown>) => Promise<void>
+
+function assertDatabaseMissing = (table: string, where: Record<string, unknown>) => Promise<void>
+
+function assertMissingFile = (diskOrDriver: string | StorageDriver, path: string) => Promise<void>
+
+function assertStoredFile = (diskOrDriver: string | StorageDriver, path: string) => Promise<void>
+
+function closeSharedTestApps = () => Promise<void>
+
+function createTestApp = (bootstrap: () => Application | Promise<Application>, setup?: () => void) => Promise<TestApp>
+
+function migrateDatabase = (options?: MigrateDatabaseOptions) => Promise<string[]>
+
+function refreshDatabase = (options?: RefreshDatabaseOptions) => void
+
+function resetTestState = () => void
+
+function withDatabase = (fn: () => Promise<void>) => () => Promise<void>
+
+interface FakeStoredFile = {
+  contentType: string | undefined
+  contents: Uint8Array<ArrayBufferLike>
+  lastModified: number
+  path: string
+  visibility: 'public' | 'private' | undefined
+}
+
+interface InertiaPage = {
+  component: string
+  props: Record<string, unknown>
+  url: string
+  version: string | null
+}
+
+interface MigrateDatabaseOptions = {
+  connection?: SQLInstance
+  path?: string
+  table?: string
+}
+
+interface RefreshDatabaseOptions = {
+  connection?: SQLInstance
+  migrate?: string | boolean
+  setup?: (db: SQLInstance) => void | Promise<void>
+  teardown?: (db: SQLInstance) => void | Promise<void>
+}
+
+interface TestFileInput = {
+  content: string | Uint8Array<ArrayBufferLike> | Blob | File
+  filename?: string
+  type?: string
+}
+
+interface TestResponseContext = {
+  exception?: unknown
+  session?: SessionDecoder | undefined
+}
+
+type FactoryPayload = Omit<InsertPayload<T>, FKKeys<T> & Exclude<{ [K in keyof T]-?: (<G>() => G extends { [P in K]: T[P]; } ? 1 : 2) extends <G>() => G extends { -readonly [P in K]: T[P]; } ? 1 : 2 ? K : never; }[keyof T] & { [K in keyof T & string]-?: K extends `_${string}` ? never : T[K] extends (...args: any[]) => any ? never : NonNullable<T[K]> extends {    readonly __isZerotalModel: true;} | {    readonly __isZerotalModel: true;}[] ? never : K; }[keyof T & string], 'id' | 'createdAt' | 'updatedAt' | 'deletedAt'>> & Partial<Pick<InsertPayload<T>, FKKeys<T> & Exclude<{ [K in keyof T]-?: (<G>() => G extends { [P in K]: T[P]; } ? 1 : 2) extends <G>() => G extends { -readonly [P in K]: T[P]; } ? 1 : 2 ? K : never; }[keyof T] & { [K in keyof T & string]-?: K extends `_${string}` ? never : T[K] extends (...args: any[]) => any ? never : NonNullable<T[K]> extends {    readonly __isZerotalModel: true;} | {    readonly __isZerotalModel: true;}[] ? never : K; }[keyof T & string], 'id' | 'createdAt' | 'updatedAt' | 'deletedAt'>>>
+
+type FakeFile = {    create(name: string, content?: string | Uint8Array, type?: string): File;    sized(name: string, size: number, type?: string): File;    image(name?: string, options?: {        width?: number;        height?: number;    }): File;    jpeg(name?: string): File;    gif(name?: string): File;    pdf(name?: string): File;}
+
+type SessionDecoder = (response: Response) => Promise<Record<string, unknown> | null>
+
+type TestFormValue = string | number | boolean | Blob | File | TestFileInput | null | undefined
+
+## ./browser  `(./src/browser.ts)`
+
+class BrowserPage = {
+  new (view: Bun.WebView, report: TransportReport, timeout: number): BrowserPage
+  attribute: (selector: string, name: string) => Promise<string | null>
+  click: (selector: string) => Promise<BrowserPage>
+  close: () => void
+  connection: () => Promise<string | null>
+  count: (selector: string) => Promise<number>
+  evaluate: <T = unknown>(expression: string) => Promise<T>
+  html: (selector: string) => Promise<string | null>
+  press: (key: string) => Promise<BrowserPage>
+  socketUpgraded: () => boolean
+  text: (selector: string) => Promise<string | null>
+  transport: () => TransportReport
+  type: (selector: string, text: string) => Promise<BrowserPage>
+  url: () => Promise<string>
+  waitFor: (expression: string, timeout?: number) => Promise<BrowserPage>
+  waitForConnection: (timeout?: number) => Promise<BrowserPage>
+  waitForCount: (selector: string, n: number, timeout?: number) => Promise<BrowserPage>
+  waitForPatch: (timeout?: number) => Promise<BrowserPage>
+}
+
+class FlowBrowser = {
+  new (app: TestApp, timeout: number): FlowBrowser
+  static availability: () => Promise<BrowserAvailability>
+  static serve: (bootstrap: () => Application | Promise<Application>, options?: FlowBrowserOptions) => Promise<FlowBrowser>
+  port: number
+  stop: () => Promise<void>
+  url: string
+  visit: (path: string) => Promise<BrowserPage>
+}
+
+const CDP_URL_ENV = 'ZT_BROWSER_CDP_URL'
+
+function browserAvailability = () => Promise<BrowserAvailability>
+
+function browserRequired = () => boolean
+
+interface BrowserAvailability = {
+  available: boolean
+  mode: 'none' | 'spawn' | 'connect'
+  reason: string
+}
+
+interface FlowBrowserOptions = {
+  setup?: () => void
+  timeout?: number
+}
+
+interface ObservedFrame = {
+  direction: 'sent' | 'received'
+  payload: string
+}
+
+interface TransportReport = {
+  created: number
+  errored: boolean
+  frames: ObservedFrame[]
+  statuses: number[]
+  upgraded: number
+}
+
+## ./preload  `(./src/preload.ts)`
+
+_(no exports)_

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/testing",
-  "version": "1.6.3",
+  "version": "1.7.2",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -14,6 +14,7 @@
   },
   "files": [
     "CHANGELOG.md",
+    "api-surface.md",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
@@ -31,14 +32,14 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.6.3",
-    "@zerotal/orm": "1.6.3",
-    "@zerotal/queue": "1.6.3",
-    "@zerotal/notifications": "1.6.3"
+    "@zerotal/core": "1.7.2",
+    "@zerotal/orm": "1.7.2",
+    "@zerotal/queue": "1.7.2",
+    "@zerotal/notifications": "1.7.2"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/session": "1.6.3"
+    "@zerotal/session": "1.7.2"
   },
   "description": "Testing utilities for Zerotal — an in-process test app, HTTP helpers, and database refresh.",
   "keywords": [

package/src/TestApp.ts

@@ -603,6 +603,21 @@ export async function createTestApp(
   // here, the fresh one after its own reset. Adopting before the reset is what is
   // unsafe: it hands back an app whose scope has just been torn down, and the first
   // facade to touch it throws E_FACADE_BEFORE_BOOT.
+  // Declare the runtime mode before anything boots.
+  //
+  // The suite runs under `zt test`, which is a console command, so `APP_TYPE`
+  // arrives as "console". Providers scoped to the test runtime are then filtered
+  // out before a single request is made — `SessionProvider` is `["web", "test"]`,
+  // so a test app had no session at all: flashed validation errors were
+  // unreadable and `assertInvalid()` reported "the response had none", blaming
+  // the app for a binding the harness had excluded. `actingAs()` failed for the
+  // same reason.
+  //
+  // Set rather than defaulted: calling `createTestApp` *is* the declaration that
+  // this process is a test, and the value it would otherwise inherit is the one
+  // that breaks it.
+  Bun.env["APP_TYPE"] = "test";
+
   if (!setup && _sharedApps.size > 0) {
     resetTestState();
     const booted = await bootstrap();