@jterrazz/test 16.1.1 → 18.0.0

package/dist/vitest.d.ts

@@ -1,36 +1,46 @@
+import { a as MobileDevice } from "./shared-device.port.js";
 import { TestProjectInlineConfiguration, ViteUserConfig } from "vitest/config";
 import { UserConfig, UserConfigFn } from "vite";
-//#region src/runner/literate-plugin.d.ts
+//#region src/vitest/project.d.ts
+/** What every helper accepts on top of its canonical project. */
+type SpecificationProjectOptions = {
+  /** Globs to stay out of: added to the preset's on a specification helper, replacing the canonical ones on `unit()` and `component()`. */
+  exclude?: string[];
+  /** Replace the canonical `include` globs. */
+  include?: string[];
+  /** Run files one at a time, for specifications sharing a served app, a database file or a browser profile. */
+  serial?: boolean;
+  /** Raise (or lower) the 30s budget for this project alone: each test's, and each hook's, which tears down what the test stood on. */
+  timeout?: number;
+};
+/** What a specification whose spec files import their runner from its specification modules accepts on top. */
+type RunnerOption = {
+  /** The `*.specification.ts` modules its spec files import their runner from: stated, a worker's files share one module graph and each module runs again before each file, so every file still boots its own subject. */
+  runner?: readonly string[] | string;
+};
+/** What a specification whose runner boots its subject in this process accepts on top. */
+type InProcessProjectOptions = RunnerOption & SpecificationProjectOptions;
+//#endregion
+//#region src/specifications/api/api.project.d.ts
+/** `api()`: the app met through HTTP. */
+type ApiProjectOptions = InProcessProjectOptions;
+export declare function api(options?: ApiProjectOptions): TestProjectInlineConfiguration;
+//#endregion
+//#region src/specifications/cli/documents/literate-plugin.d.ts
 type LiterateOptions = {
-  /**
-   * Globs added to the project's test include. Default: every `.spec.yaml`
-   * file. Narrow it when a tree holds documents that are INPUTS to other
-   * specs (a deliberately-wrong golden) rather than scenarios to run.
-   */
+  /** Globs added to the test include; narrow it when a tree holds documents that are inputs to other specs. */
   include?: string[];
-  /**
-   * Path to the `*.specification.ts` whose exported `cli` runs the files —
-   * relative to the vite root, or absolute.
-   *
-   * It is stated, never guessed: a repository may declare several cli
-   * runners (different binaries, different service records), and there is no
-   * convention that could pick the right one without silently binding a
-   * scenario to the wrong command.
-   */
-  specification: string;
+  /** Path to the `*.specification.ts` whose export named for each document's `kind:` runs it; stated, never guessed. */
+  runner: string;
 };
