@gfdelarue/testkit 0.4.5 → 0.5.0

package/dist/types/config.d.ts

@@ -0,0 +1,501 @@
+declare const RUNTIME_ISOLATION_POLICIES: readonly [
+	"shared",
+	"resetBefore"
+];
+export type RuntimeIsolationPolicy = (typeof RUNTIME_ISOLATION_POLICIES)[number];
+export type RuntimeMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface RuntimeHeaders {
+	[key: string]: string;
+}
+export interface RuntimeCookie {
+	value: string;
+}
+export interface RuntimeEnv {
+	BASE: string;
+	rawEnv?: Record<string, string | undefined>;
+}
+export interface HttpRequestParams {
+	[key: string]: unknown;
+	headers?: RuntimeHeaders;
+}
+export type HttpProfileEnvironment = Readonly<Record<string, string | undefined>>;
+export interface HttpProfileEnv {
+	[key: string]: unknown;
+	BASE?: string;
+	rawEnv?: HttpProfileEnvironment;
+}
+export type HttpProfileResolvedEnv = HttpProfileEnv & RuntimeEnv;
+export interface HttpProfileHeaderContext {
+	actor?: string | null;
+	env?: HttpProfileEnv;
+}
+export type HttpProfileHeaderBuilder<TSetup = unknown> = (setupData: TSetup | null, context?: HttpProfileHeaderContext & {
+	env: HttpProfileResolvedEnv;
+}) => RuntimeHeaders | undefined;
+/** Response shape the in-process profile setup client resolves to. */
+export interface HttpProfileResponse {
+	body: string;
+	cookies?: Record<string, RuntimeCookie[] | undefined>;
+	headers?: Record<string, string>;
+	status: number;
+}
+export type HttpProfileRequestMethod = "del" | "get" | "patch" | "post" | "put";
+/** HTTP verbs an execution engine hands to a profile's setup step. */
+export type HttpProfileRequestClient<TResult = Promise<HttpProfileResponse>> = {
+	[Method in HttpProfileRequestMethod]: Method extends "get" ? (url: string, params?: HttpRequestParams) => TResult : (url: string, body?: unknown, params?: HttpRequestParams) => TResult;
+};
+export interface HttpProfileSetupContext {
+	env: HttpProfileResolvedEnv;
+	http: HttpProfileRequestClient;
+	json(response: unknown): unknown;
+}
+/**
+ * Explicit, test-owned authentication for a named HTTP profile. The data
+ * profile runs `setup` or `setupAsync` once and passes the
+ * result to `headers` for every request.
+ */
+export interface HttpProfileAuth<TSetup = unknown> {
+	headers?: HttpProfileHeaderBuilder<TSetup>;
+	setup?(context: HttpProfileSetupContext): TSetup;
+	setupAsync?(context: HttpProfileSetupContext): Promise<TSetup>;
+}
+export interface HttpProfileConfig<TSetup = unknown> {
+	[key: string]: unknown;
+	auth?: HttpProfileAuth<TSetup> | null;
+	baseUrl?: string;
+	env?: HttpProfileEnv;
+	headers?: HttpProfileHeaderBuilder<TSetup>;
+	rawHeaders?: HttpProfileHeaderBuilder<TSetup>;
+}
+export interface RepoConfig {
+	[key: string]: unknown;
+	profiles?: {
+		http?: Record<string, HttpProfileConfig>;
+	};
+}
+export declare function registerRepoConfig(config: RepoConfig | null | undefined): void;
+export declare function getRepoConfig(): RepoConfig | null;
+export declare function clearRepoConfig(): void;
+export interface DatabaseBindingEnvConfig {
+	prefix: string;
+	service: string;
+}
+export interface PresetEnvConfig {
+	databases?: Record<string, DatabaseBindingEnvConfig>;
+	values?: Record<string, string>;
+}
+export interface ConfiguredStepBaseInput {
+	args?: unknown;
+	cwd?: string;
+	inputs?: string[];
+}
+export interface ConfiguredCommandStepInput extends ConfiguredStepBaseInput {
+	kind: "command";
+	run: string;
+}
+export interface ConfiguredSqlFileStepInput extends ConfiguredStepBaseInput {
+	kind: "sql-file";
+	path: string;
+}
+export interface ConfiguredModuleStepInput extends ConfiguredStepBaseInput {
+	kind: "module";
+	target: string;
+}
+export type ConfiguredStepInput = ConfiguredCommandStepInput | ConfiguredSqlFileStepInput | ConfiguredModuleStepInput;
+export interface BuildConfigInputBase {
+	inputs?: string[];
+}
+export interface TscBuildConfigInput extends BuildConfigInputBase {
+	cwd?: string;
+	entry?: string;
+	kind: "tsc";
+	outDir?: string;
+	tsconfig?: string;
+}
+export interface ScriptBuildConfigInput extends BuildConfigInputBase {
+	cwd?: string;
+	kind: "script";
+	script: string;
+}
+export interface NextBuildConfigInput extends BuildConfigInputBase {
+	cwd?: string;
+	distDir?: string;
+	kind: "next";
+	tsconfig?: string;
+}
+export interface StepsBuildConfigInput extends BuildConfigInputBase {
+	kind: "steps";
+	steps?: ConfiguredStepInput[];
+}
+export type BuildConfigInput = TscBuildConfigInput | ScriptBuildConfigInput | NextBuildConfigInput | StepsBuildConfigInput;
+export type TemplateCommandStepConfig = ConfiguredCommandStepInput;
+export type TemplateSqlFileStepConfig = ConfiguredSqlFileStepInput;
+export type TemplateModuleStepConfig = ConfiguredModuleStepInput;
+export type TemplateLifecycleStepConfig = ConfiguredStepInput;
+export type TemplateLifecycleStepOptions = ConfiguredStepBaseInput;
+export type TemplateStepBaseConfig = ConfiguredStepBaseInput;
+export type BuildConfig = BuildConfigInput;
+export type TscBuildConfig = TscBuildConfigInput;
+export type ScriptBuildConfig = ScriptBuildConfigInput;
+export type NextBuildConfig = NextBuildConfigInput;
+export type StepsBuildConfig = StepsBuildConfigInput;
+export interface DatabaseTemplateConfig {
+	inputs?: string[];
+	migrate?: ConfiguredStepInput[];
+	seed?: ConfiguredStepInput[];
+	verify?: ConfiguredStepInput[];
+}
+export interface DatabaseTemplateOptions {
+	inputs?: string[];
+	migrate?: ConfiguredStepInput | ConfiguredStepInput[] | string | string[];
+	seed?: ConfiguredStepInput | ConfiguredStepInput[] | string | string[];
+	verify?: ConfiguredStepInput | ConfiguredStepInput[] | string | string[];
+}
+export interface DatabaseSourceSchemaOptions {
+	refresh?: "auto" | "always" | {
+		ttlSeconds: number;
+	};
+	unavailable?: "auto" | "fail" | "warn-cache";
+	verify?: boolean;
+}
+export interface DatabaseSourceSchemaConfig extends DatabaseSourceSchemaOptions {
+	env: string;
+	kind: "env";
+}
+export interface DatabaseRoleConfig {
+	name: string;
+	login: false;
+}
+export interface PostgresDatabaseFields {
+	binding?: "shared" | "per-runtime";
+	image?: string;
+	maxConnections?: number;
+	password?: string;
+	reservedConnections?: number;
+	reset?: boolean;
+	roles?: DatabaseRoleConfig[];
+	runtimeConnections?: number;
+	sourceSchema?: DatabaseSourceSchemaConfig | null;
+	user?: string;
+}
+export interface PostgresDatabaseConfig extends PostgresDatabaseFields {
+	template?: DatabaseTemplateConfig;
+}
+export interface DatabaseLifecycleOptions extends PostgresDatabaseFields {
+	inputs?: string[];
+	migrate?: ConfiguredStepInput | ConfiguredStepInput[] | string | string[];
+	seed?: ConfiguredStepInput | ConfiguredStepInput[] | string | string[];
+	template?: DatabaseTemplateOptions;
+	verify?: ConfiguredStepInput | ConfiguredStepInput[] | string | string[];
+}
+export interface DatabaseFixtureOptions extends DatabaseLifecycleOptions {
+	discovery?: DiscoveryConfig;
+	envFiles?: string[];
+}
+export interface SkipFileRule {
+	path: string;
+	reason: string;
+}
+export interface SkipSuiteRule {
+	selector: string;
+	reason: string;
+}
+export interface SkipConfig {
+	files?: SkipFileRule[];
+	suites?: SkipSuiteRule[];
+}
+export interface RuntimePrepareConfig {
+	inputs?: string[];
+	steps?: ConfiguredStepInput[];
+}
+export interface RuntimeConfig {
+	build?: BuildConfigInput | null;
+	instances?: number;
+	maxConcurrentTasks?: number;
+	prepare?: RuntimePrepareConfig;
+	toolchain?: string | NodeToolchainConfig;
+}
+export interface NodeToolchainConfig {
+	cwd?: string;
+	detect?: "auto" | "off";
+	install?: "require-host" | "download";
+	node?: string;
+	npm?: string;
+}
+export type ToolchainConfig = NodeToolchainConfig;
+export interface SuiteRequirementRule {
+	locks?: string[];
+	selector: string;
+}
+export interface FileRequirementRule {
+	locks?: string[];
+	path: string;
+}
+export interface ServiceRequirementConfig {
+	files?: FileRequirementRule[];
+	suites?: SuiteRequirementRule[];
+}
+export interface SuiteRuntimeIsolationRule {
+	policy: RuntimeIsolationPolicy;
+	selector: string;
+}
+export interface FileRuntimeIsolationRule {
+	path: string;
+	policy: RuntimeIsolationPolicy;
+}
+export interface RuntimeIsolationConfig {
+	default?: RuntimeIsolationPolicy;
+	files?: FileRuntimeIsolationRule[];
+	suites?: SuiteRuntimeIsolationRule[];
+}
+export interface TestkitExecutionConfig {
+	fileTimeoutSeconds?: number;
+	taskConcurrency?: number;
+	/** @deprecated Use taskConcurrency. Removed in 0.3.0. */
+	workers?: number;
+}
+export interface FingerprintConfig {
+	exclude?: string[];
+	include?: string[];
+}
+export interface TestkitLintRuleConfig {
+	enabled?: boolean;
+	exclude?: string[];
+	include?: string[];
+}
+export interface TestkitBoundaryLintRuleConfig extends TestkitLintRuleConfig {
+	allowed?: string[];
+	trackedOnly?: boolean;
+}
+export type TestkitLintRuleName = "engineImports" | "uiSpecShape" | "dataSuiteContract" | "configImports" | "testkitBoundary" | "unitTestBoundaries";
+export interface TestkitLintConfig {
+	rules?: Partial<Record<Exclude<TestkitLintRuleName, "testkitBoundary">, boolean | TestkitLintRuleConfig>> & {
+		testkitBoundary?: boolean | TestkitBoundaryLintRuleConfig;
+	};
+	ui?: {
+		maxLines?: number;
+		maxTests?: number;
+	};
+}
+export interface UiConfig {
+	allowRemote?: boolean;
+	backendBaseUrl?: string;
+	frontendBaseUrl?: string;
+}
+export interface DiscoveryConfig {
+	exclude?: string[];
+	roots?: string[];
+}
+export interface GroupConfig {
+	exclude?: string[];
+	requirements?: ServiceRequirementConfig;
+	roots: string[];
+	runtimeIsolation?: RuntimeIsolationPolicy | RuntimeIsolationConfig;
+	skip?: SkipConfig;
+	uses?: string[];
+}
+export interface ServiceLocalConfig {
+	baseUrl?: string;
+	cwd?: string;
+	env?: Record<string, string>;
+	readyTimeoutMs?: number;
+	shutdownTimeoutMs?: number;
+	readyUrl?: string | false | null;
+	start: string;
+}
+export interface ServiceConfig {
+	database?: PostgresDatabaseConfig;
+	databaseFrom?: string;
+	dependsOn?: string[];
+	discovery?: DiscoveryConfig;
+	env?: Record<string, string>;
+	envFile?: string;
+	envFiles?: string[];
+	local?: false | ServiceLocalConfig;
+	runtime?: RuntimeConfig;
+	runtimeIsolation?: RuntimeIsolationPolicy | RuntimeIsolationConfig;
+	requirements?: ServiceRequirementConfig;
+	skip?: SkipConfig;
+}
+export interface AppServiceConfig extends ServiceConfig {
+	local: ServiceLocalConfig;
+	runtime: RuntimeConfig;
+}
+export interface PresetServiceOptions extends Record<string, unknown> {
+	database?: PostgresDatabaseConfig;
+	databaseFrom?: string;
+	dependsOn?: string[];
+	discovery?: DiscoveryConfig;
+	envFile?: string;
+	envFiles?: string[];
+	runtimeIsolation?: RuntimeIsolationPolicy | RuntimeIsolationConfig;
+	requirements?: ServiceRequirementConfig;
+	skip?: SkipConfig;
+}
+export interface AppRuntimeOptions {
+	instances?: number;
+	maxConcurrentTasks?: number;
+	prepare?: RuntimePrepareConfig;
+	toolchain?: string | NodeToolchainConfig;
+}
+export interface NodeAppOptions extends PresetServiceOptions {
+	baseUrl?: string;
+	build?: BuildConfigInput | null;
+	buildInputs?: string[];
+	cwd?: string;
+	entry?: string;
+	env?: PresetEnvConfig;
+	outDir?: string;
+	readyPath?: string;
+	readyTimeoutMs?: number;
+	shutdownTimeoutMs?: number;
+	readyUrl?: string | false | null;
+	runtime?: AppRuntimeOptions;
+	start?: string;
+	toolchain?: string | NodeToolchainConfig;
+	tsconfig?: string;
+}
+export interface NextAppOptions extends PresetServiceOptions {
+	api?: string | {
+		baseUrl: string;
+	};
+	baseUrl?: string;
+	build?: BuildConfigInput | null;
+	buildInputs?: string[];
+	cwd?: string;
+	env?: PresetEnvConfig;
+	mode?: "dev" | "start";
+	readyTimeoutMs?: number;
+	shutdownTimeoutMs?: number;
+	readyUrl?: string | false | null;
+	runtime?: AppRuntimeOptions;
+	start?: string;
+	toolchain?: string | NodeToolchainConfig;
+}
+export interface NodeNextPresetOptions {
+	fileTimeoutSeconds?: number;
+	install?: "require-host" | "download";
+	node?: string;
+	npm?: string;
+	taskConcurrency?: number;
+	/** @deprecated Use taskConcurrency. Removed in 0.3.0. */
+	workers?: number;
+}
+export interface AreaConfig {
+	name: string;
+	paths: string[];
+}
+export interface BugsConfig {
+	knownFailures?: "allow" | "fail";
+	repository?: string;
+}
+export interface TestkitConfig {
+	areas?: Record<string, AreaConfig>;
+	artifacts?: {
+		publication?: {
+			directory: string;
+			required?: boolean;
+		};
+		retention?: {
+			maxAgeDays?: number;
+			maxRuns?: number;
+			preserveSuites?: string[];
+		};
+	};
+	bugs?: BugsConfig;
+	discovery?: DiscoveryConfig;
+	execution?: TestkitExecutionConfig;
+	fingerprints?: FingerprintConfig;
+	groups?: Record<string, GroupConfig>;
+	lint?: TestkitLintConfig;
+	profiles?: {
+		http?: Record<string, HttpProfileConfig>;
+	};
+	redact?: string[];
+	services?: Record<string, ServiceConfig>;
+	toolchains?: Record<string, ToolchainConfig>;
+	ui?: UiConfig;
+}
+export declare function defineConfig<const TConfig extends TestkitConfig>(config: TConfig): TConfig;
+declare function commandStep(run: string, options?: ConfiguredStepBaseInput): ConfiguredCommandStepInput;
+declare function sqlFileStep(filePath: string, options?: ConfiguredStepBaseInput): ConfiguredSqlFileStepInput;
+declare function moduleStep(target: string, options?: ConfiguredStepBaseInput): ConfiguredModuleStepInput;
+declare function sourceSchemaFromEnv(envName: string, options?: DatabaseSourceSchemaOptions): DatabaseSourceSchemaConfig;
+declare function verifySeedStep(options?: unknown): ConfiguredModuleStepInput;
+declare function verifyRowsStep(options?: unknown): ConfiguredModuleStepInput;
+declare function runSqlStep(options?: unknown): ConfiguredModuleStepInput;
+declare function seedRowsStep(options?: unknown): ConfiguredModuleStepInput;
+declare function materializePostgresBindingStep(options?: unknown): ConfiguredModuleStepInput;
+declare function updateRowsStep(options?: unknown): ConfiguredModuleStepInput;
+declare function nowValue(): {
+	kind: "now";
+};
+declare function envValue(name: string): {
+	kind: "env";
+	name: string;
+};
+declare function jsonValue<TValue>(value: TValue): {
+	kind: "json";
+	value: TValue;
+};
+declare function postgresConnectionFromEnvValue(prefix: string): {
+	kind: "postgres-connection-from-env";
+	prefix: string;
+};
+declare function postgresFixture(options?: DatabaseFixtureOptions): ServiceConfig;
+declare function nodeToolchain(options?: NodeToolchainConfig): NodeToolchainConfig;
+declare function nodeApp(options?: NodeAppOptions): AppServiceConfig;
+declare function nextApp(options?: NextAppOptions): AppServiceConfig;
+export declare const app: {
+	node: typeof nodeApp;
+	next: typeof nextApp;
+};
+export declare const database: {
+	schema: {
+		fromEnv: typeof sourceSchemaFromEnv;
+	};
+	steps: {
+		materializePostgresBinding: typeof materializePostgresBindingStep;
+		runSql: typeof runSqlStep;
+		seedRows: typeof seedRowsStep;
+		updateRows: typeof updateRowsStep;
+		verifyRows: typeof verifyRowsStep;
+		verifySeed: typeof verifySeedStep;
+	};
+	values: {
+		env: typeof envValue;
+		json: typeof jsonValue;
+		now: typeof nowValue;
+		postgresConnectionFromEnv: typeof postgresConnectionFromEnvValue;
+	};
+	postgres(options?: DatabaseLifecycleOptions): PostgresDatabaseConfig;
+	fixture: typeof postgresFixture;
+};
+export declare const endpoint: {
+	baseUrl(serviceName: string): string;
+	readyUrl(serviceName: string): string;
+	publicBaseUrl(serviceName: string): string;
+	privateBaseUrl(serviceName: string): string;
+	serviceContextUrl(serviceName: string): string;
+};
+export declare const step: {
+	command: typeof commandStep;
+	module: typeof moduleStep;
+	sqlFile: typeof sqlFileStep;
+};
+export declare const presets: {
+	nodeNext(options?: NodeNextPresetOptions): {
+		execution: {
+			taskConcurrency: number;
+			fileTimeoutSeconds: number;
+		};
+		toolchains: {
+			node: NodeToolchainConfig;
+		};
+	};
+};
+export declare const toolchain: {
+	node: typeof nodeToolchain;
+};
+
+export {};

