@jterrazz/test 18.0.4 → 18.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @jterrazz/test
 
-A testing framework on vitest for whole products: HTTP APIs, background jobs, CLIs, websites, native mobile apps, rendered components, modules against real databases, and the lint rules a project ships. You declare what a test needs (Postgres, a built binary, a real Chromium, an iOS simulator), and the framework starts it, isolates it per worker and cleans it up. Each test is one sentence: a few setups, one action, and the whole result compared with `expect()`.
+A testing framework on vitest for whole products: HTTP APIs, background jobs, CLIs, websites, running deployments, native mobile apps, rendered components, modules against real databases, and the lint rules a project ships. You declare what a test needs (Postgres, a built binary, a real Chromium, an iOS simulator), and the framework starts it, isolates it per worker and cleans it up. Each test is one sentence: a few setups, one action, and the whole result compared with `expect()`.
 
 ```typescript
 // specs/api/users/list/shape.spec.ts
@@ -52,6 +52,7 @@ An ES module project on Node 24, vitest 5 and `@jterrazz/typescript` 11 is requi
 | [Component](docs/guides/component-specs.md)     | A React component, hook or DOM function in a real Chromium      | `component.render()`           |
 | [Website](docs/guides/website-specs.md)         | A served page, fetched or driven in a browser                   | `specification.website()`      |
 | [Mobile](docs/guides/mobile-specs.md)           | A native app on an iOS simulator                                | `specification.mobile()`       |
+| [Deployment](docs/guides/deployment-specs.md)   | A running deployment, probed over the network, no browser       | `specification.deployment()`   |
 | [API](docs/guides/api-specs.md)                 | An HTTP app, through complete requests                          | `specification.api()`          |
 | [Job](docs/guides/job-specs.md)                 | A pipeline triggered by name                                    | `specification.job()`          |
 | [CLI](docs/guides/cli-specs.md)                 | A binary in a fresh working directory, often as a YAML document | `specification.cli()`          |

package/dist/browser-shared-index.browser.js

@@ -3211,10 +3211,11 @@ async function waitUntil(predicate, options = {}) {
 }
 //#endregion
 //#region src/index.browser.ts
-/** The seven constructors, present and refusing in a page. */
+/** The eight constructors, present and refusing in a page. */
 const specification = {
 	api: () => refuse("specification.api()"),
 	cli: () => refuse("specification.cli()"),
+	deployment: () => refuse("specification.deployment()"),
 	integration: () => refuse("specification.integration()"),
 	job: () => refuse("specification.job()"),
 	lint: () => refuse("specification.lint()"),

package/dist/checker.js

@@ -1767,16 +1767,16 @@ function firstLine(text) {
 }
 const GRAMMAR = {
 	request: {
-		line: /^(?<method>GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS) \/\S*/u,
+		line: /^(?<method>GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS) (?:\/|https?:\/\/)/u,
 		teaching: (name) => ({
-			fix: `start ${name} with its request line, \`GET /path\` or another method`,
+			fix: `start ${name} with its request line, \`GET /path\`, \`GET https://host/path\` or another method`,
 			found: `the first line of ${name} is no request line`
 		})
 	},
 	response: {
-		line: /^HTTP\/\d(?:\.\d)? \d{3}\b/u,
+		line: /^(?:HTTP\/\d(?:\.\d)? \d{3}\b|unreachable: \S)/u,
 		teaching: (name) => ({
-			fix: `start ${name} with its status line, \`HTTP/1.1 200 OK\` or the status it expects`,
+			fix: `start ${name} with its status line, \`HTTP/1.1 200 OK\` or the status it expects, or \`unreachable: <reason>\``,
 			found: `the first line of ${name} is no status line`
 		})
 	}

package/dist/config.d.ts

@@ -22,7 +22,7 @@ type TestSettings = {
   specifications?: readonly string[];
 };
 /** The helpers a project is built by, named by their specification. */
