@jterrazz/test 10.0.0 → 10.1.0

package/dist/index.d.ts

@@ -591,6 +591,11 @@ interface Visitor {
 type VisitScenario = (visitor: Visitor) => Promise<void>;
 /** Per-visit options forwarded to the browser context. */
 interface BrowserOpenOptions {
+  /**
+   * Extra origins the `external: 'block'` policy lets through — the
+   * declared stub backend the page legitimately fetches from.
+   */
+  allowedOrigins?: string[];
   /**
    * Base URL of the site under test — the origin `goto()` resolves against
    * and the boundary of the `external` policy.
@@ -644,6 +649,107 @@ interface BrowserPort {
   open: (url: string, options: BrowserOpenOptions) => Promise<BrowserPage>;
 }
 //#endregion
+//#region src/core/ports/device.port.d.ts
+/**
+ * The element kinds a mobile screen can designate — the structural subset of
+ * {@link ElementRef} kinds that map onto the XCUITest accessibility tree.
+ * There is ONE element vocabulary across facets: `button('Bookmark')` works
+ * in a visit scenario and a mobile scenario alike. Landmarks have no iOS
+ * analog — passing one to a mobile verb refuses at runtime.
+ */
+type MobileElementKind = 'button' | 'field' | 'testId' | 'text';
+/**
+ * A user-facing element descriptor for mobile scenarios — pure data, built by
+ * the shared element vocabulary (`button()`, `field()`, `content()`,
+ * `testId()`, `within()`) and translated into iOS predicate strings by the
+ * device integration. Structurally the same ref type as the browser's, so the
+ * vocabulary stays single; kinds outside {@link MobileElementKind} (the ARIA
+ * landmarks) are refused at runtime with a message naming the boundary.
+ *
+ * A descriptor must designate exactly ONE element when a verb ACTS on it
+ * (`tap`, `fill`) — see {@link MobileElementMatch} and CONVENTIONS W3.
+ * `see()` acts on nothing, so any visible match satisfies it: XCUITest trees
+ * legitimately duplicate a label across container and child.
+ */
+type MobileElementRef = ElementRef;
+/**
+ * One candidate captured when a descriptor matched more than one element —
+ * the evidence the ambiguity error enumerates so the author can disambiguate
+ * without opening the simulator.
+ */
+interface MobileElementMatch {
+  /** The accessibility identifier (`testId()` target), when one is set. */
+  identifier?: string;
+  /** The accessible label, whitespace-collapsed and truncated. */
+  label?: string;
+  /** Element type without the `XCUIElementType` prefix — `Button`, `StaticText`. */
+  type: string;
+  /** The element value (text-field content, adjustable value), when present. */
+  value?: string;
+}
+/**
+ * The visitor — the interaction vocabulary handed to a mobile scenario.
+ * Every verb auto-waits by polling until a visible match exists; acting
+ * verbs then enforce exactly-one (W3), while `see()` — the single
+ * synchronization primitive — is satisfied by any visible match. There is
+ * no sleep and no conditional helper.
+ */
+interface MobileVisitor {
+  /** Fill a text field with a value. */
+  fill: (element: MobileElementRef, value: string) => Promise<void>;
+  /** Wait until the element is visible — the only synchronization primitive. */
+  see: (element: MobileElementRef) => Promise<void>;
+  /** Tap the element. */
+  tap: (element: MobileElementRef) => Promise<void>;
+}
+/** The behavior of an open — the When of the spec; assertions stay in the Then. */
+type MobileScenario = (visitor: MobileVisitor) => Promise<void>;
+/**
+ * One node of the projected accessibility tree — the XCUITest page source
+ * with its noise collapsed: unlabeled, identifier-less, valueless wrapper
+ * nodes are dropped and their children hoisted, so the projection stays
+ * stable and golden-friendly. Type names lose the `XCUIElementType` prefix.
+ */
+interface ScreenNode {
+  children?: ScreenNode[];
+  /** The accessibility identifier, only when it differs from the label. */
+  identifier?: string;
+  label?: string;
+  /** Element type without the `XCUIElementType` prefix — `Button`, `StaticText`. */
+  type: string;
+  value?: string;
+}
+/**
+ * The screen captured by a device open — the FINAL state when a scenario
+ * ran. The tree is the projected page source; `texts` are the visible
+ * labels/values in document order, consecutive duplicates collapsed.
+ */
+interface DeviceScreen {
+  texts: string[];
+  tree: ScreenNode;
+}
+/** Per-open options forwarded to the device session. */
+interface DeviceOpenOptions {
+  /** The app under test — terminated and relaunched for a fresh, deterministic state. */
+  bundleId: string;
+  /** Deep link applied after the relaunch (`news://events`); absent opens the app plainly. */
+  deepLink?: string;
+  /** The interaction scenario to run after launch; the capture reflects the final state. */
+  scenario?: MobileScenario;
+}
+/**
+ * Abstract device interface for the mobile specification runner.
+ * One implementation lives in `integrations/appium/` — a single driver
+ * session per runner, created on the first `open()` and reused; each open
+ * terminates and relaunches the app for a deterministic fresh state.
+ */
+interface DevicePort {
+  /** End the driver session (idempotent). */
+  close: () => Promise<void>;
+  /** Relaunch the app, apply the deep link, run the scenario, capture the final screen. */
+  open: (options: DeviceOpenOptions) => Promise<DeviceScreen>;
+}
+//#endregion
 //#region src/core/ports/isolation.port.d.ts
 /**
  * Strategy for isolating service state across parallel test workers.
@@ -771,6 +877,27 @@ declare class HttpResult extends BaseResult {
   get status(): number;
 }
 //#endregion
+//#region src/core/specification/mobile/result.d.ts
+/** Result from a `.open()` action — the screen as the device saw it, final state. */
+declare class ScreenResult extends BaseResult {
+  private readonly capturedScreen;
+  constructor(options: {
+    config: SpecificationConfig;
+    screen: DeviceScreen;
+    testDir: string;
+  });
+  /**
+   * The visible screen texts as one stream, in reading order — the scalpel
+   * for a targeted probe: `expect(result.content).toContain('Bookmarked')`.
+   */
+  get content(): TextAccessor;
+  /**
+   * The projected accessibility tree as a JSON accessor — the one golden
+   * per screen: `expect(result.screen).toMatch('events.screen.json')`.
+   */
+  get screen(): JsonAccessor;
+}
+//#endregion
 //#region src/core/specification/website/result.d.ts
 /** A raw HTTP exchange captured by `.fetch()` — redirects are NOT followed. */
 interface FetchExchange {
@@ -848,6 +975,78 @@ declare class PageResult extends BaseResult {
   get url(): string;
 }
 //#endregion
+//#region src/core/http-files/intercept-file.d.ts
+/** The declared request half of an exchange — the matching trigger. */
+interface ExchangeRequest {
+  /** Declared header subset — names case-insensitive, values may carry `{{token}}`s. */
+  headers: Record<string, string>;
+  method: string;
+  /** Path as written, query string included (`/articles?event_id=…`). */
+  path: string;
+}
+/** The declared response half of an exchange — the stubbed reply. */
+interface ExchangeResponse {
+  /** Parsed JSON body — or the raw text when the body is not valid JSON. */
+  body: unknown;
+  /** True when a body section is present. */
+  hasBody: boolean;
+  headers: Record<string, string>;
+  status: number;
+}
+/** One declared request/response pair of an `intercepts/*.http` file. */
+interface InterceptExchange {
+  request: ExchangeRequest;
+  response: ExchangeResponse;
+}
+//#endregion
+//#region src/core/specification/shared/stub-backend.d.ts
+/** Options for the stub backend server. */
+interface StubBackendOptions {
+  /**
+   * Fixed port — pins a stable stub URL across runs (a bundler that inlines
+   * the URL at serve time survives warm). Default: a free OS-assigned port.
+   */
+  port?: number;
+}
+declare class StubBackend {
+  private consumed;
+  private entries;
+  /** Guarded once the current chain declared at least one intercept. */
+  private guarded;
+  private readonly options;
+  private server;
+  private readonly unmatchedRequests;
+  private url;
+  constructor(options?: StubBackendOptions);
+  /** Start the server and resolve with its base URL. */
+  start(): Promise<string>;
+  /** Stop the server (idempotent). */
+  stop(): Promise<void>;
+  /**
+   * Arm the stub for one chain: the declared exchanges replace the previous
+   * chain's wholesale, consumption restarts, and the unmatched log clears —
+   * the reset-between-chains databases already follow.
+   */
+  beginChain(exchanges: InterceptExchange[]): void;
+  /**
+   * The strict failure for the chain, or null — non-null when the chain
+   * declared at least one intercept AND an unmatched request was recorded.
+   * Enumerates every unmatched request (method, path, count) plus the
+   * declared routes, so the missing exchange writes itself.
+   */
+  violation(): Error | null;
+  private corsHeaders;
+  private describeRoutes;
+  private handle;
+  private record;
+  /**
+   * FIFO with a sticky tail: the first unconsumed matching exchange is
+   * consumed; when every matching exchange is spent, the LAST one keeps
+   * replying.
+   */
+  private take;
+}
+//#endregion
 //#region src/core/specification/shared/builder.d.ts
 /** A named job that can be triggered via jobs.trigger(). */
 interface JobHandle {
@@ -867,6 +1066,16 @@ interface DockerSpecConfig {
 }
 /** Adapter configuration passed to the specification facets at setup time. */
 interface SpecificationConfig {
+  /**
+   * The declared stub backend (website/mobile facets) — armed with the
+   * chain's `.http` intercept exchanges before every terminal action.
+   */
+  backend?: StubBackend;
+  /**
+   * Base URL of the running stub backend — allow-listed through the
+   * browser's `external: 'block'` policy so client-side fetches reach it.
+   */
+  backendUrl?: string;
   /** Base URL of the website under test (website facet only). */
   baseUrl?: string;
   /**
@@ -881,6 +1090,8 @@ interface SpecificationConfig {
    * of strict intercepts.
    */
   external?: 'allow' | 'block';
+  /** Bundle id of the app under test (mobile facet only) — the app `.open()` relaunches. */
+  bundleId?: string;
   command?: CliPort;
   database?: DatabasePort;
   /**
@@ -890,6 +1101,13 @@ interface SpecificationConfig {
    */
   databaseKeys?: string[];
   databases?: Map<string, DatabasePort>;
+  /**
+   * Lazy device accessor (mobile facet only). The first `.open()` creates
+   * the shared driver session; the appium/webdriverio integration stays a
+   * lazy import so the optional peer is only loaded when a spec opens the
+   * app.
+   */
+  device?: () => Promise<DevicePort>;
   dockerConfig?: DockerSpecConfig;
   /**
    * Unique id shared by every spec from this runner instance.
@@ -929,8 +1147,8 @@ interface SpecificationConfig {
 interface ApiSpecification<DatabaseKey extends string = string> {
   /** Set HTTP headers for the request. Multiple calls merge. */
   headers: (headers: Record<string, string>) => ApiSpecification<DatabaseKey>;
-  /** Intercept an outgoing HTTP call — a contract, an array of contracts, or a trigger + response pair. */
-  intercept: ((contractOrContracts: InterceptContract | InterceptContract[]) => ApiSpecification<DatabaseKey>) & ((trigger: InterceptTrigger, response: InterceptResponder | InterceptResponse | string) => ApiSpecification<DatabaseKey>);
+  /** Intercept an outgoing HTTP call — a contract, an array of contracts, an `intercepts/*.http` file, or a trigger + response pair. */
+  intercept: ((contractOrContracts: InterceptContract | InterceptContract[] | string) => ApiSpecification<DatabaseKey>) & ((trigger: InterceptTrigger, response: InterceptResponder | InterceptResponse | string) => ApiSpecification<DatabaseKey>);
   /** Queue a SQL seed file from `seeds/` to run before the action. */
   seed: (file: string, options?: {
     database?: DatabaseKey;
@@ -951,8 +1169,8 @@ interface ApiSpecification<DatabaseKey extends string = string> {
  * Jobs run in-process by definition (CONVENTIONS A5/A8).
  */
 interface JobsSpecification<DatabaseKey extends string = string> {
-  /** Intercept an outgoing HTTP call — a contract, an array of contracts, or a trigger + response pair. */
-  intercept: ((contractOrContracts: InterceptContract | InterceptContract[]) => JobsSpecification<DatabaseKey>) & ((trigger: InterceptTrigger, response: InterceptResponder | InterceptResponse | string) => JobsSpecification<DatabaseKey>);
+  /** Intercept an outgoing HTTP call — a contract, an array of contracts, an `intercepts/*.http` file, or a trigger + response pair. */
+  intercept: ((contractOrContracts: InterceptContract | InterceptContract[] | string) => JobsSpecification<DatabaseKey>) & ((trigger: InterceptTrigger, response: InterceptResponder | InterceptResponse | string) => JobsSpecification<DatabaseKey>);
   /** Queue a SQL seed file from `seeds/` to run before the action. */
   seed: (file: string, options?: {
     database?: DatabaseKey;
@@ -998,6 +1216,12 @@ interface CliSpecification<DatabaseKey extends string = string> {
 interface WebsiteSpecification {
   /** Set HTTP headers for the exchange (incl. User-Agent overrides). Multiple calls merge. */
   headers: (headers: Record<string, string>) => WebsiteSpecification;
+  /**
+   * Declare the chain's backend exchanges from an `intercepts/<name>.http`
+   * file — served by the declared stub backend (requires the runner's
+   * `backend` option). Multiple calls layer in order.
+   */
+  intercept: (file: string) => WebsiteSpecification;
   /** Perform one raw HTTP GET — redirects surface as 3xx results, never followed. */
   fetch: (path: string) => Promise<FetchResult>;
   /**
@@ -1007,6 +1231,26 @@ interface WebsiteSpecification {
    */
   visit: (path: string, scenario?: VisitScenario) => Promise<PageResult>;
 }
+/**
+ * The `mobile` facet — screen chain entry handed out by
+ * `specification.mobile()`. `.open()` is the single, terminal action: it
+ * terminates and relaunches the app (deterministic fresh state), applies the
+ * deep link, runs the scenario, and captures the final screen.
+ */
+interface MobileSpecification {
+  /**
+   * Declare the chain's backend exchanges from an `intercepts/<name>.http`
+   * file — served by the declared stub backend (requires the runner's
+   * `backend` option). Multiple calls layer in order.
+   */
+  intercept: (file: string) => MobileSpecification;
+  /**
+   * Relaunch the app and resolve with the captured screen. With a deep
+   * link, the app opens on it; with a scenario, the visitor interacts
+   * first (the When) and the capture reflects the FINAL screen state.
+   */
+  open: (deepLink?: string, scenario?: MobileScenario) => Promise<ScreenResult>;
+}
 //#endregion
 //#region src/core/specification/cli/result.d.ts
 /**
@@ -1358,6 +1602,72 @@ interface JobsHandle<DatabaseKey extends string = string> {
 }
 declare function startJobs<Services extends ServiceRecord>(options: JobsSpecificationOptions<Services>): Promise<JobsHandle<DatabaseKeys<Services>>>;
 //#endregion
+//#region src/core/specification/mobile/start-mobile.d.ts
+/**
+ * The declared stub backend behind the app under test. The framework owns
+ * the simulator and appium but NOT the JS bundler (Metro belongs to the
+ * caller's repo, like `next build` belongs to a website's) — so nothing is
+ * injected: the handle exposes `backendUrl` and the CALLER wires it into its
+ * own bundler env.
+ */
+interface MobileBackendOptions {
+  /**
+   * Fixed port — pins a stable stub URL across runs. Metro inlines
+   * `EXPO_PUBLIC_*` values at bundle-serve time; a stable port lets a warm
+   * Metro survive between runs. Default: a free OS-assigned port.
+   */
+  port?: number;
+}
+/** Options for {@link startMobile | specification.mobile}. */
+interface MobileSpecificationOptions {
+  /** The app under test — terminated and relaunched by every `.open()`. */
+  app: {
+    /** Bundle id of the installed app (`com.example.app`). */
+    bundleId: string;
+  };
+  /**
+   * Declared stub backend: started with the runner, serving the exchanges
+   * each chain declares via `.intercept('<name>.http')`. The handle gains
+   * `backendUrl` — inject it into your bundler env yourself.
+   */
+  backend?: MobileBackendOptions;
+  /** The simulator to run on — resolved through `xcrun simctl`. */
+  device: {
+    /** Simulator name, matched exactly (`iPhone 17`). */
+    name: string;
+    /** OS narrowing when the name exists on several runtimes — `'26.5'` or `'iOS 26.5'`. */
+    os?: string;
+    /** Explicit UDID — skips name/os resolution entirely. */
+    udid?: string;
+  };
+  /**
+   * Project-root override (CONVENTIONS A9): where the appium binary is
+   * resolved from (`node_modules/.bin`). Auto-discovered from the calling
+   * file when absent.
+   */
+  root?: string;
+}
+/**
+ * The record returned by {@link startMobile | specification.mobile}.
+ * Destructure with the canonical names (CONVENTIONS A3):
+ *
+ *     const { mobile, cleanup, udid } = await specification.mobile(…);
+ */
+interface MobileHandle {
+  /**
+   * Base URL of the declared stub backend — present only with the
+   * `backend` option. The caller injects it into its own bundler env
+   * (e.g. `EXPO_PUBLIC_API_URL`); the framework never touches the bundler.
+   */
+  backendUrl?: string;
+  /** End the driver session, stop the appium server and the stub backend. */
+  cleanup: () => Promise<void>;
+  mobile: MobileSpecification;
+  /** The resolved simulator UDID the specs run against. */
+  udid: string;
+}
+declare function startMobile(options: MobileSpecificationOptions): Promise<MobileHandle>;
+//#endregion
 //#region src/core/specification/website/serve.adapter.d.ts
 /** Options for the local server started by `specification.website()`. */
 interface ServeOptions {
@@ -1372,11 +1682,25 @@ interface ServeOptions {
 }
 //#endregion
 //#region src/core/specification/website/start-website.d.ts
+/**
+ * The declared stub backend behind the site under test — started before the
+ * server command, torn down with the runner. Its URL is injected into the
+ * server child's environment under `env`; the chain's
+ * `.intercept('<name>.http')` exchanges are what it serves.
+ */
+interface WebsiteBackendOptions {
+  /** Env var receiving the stub's URL in the server child (e.g. `'API_URL'`). */
+  env: string;
+  /** Fixed port — pins a stable stub URL across runs. Default: a free OS-assigned port. */
+  port?: number;
+}
 /**
  * Options for {@link startWebsite | specification.website}. `server` (start
  * the site locally) and `url` (target a running site) are mutually
  * exclusive BY TYPE — the union makes the invalid combinations
- * inexpressible rather than runtime-checked.
+ * inexpressible rather than runtime-checked. `backend` requires `server`
+ * mode for the same reason: a deployed site cannot be pointed at a local
+ * stub.
  */
 type WebsiteSpecificationOptions = {
   /**
@@ -1391,6 +1715,12 @@ type WebsiteSpecificationOptions = {
    */
   root?: string;
 } & ({
+  /**
+   * Declared stub backend: started BEFORE the server command, its
+   * URL injected into the child env under `backend.env`. Serves the
+   * exchanges each chain declares via `.intercept('<name>.http')`.
+   */
+  backend?: WebsiteBackendOptions;
   /**
    * Start the site locally: a shell command receiving a free port
    * as `PORT`, polled on `ready` (default `/`) until it answers.
@@ -1398,6 +1728,7 @@ type WebsiteSpecificationOptions = {
   server: ServeOptions;
   url?: never;
 } | {
+  backend?: never;
   server?: never;
   /** Target an already-running site (a deployed or preview URL). */
   url: string;
@@ -1419,7 +1750,7 @@ declare function startWebsite(options: WebsiteSpecificationOptions): Promise<Web
 //#endregion
 //#region src/core/specification/shared/specification.d.ts
 /**
- * The three specification constructors (CONVENTIONS A2) — created in a
+ * The five specification constructors (CONVENTIONS A2) — created in a
  * `*.specification.ts` file under `specs/`, destructured with canonical
  * names, and cleaned up via `afterAll(cleanup)` (A1/A3/A4).
  *
@@ -1462,6 +1793,13 @@ declare const specification: {
    * server, no mode. `.trigger(name)` is the terminal action.
    */
   jobs: typeof startJobs;
+  /**
+   * Test a native app on the iOS simulator. `device` names the simulator
+   * (resolved and booted via `simctl`); `app` names the bundle under
+   * test. `.open(deepLink?, scenario?)` relaunches the app fresh, runs
+   * the scenario, and captures the final screen.
+   */
+  mobile: typeof startMobile;
   /**
    * Test a deployed or locally-served website. `server` starts the site
    * (a shell command receiving `PORT`); `url` targets a running one.
@@ -1891,4 +2229,4 @@ declare module 'vitest' {
   }
 }
 //#endregion
-export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, BaseResult, type BrowserConsoleMessage, type BrowserLinkElement, type BrowserMetaElement, type BrowserOpenOptions, type BrowserPage, type BrowserPort, type CaptureScope, type CliEnv, type CliHandle, type CliOutput, type CliPort, CliResult, type CliSpecification, type CliSpecificationOptions, ContainerAccessor, type ContainerPort, type DatabaseKeys, type DatabasePort, DirectoryAccessor, type DockerSpecConfig, type ElementKind, type ElementMatch, type ElementOptions, type ElementRef, type ExecOptions, FetchResult, type FileAccessor, FilesystemAccessor, type HonoApp, HttpResult, type InterceptContract, type InterceptEntry, type InterceptResponder, type InterceptResponse, type InterceptResponseValue, type InterceptTrigger, type IsolationStrategy, type JobHandle, type JobsHandle, type JobsSpecification, type JobsSpecificationOptions, JsonAccessor, type LandmarkKind, type MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MockDatePort, type MockPort, Orchestrator, PageResult, type PostgresOptions, type RedisOptions, ResponseAccessor, type ServeOptions, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecificationConfig, type SpecificationMode, type SqliteOptions, TableAccessor, TextAccessor, type VisitScenario, type Visitor, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, anthropic, banner, button, complementary, content, contentinfo, defineContract, field, findContainersByLabel, form, heading, http, inspectContainer, link, main, match, mockOf, mockOfDate, navigation, openai, postgres, redis, region, removeContainers, search, specification, sqlite, testId, text, within };
+export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, BaseResult, type BrowserConsoleMessage, type BrowserLinkElement, type BrowserMetaElement, type BrowserOpenOptions, type BrowserPage, type BrowserPort, type CaptureScope, type CliEnv, type CliHandle, type CliOutput, type CliPort, CliResult, type CliSpecification, type CliSpecificationOptions, ContainerAccessor, type ContainerPort, type DatabaseKeys, type DatabasePort, type DeviceOpenOptions, type DevicePort, type DeviceScreen, DirectoryAccessor, type DockerSpecConfig, type ElementKind, type ElementMatch, type ElementOptions, type ElementRef, type ExecOptions, FetchResult, type FileAccessor, FilesystemAccessor, type HonoApp, HttpResult, type InterceptContract, type InterceptEntry, type InterceptResponder, type InterceptResponse, type InterceptResponseValue, type InterceptTrigger, type IsolationStrategy, type JobHandle, type JobsHandle, type JobsSpecification, type JobsSpecificationOptions, JsonAccessor, type LandmarkKind, type MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MobileBackendOptions, type MobileElementKind, type MobileElementMatch, type MobileElementRef, type MobileHandle, type MobileScenario, type MobileSpecification, type MobileSpecificationOptions, type MobileVisitor, type MockDatePort, type MockPort, Orchestrator, PageResult, type PostgresOptions, type RedisOptions, ResponseAccessor, type ScreenNode, ScreenResult, type ServeOptions, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecificationConfig, type SpecificationMode, type SqliteOptions, TableAccessor, TextAccessor, type VisitScenario, type Visitor, type WebsiteBackendOptions, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, anthropic, banner, button, complementary, content, contentinfo, defineContract, field, findContainersByLabel, form, heading, http, inspectContainer, link, main, match, mockOf, mockOfDate, navigation, openai, postgres, redis, region, removeContainers, search, specification, sqlite, testId, text, within };