-/**
- * The shape vite consumes. Declared structurally rather than imported from
- * `vite`, so the package's runner coupling stays the one dependency it already
- * has (CONVENTIONS I1) — the object is assignable to vite's `Plugin`.
- */
+/** Structural, so the runner coupling stays one dependency (the layer map); assignable to vite's `Plugin`. */
 type LiteratePlugin = {
   config: () => {
     test: {
       include: string[];
     };
   };
-  /** Vite hands the resolved root here — what a relative `specification` is resolved against. */
+  /** Vite hands the resolved root here: what a relative `runner` is resolved against. */
   configResolved: (resolved: {
     root: string;
   }) => void;
@@ -38,170 +48,89 @@ type LiteratePlugin = {
   load: (id: string) => null | string;
   name: string;
 };
-declare function literate(options: LiterateOptions): LiteratePlugin;
+export declare function literate(options: LiterateOptions): LiteratePlugin;
 //#endregion
-//#region src/runner/preset.d.ts
-/**
- * Options are a vite/vitest config plus one key of the framework's own.
- * Everything stated here wins over the preset's defaults.
- */
-type SpecConfig = {
-  /**
-   * Turns every matching `<case>.spec.yaml` into a test file bound to the
-   * named specification — the {@link literate} plugin, added to `plugins`.
-   *
-   * Declare it here for a config with no `projects`. With projects, the glob
-   * has to join the include of the ONE project that collects those documents,
-   * so the plugin goes in that project's own `plugins` instead.
-   */
-  literate?: LiterateOptions;
-} & ViteUserConfig;
-declare function defineSpecConfig(config?: SpecConfig): ViteUserConfig;
-//#endregion
-//#region src/runner/facet-project.d.ts
-/**
- * The node facets' canonical projects.
- *
- * Each one collects the facet's own tree — `specs/<facet>/**\/*.spec.ts`, the
- * suffix that says "the assembled product" — carries the preset's budgets and
- * artefact directory, and runs in group 0 — the browser facets follow, so two
- * Chromiums never share a slot on a two-vCPU runner. `{ include, exclude,
- * timeout, serial }` is what a repository states when its tree, its budget or
- * its parallelism differs;
- * everything else is the framework's.
- */
-/** What every helper accepts on top of its canonical project. */
-type FacetProjectOptions = {
-  /**
-   * Globs this project stays out of. On a facet helper they ADD to the
-   * preset's (`_fixtures/` and vitest's own), because vite concatenates. On
-   * `unit()` and `component()`, whose canonical `exclude` exists only to
-   * guard their canonical `include`, stating one replaces it — so state
-   * both or neither there.
-   */
-  exclude?: string[];
-  /** Replace the canonical `include` globs. */
-  include?: string[];
-  /**
-   * Run this project's files ONE AT A TIME (`fileParallelism: false`) — for
-   * the facets whose files share something a second worker would collide
-   * with: one served app, one database file, one browser profile.
-   */
-  serial?: boolean;
-  /** Raise (or lower) the 30s budget for this project alone. */
-  timeout?: number;
-};
-//#endregion
-//#region src/facets/api/api.project.d.ts
-/** `api()` — the app met through HTTP. */
-declare function api(options?: FacetProjectOptions): TestProjectInlineConfiguration;
-//#endregion
-//#region src/facets/cli/cli.project.d.ts
-/** `cli()` — a binary, and the documents that specify it. */
-type CliProjectOptions = FacetProjectOptions & {
-  /**
-   * The literate door, wired by default: every `specs/cli/**\/*.spec.yaml`
-   * becomes a test file bound to `specs/cli/cli.specification.ts`. State
-   * `specification` to name another runner, `include` to narrow the glob, or
-   * `false` to collect no documents at all.
-   */
+//#region src/specifications/cli/cli.project.d.ts
+/** The literate door of the specification that reads documents: the cli. */
+type LiterateDoor = {
+  /** Every `specs/cli/` `.spec.yaml` becomes a test bound to `specs/cli/cli.specification.ts`; `false` collects none. */
   literate?: false | Partial<LiterateOptions>;
 };
-/**
- * A cli project collects the facet's `.test.ts` files AND its documents: a
- * `<case>.spec.yaml` is a test file of its own (docs/07 § the literate door),
- * so the plugin's glob has to join the include of the project that collects
- * them — which is this one, never the root config.
- */
-declare function cli(options?: CliProjectOptions): TestProjectInlineConfiguration;
+/** `cli()`: a binary, and the documents that specify it. */
+type CliProjectOptions = LiterateDoor & RunnerOption & SpecificationProjectOptions;
+/** A cli project: the specification's `.spec.ts` files and its documents (docs/guides/spec-documents.md); the plugin's glob joins this project's include, never the root config. */
+export declare function cli(options?: CliProjectOptions): TestProjectInlineConfiguration;
 //#endregion
-//#region src/facets/component/component.project.d.ts
-/** `component()` — rendered units, beside the components they cover. */
-type ComponentProjectOptions = {
+//#region src/specifications/component/component.project.d.ts
+type ComponentOptions = {
   /** Freeze the page's `Date` for every render of the project. */
   clock?: string;
   /** `Accept-Language` and `Intl` locale of the page. Default `'en-US'`. */
   locale?: string;
-  /**
-   * The directory `vite` and `wrap` are resolved against. Default: the
-   * directory of the file that CALLED the helper — see
-   * {@link callerDirectory}. State it when the call is not written in the
-   * config it configures (a shared config factory).
-   */
-  root?: string;
+  /** The directory `vite` and `wrap` resolve against, absolute; `vitestConfig` hands it the project root, or the `root` a declared project states read from it. */
+  root: string;
   /** IANA zone the page's `Date` reports in. Default `'UTC'`. */
   timezone?: string;
-  /**
-   * The app's own Vite pipeline: a config path, the object, or the function
-   * a framework exports. Only the PIPELINE is adopted (see {@link reroot}).
-   */
+  /** The app's Vite pipeline: a config path, the object, or a framework's function. Only the pipeline is adopted. */
   vite?: Promise<UserConfig> | string | UserConfig | UserConfigFn;
   /** The page size every render gets. Default 1280×720. */
   viewport?: {
     height: number;
     width: number;
   };
-  /**
-   * A module whose default export is `(ui) => ReactNode` — the providers
-   * every render of this project is dressed in (a theme, a store, an intl
-   * provider). A router belongs on the chain instead: it is a test's Given.
-   */
+  /** A module whose default export `(ui) => ReactNode` wraps every render; a router is a test's Given, on the chain. */
   wrap?: string;
-} & FacetProjectOptions;
-/**
- * A component test renders in a real Chromium — the browser the website facet
- * already drives through the same `playwright` peer.
- *
- * The default `include` reaches the whole project, so the default `exclude`
- * keeps it out of `specs/`, where the assembled product is specified. State
- * your own `include` and the exclusion is yours to state too.
- */
-declare function component(options?: ComponentProjectOptions): Promise<TestProjectInlineConfiguration>;
+};
+/** `component()`: rendered units, in the `__tests__/` of the folder of the components they cover; under a specs tree, beside them. */
+type ComponentProjectOptions = ComponentOptions & SpecificationProjectOptions;
+/** A component project: renders in a real Chromium; the default `exclude` keeps it out of `specs/`. */
+export declare function component(options: ComponentProjectOptions): Promise<TestProjectInlineConfiguration>;
 //#endregion
-//#region src/facets/integration/integration.project.d.ts
-/** `integration()` — a module against real services, or against a golden. */
-declare function integration(options?: FacetProjectOptions): TestProjectInlineConfiguration;
+//#region src/specifications/integration/integration.project.d.ts
+/** `integration()`: a module against real services, or against a golden. */
+type IntegrationProjectOptions = InProcessProjectOptions;
+export declare function integration(options?: IntegrationProjectOptions): TestProjectInlineConfiguration;
 //#endregion
-//#region src/facets/jobs/jobs.project.d.ts
-/** `jobs()` — what a name triggers in-process. */
-declare function jobs(options?: FacetProjectOptions): TestProjectInlineConfiguration;
+//#region src/specifications/job/job.project.d.ts
+/** `job()`: the background jobs, run in this process. */
+type JobProjectOptions = InProcessProjectOptions;
+export declare function job(options?: JobProjectOptions): TestProjectInlineConfiguration;
 //#endregion
-//#region src/facets/mobile/mobile.project.d.ts
-/**
- * `mobile()` — the app on a simulator. A simulator is the one thing that
- * cannot share a machine with itself, so it runs last and alone (group 3).
- */
-declare function mobile(options?: FacetProjectOptions): TestProjectInlineConfiguration;
+//#region src/specifications/lint/lint.project.d.ts
+/** `lint()`: the rules a project ships, run by the real linters over fixture trees. */
+type LintProjectOptions = SpecificationProjectOptions;
+export declare function lint(options?: LintProjectOptions): TestProjectInlineConfiguration;
 //#endregion
-//#region src/facets/website/website.project.d.ts
-/** `website()` — the assembled product, met through a served page. */
-type WebsiteProjectOptions = FacetProjectOptions;
-/**
- * A website spec meets the assembled product through a served page, in the
- * Chromium playwright drives. It opens a browser, so it is scheduled before the
- * component project and never beside it: two Chromiums must not share a slot on
- * a 2-vCPU runner.
- */
-declare function website(options?: WebsiteProjectOptions): TestProjectInlineConfiguration;
+//#region src/specifications/mobile/mobile.project.d.ts
+/** The common options; for a run whose specs spawn no server, the device its one Appium server drives. */
+type MobileProjectOptions = SpecificationProjectOptions & ({
+  device: MobileDevice;
+  root?: string;
+} | {
+  device?: never;
+  root?: never;
+});
+/** A simulator cannot share a machine with itself: serial, unless `serial: false` states a server that gives every session an app of its own. A global setup holds the run's driver sessions, one per worker. */
+export declare function mobile(options?: MobileProjectOptions): TestProjectInlineConfiguration;
+//#endregion
+//#region src/specifications/website/website.project.d.ts
+/** `website()`: the assembled product, met through a served page. */
+type WebsiteProjectOptions = RunnerOption & SpecificationProjectOptions;
+export declare function website(options?: WebsiteProjectOptions): TestProjectInlineConfiguration;
 //#endregion
-//#region src/runner/projects.d.ts
-/** `unit()` — module tests, beside the modules they cover (CONVENTIONS I2). */
-type UnitProjectOptions = FacetProjectOptions & {
-  /**
-   * The trees module tests live in, when they do not live in `src/`. Each
-   * root becomes `<root>/**\/*.test.ts`; `include` states the globs outright.
-   */
+//#region src/vitest/unit.project.d.ts
+/** `unit()`: module tests, in the `__tests__/` of the folder of the modules they cover (rule `test-in-its-tests-folder`). */
+type UnitProjectOptions = SpecificationProjectOptions & {
+  /** `false` shares one module graph per worker (`isolate: false`); for pure projects only. */
+  isolate?: boolean;
+  /** The trees module tests live in, each collected whole: none, every `.test.ts` outside `specs/`. */
   roots?: string[];
 };
-/**
- * A module test runs beside the module it covers: no DOM, no browser, no
- * pipeline. Its suffix is `.test.ts` and its place is OUTSIDE `specs/`, where
- * the assembled product is specified in `.spec.ts` — the two exclusions say
- * exactly that. `.test.tsx` is the third exclusion because a rendered thing is
- * a component test: a project's dependency scan reads every file its globs
- * match, and a `.tsx` collected here would be optimised for a page that never
- * opens.
- */
-declare function unit(options?: UnitProjectOptions): TestProjectInlineConfiguration;
+/** `.test.tsx` is excluded: a rendered thing is a component test, and the dependency scan would optimise it for a page that never opens. */
+export declare function unit(options?: UnitProjectOptions): TestProjectInlineConfiguration;
+//#endregion
+//#region src/index.vitest.d.ts
+export declare const vitestConfig: (configUrl: string) => Promise<ViteUserConfig>;
 //#endregion
-export { type CliProjectOptions, type ComponentProjectOptions, type FacetProjectOptions, type LiterateOptions, type LiteratePlugin, type SpecConfig, type UnitProjectOptions, type WebsiteProjectOptions, api, cli, component, defineSpecConfig, integration, jobs, literate, mobile, unit, website };
+export type { ApiProjectOptions, CliProjectOptions, ComponentProjectOptions, InProcessProjectOptions, IntegrationProjectOptions, JobProjectOptions, LintProjectOptions, LiterateDoor, LiterateOptions, LiteratePlugin, MobileProjectOptions, SpecificationProjectOptions, UnitProjectOptions, WebsiteProjectOptions };
+//# sourceMappingURL=vitest.d.ts.map