package/dist/types/drizzle.d.ts

@@ -0,0 +1,13 @@
+export interface DrizzleConfigOptions {
+	consumer?: string;
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+	files?: string[];
+	onlyWhenAllowed?: boolean;
+	override?: boolean;
+	requireLocalDatabase?: boolean;
+}
+export declare function defineConfig(): Record<string, never>;
+export declare function defineConfig<T extends Record<string, unknown>>(config: T, options?: DrizzleConfigOptions): T;
+
+export {};

package/dist/{config/runtime/env/index.d.ts → types/env.d.ts}

@@ -1,35 +1,37 @@
 export interface LoadDotenvFilesOptions {
-    cwd?: string;
-    env?: NodeJS.ProcessEnv;
-    files?: string[];
-    onlyWhenAllowed?: boolean;
-    override?: boolean;
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+	files?: string[];
+	onlyWhenAllowed?: boolean;
+	override?: boolean;
 }
 export interface PostgresConnectionEnvFallback {
-    database?: string;
-    host?: string;
-    password?: string;
-    port?: number | string;
-    ssl?: boolean;
-    username?: string;
+	database?: string;
+	host?: string;
+	password?: string;
+	port?: number | string;
+	ssl?: boolean;
+	username?: string;
 }
 export interface PostgresConnectionEnvOptions {
-    env?: NodeJS.ProcessEnv;
-    fallback?: PostgresConnectionEnvFallback;
+	env?: NodeJS.ProcessEnv;
+	fallback?: PostgresConnectionEnvFallback;
 }
 export interface PostgresConnectionEnvValue {
-    database: string;
-    host: string;
-    password: string;
-    port: number;
-    ssl: boolean;
-    username: string;
+	database: string;
+	host: string;
+	password: string;
+	port: number;
+	ssl: boolean;
+	username: string;
 }
 export declare function isManagedRuntime(env?: NodeJS.ProcessEnv): boolean;
 export declare function managedRuntimeMode(env?: NodeJS.ProcessEnv): null | string;
 export declare function shouldLoadDotenv(env?: NodeJS.ProcessEnv): boolean;
 export declare function loadDotenvFiles(options?: LoadDotenvFilesOptions): {
-    loaded: string[];
+	loaded: string[];
 };
 export declare function assertLocalDatabaseUrl(env?: NodeJS.ProcessEnv, consumer?: string): void;
 export declare function readPostgresConnectionFromEnv(prefix: string, options?: PostgresConnectionEnvOptions): PostgresConnectionEnvValue;