-type TestSpecification = 'api' | 'cli' | 'component' | 'integration' | 'job' | 'lint' | 'mobile' | 'unit' | 'website';
+type TestSpecification = 'api' | 'cli' | 'component' | 'deployment' | 'integration' | 'job' | 'lint' | 'mobile' | 'unit' | 'website';
 /** What a declared project states beyond its derived one: the global setups it runs, the options its helper takes, and why. */
 type TestProject = {
   readonly reason: string;

package/dist/config.js

@@ -13,16 +13,23 @@ var standard_default = defineStandard({ test: {
 		"api",
 		"cli",
 		"component",
+		"deployment",
 		"integration",
 		"job",
 		"lint",
 		"mobile",
 		"website"
 	],
-	projects: { unit: {
-		isolate: false,
-		reason: "a module test leaves no state behind in a module, so a worker runs its files in one module graph"
-	} }
+	projects: {
+		lint: {
+			isolate: false,
+			reason: "a lint spec lays its own fixture tree and runs the linters as processes of their own, so a worker runs its files in one module graph"
+		},
+		unit: {
+			isolate: false,
+			reason: "a module test leaves no state behind in a module, so a worker runs its files in one module graph"
+		}
+	}
 } });
 //#endregion
 //#region lint/kit/project/loaded-packages.ts

package/dist/index.d.ts

@@ -279,6 +279,15 @@ type ServerResponse = {
   body: unknown;
   /** Response headers as a flat key-value map. */
   headers: Record<string, string>;
+  /** Why no response came back (`refused`, `timeout`, `dns`, `tls CERT_HAS_EXPIRED` ...): set only when the exchange never answered, and then the status is 0, the headers empty and the body null. */
+  unreachable?: string | undefined;
+};
+/** What update mode writes into a golden that states nothing yet: which headers it records, and whether a golden stating no body keeps stating none. */
+type ResponseRecording = {
+  /** A golden that states no body keeps stating none: the body is claimed by writing it. */
+  readonly bodyKeptAbsent: boolean;
+  /** The header names a fresh golden records, those the response carries. */
+  readonly headers: readonly string[];
 };
 /** Read-only accessor for an HTTP response, compared by `expect(...).toMatch(...)`. */
 declare class ResponseAccessor {
@@ -288,10 +297,14 @@ declare class ResponseAccessor {
   readonly captures: CaptureScope;
   /** Response headers as a flat, lower-cased key-value map. */
   readonly headers: Record<string, string>;
+  /** @internal */
+  readonly recording: ResponseRecording;
   readonly status: number;
   /** @internal */
   readonly testDir: string;
-  constructor(response: ServerResponse, testDir: string, captures?: CaptureScope);
+  /** Why the exchange never answered, a golden's `unreachable: <reason>` line; undefined when it answered. */
+  readonly unreachable: string | undefined;
+  constructor(response: ServerResponse, testDir: string, captures?: CaptureScope, recording?: ResponseRecording);
 }
 //#endregion
 //#region src/specifications/api/server/server.port.d.ts
@@ -465,7 +478,7 @@ type Methods<C extends Composition, P extends SpecificationParams, Self> = Inter
 type ChainOf<C extends Composition, P extends SpecificationParams, Self> = Pick<Methods<C, P, Self>, Extract<Names<C['actions']> | Names<C['capabilities']>, keyof Methods<C, P, Self>>> & SharingOf<C, Self>;
 //#endregion
 //#region src/specifications/api/api.composition.d.ts
-declare const composition$7: {
+declare const composition$8: {
   readonly actions: readonly [Action<"request", [source: string | DiskFile<".http">], HttpResult, RequestSignature, {
     server: ServerPort;
   }, ChainConfig>, Action<"get", [path: string, options?: RouteOptionsAny], HttpResult, RequestSignature, {
@@ -508,7 +521,7 @@ declare const composition$7: {
   };
 };
 /** The chain `specification.api()` hands out; the app answers in this process (`server-sees-declared-services`). */
-interface ApiSpecification<DatabaseKey extends string = string> extends ChainOf<typeof composition$7, {
+interface ApiSpecification<DatabaseKey extends string = string> extends ChainOf<typeof composition$8, {
   databaseKey: DatabaseKey;
   services: Record<string, unknown>;
 }, ApiSpecification<DatabaseKey>> {}
@@ -720,7 +733,7 @@ interface PrepareSignature extends ChainSignature {
 }
 //#endregion
 //#region src/specifications/cli/cli.composition.d.ts
-declare const composition$6: {
+declare const composition$7: {
   readonly actions: readonly [Action<"exec", [args?: string | string[], options?: ExecOptions], CliResult, ExecSignature, {
     command: CliPort;
   }, CliConfig>, Action<"run", [document: DiskFile<".spec.yaml">, options?: LiterateRunFlags], CliResult, RunSignature$1, Record<never, never>, CliConfig>];
@@ -793,7 +806,7 @@ declare const composition$6: {
   };
 };
 /** The chain `specification.cli()` hands out: a binary run in a fresh, empty working directory, in its own process. */
-interface CliSpecification<DatabaseKey extends string = string> extends ChainOf<typeof composition$6, {
+interface CliSpecification<DatabaseKey extends string = string> extends ChainOf<typeof composition$7, {
   databaseKey: DatabaseKey;
   services: Record<string, unknown>;
 }, CliSpecification<DatabaseKey>> {}
@@ -861,6 +874,131 @@ type CliHandle<DatabaseKey extends string = string> = {
 };
 declare function startCli<Services extends ServiceRecord>(bin: string, options?: CliSpecificationOptions<Services>): Promise<CliHandle<DatabaseKeys<Services>>>;
 //#endregion
+//#region src/specifications/deployment/exchange/tls-facts.d.ts
+/** The certificate an HTTPS exchange was presented, and what the client made of it. */
+type TlsFacts = {
+  /** The names the certificate is valid for (its subjectAltName), each without its `DNS:` or `IP Address:` prefix. */
+  readonly altNames: readonly string[];
+  /** The code the trust check refused with (`DEPTH_ZERO_SELF_SIGNED_CERT`, `CERT_HAS_EXPIRED`, `ERR_TLS_CERT_ALTNAME_INVALID` ...), undefined when trusted. */
+  readonly authorizationError: string | undefined;
+  /** Whether the certificate chains to a trusted authority and covers the URL's host. */
+  readonly authorized: boolean;
+  /** Whole days from the exchange to `validTo`, negative once it has expired. */
+  readonly daysRemaining: number;
+  /** The issuer's common name, or its organisation when it states none. */
+  readonly issuer: string;
+  /** The TLS version negotiated (`TLSv1.3`). */
+  readonly protocol: string | undefined;
+  /** The subject's common name; empty when it states none. */
+  readonly subject: string;
+  readonly validFrom: Date;
+  readonly validTo: Date;
+  /** Whether the certificate is valid for `host`, wildcards read as a client reads them. */
+  covers: (host: string) => boolean;
+};
+//#endregion
+//#region src/specifications/deployment/exchange/exchange.result.d.ts
+/** What one exchange with a deployment hands back: the response, or why none came, and the certificate it was presented. */
+declare class ExchangeResult extends BaseResult {
+  private readonly answer;
+  private readonly recording;
+  /** The certificate an https exchange was presented and the trust check's verdict; undefined over http, or when no handshake completed. */
+  readonly tls: TlsFacts | undefined;
+  constructor(options: BaseResultOptions & {
+    recording: ResponseRecording;
+    response: ServerResponse;
+    tls: TlsFacts | undefined;
+  });
+  /** The whole response (status, headers, body), or `unreachable: <reason>`, compared whole: `toMatch(<.http text>)` or `toMatch(file(...))`. */
+  get response(): ResponseAccessor;
+}
+//#endregion
+//#region src/specifications/deployment/exchange/request.action.d.ts
+type ExchangeSignature = ChainSignature & {
+  readonly chain: {
+    /** Send a GET to a URL, written whole or as a path from the specification's `url`, and resolve with what came back. */
+    get: (target: string) => Promise<ExchangeResult>;
+    /** Send a complete request: its `.http` text written in the test, or `file('./__requests__/<name>.http')`; its first line names the URL whole or a path. */
+    request: (source: DiskFile<'.http'> | string) => Promise<ExchangeResult>;
+  };
+};
+//#endregion
+//#region src/specifications/deployment/exchange/connect.capability.d.ts
+type ConnectChain<Self> = {
+  /** Open the socket on this address instead of the URL's host and port, as curl's `--connect-to`: the Host header and the TLS server name stay the URL's; a later call wins. */
+  connect: (address: string) => Self;
+};
+interface ConnectSignature extends ChainSignature {
+  readonly chain: ConnectChain<this['self']>;
+}
+//#endregion
+//#region src/specifications/deployment/deployment.composition.d.ts
+declare const composition$6: {
+  readonly actions: readonly [Action<"request", [source: string | DiskFile<".http">], ExchangeResult, ExchangeSignature, Record<never, never>, DeploymentConfig>, Action<"get", [target: string], ExchangeResult, ExchangeSignature, Record<never, never>, DeploymentConfig>];
+  readonly capabilities: readonly [Capability<"connect", string | null, [address: string], ConnectSignature, Record<never, never>, never, ChainConfig>, Capability<"headers", Readonly<Record<string, string>>, [headers: Record<string, string>], HeadersSignature, Record<never, never>, "headers", ChainConfig>, Sharing];
+  readonly options: {
+    ca: {
+      group: "Constructor option";
+      name: string;
+      probe: string;
+    };
+    insecure: {
+      group: "Constructor option";
+      name: string;
+      probe: string;
+    };
+    recordedHeaders: {
+      group: "Constructor option";
+      name: string;
+      probe: string;
+    };
+    timeout: {
+      group: "Constructor option";
+      name: string;
+      probe: string;
+    };
+    url: {
+      group: "Constructor option";
+      name: string;
+      probe: string;
+    };
+  };
+};
+/** The chain `specification.deployment()` hands out: one HTTP exchange with a running deployment, over the network. */
+interface DeploymentSpecification extends ChainOf<typeof composition$6, {
+  databaseKey: string;
+  services: Record<string, unknown>;
+}, DeploymentSpecification> {}
+//#endregion
+//#region src/specifications/deployment/deployment.handle.d.ts
+/** Options for {@link startDeployment | specification.deployment}. */
+type DeploymentSpecificationOptions = {
+  /** A certificate authority trusted beside the ones node trusts: its PEM text, a value like any string. */
+  ca?: string;
+  /** Accept a certificate the trust check refuses (self-signed, expired, another host's); `result.tls` still says why. Default `false`. */
+  insecure?: boolean;
+  /** The headers update mode records into a golden that states none yet, those the response carries. Default `['content-type', 'location']`. */
+  recordedHeaders?: readonly string[];
+  /** The milliseconds one exchange may take, connection to last byte, before it reads `unreachable: timeout`. Default `5000`. */
+  timeout?: number;
+  /** The base URL a path is read from (`.get('/health')`); a URL written whole needs none. */
+  url?: string;
+};
+type DeploymentConfig = ChainConfig & {
+  baseUrl: string | undefined;
+  ca: string | undefined;
+  insecure: boolean;
+  recording: ResponseRecording;
+  timeout: number;
+};
+/** What `specification.deployment()` returns: `const { deployment, cleanup } = ...` (`no-runner-alias`). */
+type DeploymentHandle = {
+  /** Starts nothing, so releases nothing: passed to `afterAll` like every specification's. */
+  cleanup: () => Promise<void>;
+  deployment: DeploymentSpecification;
+};
+declare function startDeployment(options?: DeploymentSpecificationOptions): Promise<DeploymentHandle>;
+//#endregion
 //#region src/specifications/integration/call.result.d.ts
 type CallOutcome = {
   error: unknown;
@@ -1552,10 +1690,11 @@ type WebsiteHandle = {
 declare function startWebsite<Services extends ServiceRecord>(options: WebsiteSpecificationOptions<Services>): Promise<WebsiteHandle>;
 //#endregion
 //#region src/specifications/specification.d.ts
-/** The seven constructors, and only seven: the framework's whole entry surface. */
+/** The eight constructors, and only eight: the framework's whole entry surface. */
 type Specification = {
   api: typeof startApi;
   cli: typeof startCli;
+  deployment: typeof startDeployment;
   integration: typeof startIntegration;
   job: typeof startJob;
   lint: typeof startLint;
@@ -1912,5 +2051,5 @@ declare module 'vitest' {
   }
 }
 //#endregion
-export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, type BaseResult, type BrowserConsoleMessage, type BrowserLinkElement, type BrowserMetaElement, type BrowserOpenOptions, type BrowserPage, type BrowserPort, type CallResult, type CaptureScope, type CliEnv, type CliHandle, type CliInput, type CliOutput, type CliPort, type CliResult, type CliSpecification, type CliSpecificationOptions, type ComponentChain, type ComponentScenario, type ComponentUi, type ComponentVisitor, type ContainerAccessor, type DeviceOpenOptions, type DevicePort, type DeviceScreen, type DeviceTimeouts, type DirectoryAccessor, type DiskDirectory, type DiskFile, type DiskTarget, type DockerSpecConfig, type DomMount, type ElementKind, type ElementMatch, type ExecOptions, type FetchResult, type FileAccessor, type FileAt, type FilesystemAccessor, type HonoApp, type HttpResult, type IntegrationHandle, type IntegrationSpecification, type IntegrationSpecificationOptions, type Job, type JobHandle, type JobResult, type JobSpecification, type JobSpecificationOptions, type JsonAccessor, type LandmarkKind, type LintConfig, type LintHandle, type LintResult, type LintRules, type LintRunOptions, type LintSpecification, type LintSpecificationOptions, type LiterateRunFlags, type LiterateServeRegistration, type MatchFixtureOptions, Matcher, type MatcherKind, type MobileBackendOptions, type MobileElementKind, type MobileElementMatch, type MobileHandle, type MobileScenario, type MobileSpecification, type MobileSpecificationOptions, type MobileVisitor, type MockOfOptions, type MockPort, type PackedPackage, type PageResult, type PinnedClock, type PositionedCases, type PositionedRuleTester, type PrepareStep, type RelativePath, type RenderResult, type RenderSubject, type RenderedText, type ResponseAccessor, type ScreenNode, type ScreenResult, type ServerPort, type ServerRequestOptions, type ServerResponse, type ServerSpec, type SpecDocument, type SpecEnvToken, type SpecFileAssertion, type SpecFixture, type SpecRun, type SpecServeEntry, type SpecStream, type TableAccessor, type Target, type TargetOptions, type TextAccessor, type VisitScenario, type WaitUntilOptions, type WebsiteBackendOptions, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, type WebsiteVisitor, directory, file, match };
+export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, type BaseResult, type BrowserConsoleMessage, type BrowserLinkElement, type BrowserMetaElement, type BrowserOpenOptions, type BrowserPage, type BrowserPort, type CallResult, type CaptureScope, type CliEnv, type CliHandle, type CliInput, type CliOutput, type CliPort, type CliResult, type CliSpecification, type CliSpecificationOptions, type ComponentChain, type ComponentScenario, type ComponentUi, type ComponentVisitor, type ContainerAccessor, type DeploymentHandle, type DeploymentSpecification, type DeploymentSpecificationOptions, type DeviceOpenOptions, type DevicePort, type DeviceScreen, type DeviceTimeouts, type DirectoryAccessor, type DiskDirectory, type DiskFile, type DiskTarget, type DockerSpecConfig, type DomMount, type ElementKind, type ElementMatch, type ExchangeResult, type ExecOptions, type FetchResult, type FileAccessor, type FileAt, type FilesystemAccessor, type HonoApp, type HttpResult, type IntegrationHandle, type IntegrationSpecification, type IntegrationSpecificationOptions, type Job, type JobHandle, type JobResult, type JobSpecification, type JobSpecificationOptions, type JsonAccessor, type LandmarkKind, type LintConfig, type LintHandle, type LintResult, type LintRules, type LintRunOptions, type LintSpecification, type LintSpecificationOptions, type LiterateRunFlags, type LiterateServeRegistration, type MatchFixtureOptions, Matcher, type MatcherKind, type MobileBackendOptions, type MobileElementKind, type MobileElementMatch, type MobileHandle, type MobileScenario, type MobileSpecification, type MobileSpecificationOptions, type MobileVisitor, type MockOfOptions, type MockPort, type PackedPackage, type PageResult, type PinnedClock, type PositionedCases, type PositionedRuleTester, type PrepareStep, type RelativePath, type RenderResult, type RenderSubject, type RenderedText, type ResponseAccessor, type ScreenNode, type ScreenResult, type ServerPort, type ServerRequestOptions, type ServerResponse, type ServerSpec, type SpecDocument, type SpecEnvToken, type SpecFileAssertion, type SpecFixture, type SpecRun, type SpecServeEntry, type SpecStream, type TableAccessor, type Target, type TargetOptions, type TextAccessor, type TlsFacts, type VisitScenario, type WaitUntilOptions, type WebsiteBackendOptions, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, type WebsiteVisitor, directory, file, match };
 //# sourceMappingURL=index.d.ts.map