+
+export {};

package/dist/types/environment.d.ts

@@ -0,0 +1,40 @@
+export interface CapturedRequest {
+	readonly bodyBytes: number;
+	readonly bodyText: string;
+	readonly bodyTruncated: boolean;
+	readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+	readonly method: null | string;
+	readonly path: null | string;
+	readonly receivedAt: string;
+}
+export interface HttpCaptureHandle {
+	readonly kind: "http-capture";
+	readonly url: string;
+	requests(): Promise<CapturedRequest[]>;
+	reset(): Promise<void>;
+}
+export type EnvironmentHandle = HttpCaptureHandle;
+export type EnvironmentHandleFailure = "ambiguous" | "invalid" | "refused" | "unavailable" | "unsupported";
+export declare class EnvironmentHandleError extends Error {
+	readonly code = "TESTKIT_ENVIRONMENT_HANDLE_FAILED";
+	readonly handleName: string;
+	readonly reason: EnvironmentHandleFailure;
+	constructor(handleName: string, reason: EnvironmentHandleFailure, message: string, options?: ErrorOptions);
+}
+export declare class EnvironmentHandleAmbiguousError extends EnvironmentHandleError {
+	readonly count: number;
+	constructor(handleName: string, count: number);
+}
+export type EnvironmentValueKind = "database" | "endpoint" | "handle";
+export declare class EnvironmentValueMissingError extends Error {
+	readonly code = "TESTKIT_ENVIRONMENT_VALUE_MISSING";
+	readonly available: readonly string[];
+	readonly kind: EnvironmentValueKind;
+	readonly valueName: null | string;
+	constructor(kind: EnvironmentValueKind, valueName: null | string, available: readonly string[] | null);
+}
+export declare function endpoint(name: string): string;
+export declare function database(name: string): string;
+export declare function handle(name: string): EnvironmentHandle;
+
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,21 @@
+declare const ENGINE_IDS: readonly [
+	"node-vitest",
+	"playwright"
+];
+export type EngineId = (typeof ENGINE_IDS)[number];
+declare const RUNTIME_ISOLATION_POLICIES: readonly [
+	"shared",
+	"resetBefore"
+];
+export type RuntimeIsolationPolicy = (typeof RUNTIME_ISOLATION_POLICIES)[number];
+export interface TestkitFileMetadata {
+	engine: EngineId;
+	locks?: string[];
+	runtimeIsolation?: RuntimeIsolationPolicy;
+	skip?: string | {
+		reason: string;
+	};
+}
+export declare function defineFile(metadata: TestkitFileMetadata): TestkitFileMetadata;
+
+export {};