@gfdelarue/testkit 0.4.5 → 0.6.0

package/dist/types/workspace.d.ts

@@ -0,0 +1,633 @@
+declare const ENGINE_IDS: readonly [
+	"node-vitest",
+	"playwright"
+];
+export type EngineId = (typeof ENGINE_IDS)[number];
+declare const PUBLIC_TEST_TYPES: readonly [
+	"ui"
+];
+export type PublicTestType = (typeof PUBLIC_TEST_TYPES)[number];
+declare const RUNNER_PROFILE_IDS: readonly [
+	"node-vitest",
+	"playwright-ui"
+];
+export type RunnerProfileId = (typeof RUNNER_PROFILE_IDS)[number];
+declare const RUNTIME_ISOLATION_POLICIES: readonly [
+	"shared",
+	"resetBefore"
+];
+export type RuntimeIsolationPolicy = (typeof RUNTIME_ISOLATION_POLICIES)[number];
+declare const RUN_TYPE_VALUES: readonly [
+	"ui",
+	"plain",
+	"all"
+];
+export type RunType = (typeof RUN_TYPE_VALUES)[number];
+export declare function formatTestTypeLabel(testType: PublicTestType): string;
+export type ErrorMetadataPrimitive = string | number | boolean | null;
+export type ErrorMetadataValue = ErrorMetadataPrimitive | ErrorMetadataObject | ErrorMetadataValue[];
+export interface ErrorMetadataObject {
+	[key: string]: ErrorMetadataValue;
+}
+export interface SerializedErrorOperation {
+	id?: string;
+	source: string;
+	name: string;
+	kind: string;
+	summary?: string;
+	scope: ErrorMetadataObject;
+	status?: string;
+	error?: string;
+}
+export interface SerializedError {
+	name: string;
+	message: string;
+	code?: string;
+	exitCode?: number;
+	status?: number;
+	phase?: string;
+	operation?: SerializedErrorOperation;
+	diagnostics?: ErrorMetadataObject;
+	stack?: string;
+}
+declare const RETIRED_SUITE_IDENTITIES: readonly [
+	...{
+		readonly engineId: "k6";
+		readonly profileId: "k6-http";
+		readonly testType: "e2e" | "int" | "load" | "scenario";
+	}[],
+	{
+		readonly engineId: "k6";
+		readonly profileId: "k6-dal";
+		readonly testType: "dal";
+	},
+	{
+		readonly engineId: "node-vitest";
+		readonly profileId: "node-vitest-contract";
+		readonly testType: "contract";
+	},
+	{
+		readonly engineId: "node-vitest";
+		readonly profileId: "node-vitest-data";
+		readonly testType: "data";
+	}
+];
+export type ReportingRecord = Record<string, unknown>;
+export interface ReportingFailureRequest extends ReportingRecord {
+	method?: string;
+	path?: string;
+	requestId?: string;
+}
+export interface ReportingFailureResponse extends ReportingRecord {
+	bodyPreview?: string;
+	contentType?: string;
+	status?: number | string;
+}
+export interface ReportingFailureLocation extends ReportingRecord {
+	column?: number;
+	line?: number;
+	path?: string;
+}
+export interface ReportingFailureDetail extends ReportingRecord {
+	key?: string;
+	kind?: string;
+	location?: ReportingFailureLocation;
+	message?: string;
+	request?: ReportingFailureRequest;
+	response?: ReportingFailureResponse;
+	stack?: string;
+	title: string;
+}
+export interface ReportingArtifactReference extends ReportingRecord {
+	contentType?: null | string;
+	kind?: null | string;
+	name: string;
+	path: string;
+	summary?: null | string;
+}
+export interface ReportingRuntimeBatch extends ReportingRecord {
+	fileCount?: number;
+	files?: string[];
+	id?: string;
+	index?: number;
+}
+export interface ReportingRuntimeReset extends ReportingRecord {
+	position?: string;
+	reason?: string;
+	runtimeIsolation?: string;
+	trigger?: string;
+}
+export interface RunArtifactFile extends ReportingRecord {
+	artifacts?: ReportingArtifactReference[];
+	blockedByRuntime?: boolean;
+	durationMs?: null | number;
+	error?: null | string;
+	failed?: boolean;
+	failureDetails?: ReportingFailureDetail[];
+	infraFailed?: boolean;
+	path: string;
+	reason?: null | string;
+	runtimeBatch?: null | ReportingRuntimeBatch;
+	runtimeIsolation?: null | string;
+	runtimeResets?: ReportingRuntimeReset[];
+	status: string;
+}
+export interface ReportingDiagnostic extends ReportingRecord {
+	code: string;
+	group?: string;
+	message: string;
+	suite?: string;
+}
+export interface RunArtifactSuite extends ReportingRecord {
+	completedFileCount?: number;
+	diagnostics?: ReportingDiagnostic[];
+	engineId: EngineId | "k6";
+	failed?: boolean;
+	failedFileCount?: number;
+	fileCount?: number;
+	files?: RunArtifactFile[];
+	name: string;
+	passedFileCount?: number;
+	profileId: RunnerProfileId | (typeof RETIRED_SUITE_IDENTITIES)[number]["profileId"];
+	skippedFileCount?: number;
+	testType?: PublicTestType | (typeof RETIRED_SUITE_IDENTITIES)[number]["testType"];
+}
+export interface RunArtifactGroup extends ReportingRecord {
+	name: string;
+	suites: RunArtifactSuite[];
+}
+export interface ReportingServiceLogReference extends ReportingRecord {
+	path: string;
+	runtimeLabel: string;
+	serviceName: string;
+}
+export interface ReportingEnvironmentServiceAttempt extends ReportingRecord {
+	outcome: string;
+	port: number;
+}
+export interface ReportingEnvironmentService extends ReportingRecord {
+	attempts: ReportingEnvironmentServiceAttempt[];
+	baseUrl: null | string;
+	port: number;
+	readyUrl: null | string;
+	runtimeLabel: string;
+	serviceName: string;
+}
+export interface ReportingSetupLogReference extends ReportingRecord {
+	path: string;
+	runtimeLabel?: string;
+	serviceName?: string;
+	stage?: string;
+}
+export interface ReportingSetupOperation extends ReportingRecord {
+	durationMs?: null | number;
+	error?: null | string;
+	logRef?: null | ReportingSetupLogReference;
+	serviceName: string;
+	stage: string;
+	startedAt?: string;
+	status: string;
+	summary?: null | string;
+}
+export interface RunArtifactRun extends ReportingRecord {
+	durationMs?: null | number;
+	types?: string[];
+	finishedAt: null | string;
+	id: null | string;
+	startedAt: string;
+	status: string;
+}
+export interface RunDocument19 extends ReportingRecord {
+	archive?: ReportingRecord;
+	environment?: {
+		services?: ReportingEnvironmentService[];
+	};
+	finalizationFailure?: SerializedError;
+	generatedAt?: string;
+	logs?: {
+		services?: ReportingServiceLogReference[];
+		setup?: ReportingSetupLogReference[];
+	};
+	run: RunArtifactRun;
+	schemaVersion: 19;
+	services: RunArtifactGroup[];
+	setup?: {
+		operations?: ReportingSetupOperation[];
+	};
+	summary?: RunSummary19;
+}
+export interface StoredEnvironmentRecord extends ReportingRecord {
+	capacity?: {
+		readonly runtimeStats?: readonly unknown[];
+	};
+	logs?: {
+		services?: readonly ReportingServiceLogReference[];
+		setup?: readonly ReportingSetupLogReference[];
+	};
+	services?: readonly ReportingEnvironmentService[];
+	setupOperations?: readonly ReportingSetupOperation[];
+}
+export interface RunDocument20 extends ReportingRecord {
+	archive?: ReportingRecord;
+	environment?: StoredEnvironmentRecord;
+	finalizationFailure?: SerializedError;
+	generatedAt?: string;
+	groups: RunArtifactGroup[];
+	run: RunArtifactRun;
+	schemaVersion: 20;
+	summary?: RunArtifactSummary;
+}
+export type StoredRunDocument = RunDocument19 | RunDocument20;
+export interface ReportingGroupSummary {
+	blockedByRuntime: number;
+	failed: number;
+	infraFailed: number;
+	passed: number;
+	skipped: number;
+	total: number;
+}
+export interface ReportingSuiteSummary {
+	completed: number;
+	failed: number;
+	passed: number;
+	skipped: number;
+	total: number;
+}
+export interface ReportingFileSummary {
+	blockedByRuntime: number;
+	cancelled: number;
+	failed: number;
+	infraFailed: number;
+	interrupted: number;
+	notRun: number;
+	passed: number;
+	skipped: number;
+	total: number;
+}
+export interface RunArtifactSummary extends ReportingRecord {
+	diagnostics?: ReportingDiagnostic[];
+	files: ReportingFileSummary;
+	groups: ReportingGroupSummary;
+	suites: ReportingSuiteSummary;
+}
+export interface RunSummary19 extends ReportingRecord {
+	diagnostics?: ReportingDiagnostic[];
+	files: ReportingFileSummary;
+	services: ReportingGroupSummary;
+	suites: ReportingSuiteSummary;
+}
+declare const BUNDLE_SCHEMA_VERSION = 2;
+export type RunBundleSchemaVersion = typeof BUNDLE_SCHEMA_VERSION;
+export interface RunBundleStorage extends Record<string, unknown> {
+	deduplicatedBytes: number;
+	fileCount: number;
+	logicalBytes: number;
+	objectBytesWritten: number;
+}
+export interface RunBundleRedaction extends Record<string, unknown> {
+	filesRedacted: number;
+	policyVersion: number;
+	replacements: number;
+	sensitiveEnvironmentKeys: string[];
+	status: string;
+	structuredReplacements?: number;
+	textualFilesScanned: number;
+	valuesStored: boolean;
+}
+export interface RunBundlePublication extends Record<string, unknown> {
+	bundleBytes?: number;
+	bytesUploaded?: number;
+	configured?: boolean;
+	error?: string;
+	manifestDigest?: null | string;
+	required?: boolean;
+	reused?: boolean;
+	status: "complete" | "failed" | "not_configured" | "pending";
+	target?: null | string;
+}
+export interface RunBundleCleanup {
+	error?: string;
+	status: "complete" | "failed";
+}
+export interface RunBundleLatestProjection {
+	error?: string;
+	path: string;
+	status: "complete" | "failed";
+}
+export interface RunBundleRetentionSummary extends Record<string, unknown> {
+	currentRunId: string;
+	decidedAt: string;
+	error?: string;
+	policy: {
+		maxAgeDays: null | number;
+		maxRuns: null | number;
+		preserveSuites: string[];
+	};
+	status: "complete" | "failed";
+}
+export interface RunBundleArchive extends Record<string, unknown> {
+	canonicalRunPath: string;
+	cleanup?: RunBundleCleanup;
+	integrity: "sha256";
+	latest?: RunBundleLatestProjection;
+	manifestDigest?: string;
+	manifestPath: string;
+	provenancePath: string;
+	publication: RunBundlePublication;
+	redaction: RunBundleRedaction;
+	retention?: RunBundleRetentionSummary;
+	runId: string;
+	schemaVersion: RunBundleSchemaVersion;
+	status: "complete";
+	storage?: RunBundleStorage;
+}
+export type RunBundleArtifact = StoredRunDocument & {
+	archive: RunBundleArchive;
+};
+export interface RunBundleManifestEntry extends Record<string, unknown> {
+	bytes: number;
+	path: string;
+	sha256: string;
+}
+export interface RunBundleManifest extends Record<string, unknown> {
+	algorithm: "sha256";
+	createdAt: string;
+	digest: string;
+	files: RunBundleManifestEntry[];
+	redaction: RunBundleRedaction;
+	runId: string;
+	schemaVersion: RunBundleSchemaVersion;
+	storage: RunBundleStorage;
+}
+export interface RunBundleSummary {
+	canonicalRunPath: null | string;
+	finishedAt: null | string;
+	manifestDigest: null | string;
+	runId: string;
+	startedAt: null | string;
+	status: null | string;
+}
+export interface RunBundleVerification {
+	checkedFiles: number;
+	errors: string[];
+	manifestDigest?: null | string;
+	ok: boolean;
+	runId: string;
+	storage?: null | RunBundleStorage;
+}
+export declare function loadRunBundleArtifact(productDir: string, runId: unknown): RunBundleArtifact;
+export declare function loadRunBundleManifest(productDir: string, runId: unknown): RunBundleManifest;
+export declare function listRunBundles(productDir: string, options?: {
+	file?: null | string;
+}): RunBundleSummary[];
+export declare function verifyRunBundle(productDir: string, runId: unknown): RunBundleVerification;
+export type VitestSelection = Readonly<{
+	config: null | string;
+	host: Readonly<Record<string, string>>;
+	project: null | string;
+	runner: "auto" | "managed" | "repo";
+}>;
+export type TestGroupSource = "groups" | "implicit";
+export interface DiscoverySummary {
+	activeFiles: number;
+	byGroup: Record<string, number>;
+	byTestType: Record<string, number>;
+	diagnostics: {
+		errors: number;
+		warnings: number;
+	};
+	files: number;
+	groups: number;
+	skippedFiles: number;
+	suites: number;
+}
+declare const DISCOVERY_SCHEMA_VERSION: 10;
+export type DiscoveryTestType = PublicTestType;
+export interface DiscoveryDiagnostic {
+	code: string;
+	groupNames?: string[];
+	message: string;
+	path?: string;
+	severity: "error" | "warning";
+}
+export interface DiscoveryGroup {
+	activeFileCount: number;
+	fileCount: number;
+	name: string;
+	roots: string[];
+	skippedFileCount: number;
+	source: TestGroupSource;
+	suiteCount: number;
+	uses: string[];
+}
+export interface DiscoveryTestContract {
+	authoringApi?: string;
+	summary?: string;
+}
+export interface DiscoverySuite {
+	activeFileCount: number;
+	contract: DiscoveryTestContract;
+	displayName: string;
+	engineId: EngineId;
+	fileCount: number;
+	filePaths: string[];
+	group: string;
+	id: string;
+	locks: string[];
+	name: string;
+	profileId: RunnerProfileId;
+	skippedFileCount: number;
+	suiteLabel: string;
+	testType?: DiscoveryTestType;
+}
+export interface DiscoveryFile {
+	contract: DiscoveryTestContract;
+	displayName: string;
+	engineId: EngineId;
+	group: string;
+	id: string;
+	locks: string[];
+	path: string;
+	profileId: RunnerProfileId;
+	runtimeIsolation: RuntimeIsolationPolicy;
+	skipped: boolean;
+	skipReason: null | string;
+	suiteLabel: string;
+	suiteName: string;
+	testType?: DiscoveryTestType;
+}
+export interface DiscoveryResult {
+	configFile: null | string;
+	diagnostics: DiscoveryDiagnostic[];
+	files: DiscoveryFile[];
+	filters: {
+		diagnostics: "error" | "report";
+		fileNames: string[];
+		group: null | string;
+		runnableOnly: boolean;
+		suiteSelectors: string[];
+		types: RunType[];
+	};
+	groups: DiscoveryGroup[];
+	product: {
+		directory: string;
+		name: string;
+	};
+	schemaVersion: typeof DISCOVERY_SCHEMA_VERSION;
+	source: "testkit-discovery";
+	suites: DiscoverySuite[];
+	summary: DiscoverySummary;
+}
+export interface DiscoverTestsOptions {
+	diagnostics?: "error" | "report";
+	dir?: null | string;
+	file?: null | string | readonly string[];
+	group?: null | string;
+	runnableOnly?: boolean;
+	suite?: null | string | readonly string[];
+	type?: null | string | readonly string[];
+	vitest?: VitestSelection;
+}
+export declare function discoverTests(options?: Readonly<DiscoverTestsOptions>): Promise<DiscoveryResult>;
+export declare function formatDisplayName(value: unknown): string;
+export declare function testTypeContract(testType: DiscoveryTestType | undefined, engineId: EngineId, profileId: RunnerProfileId): DiscoveryTestContract;
+export declare function fileDisplayName(filePath: string): string;
+export interface DesiredRuntimeGraphStatus {
+	instanceCount: number;
+	runtimeIds: string[];
+	runtimeServices: string[];
+	targetServices: string[];
+}
+export type BundleSourcemapStatus = "detected" | "none" | "not-detected-in-sample" | "present";
+export interface BundleCacheStatus {
+	duplicatedSourceCount: number;
+	entryFileCount: number;
+	exists: boolean;
+	fileCount: number;
+	jsFileCount: number;
+	manifest: {
+		entryCount: number;
+		exists: boolean;
+	};
+	path: string;
+	serviceName: string;
+	sizeBytes: number;
+	sourcemapFileCount: null | number;
+	sourcemapStatus: BundleSourcemapStatus;
+	sourceFileCount: number;
+	unmanagedFileCount: number;
+}
+export interface StatusProduct {
+	configFile: null | string;
+	dependencies: string[];
+	dir: string;
+	selectedService: string;
+	services: string[];
+}
+declare const WORKSPACE_SCHEMA_VERSION: 3;
+export type WorkspaceTargetKind = "file" | "project" | "suite";
+export type WorkspaceTargetSource = "discovery" | "latest" | "live";
+export type WorkspaceRunSource = "latest" | "live";
+export interface WorkspaceTargetRef {
+	detail: string;
+	engineId?: null | RunArtifactSuite["engineId"];
+	filePath?: string;
+	group?: null | string;
+	id: string;
+	kind: WorkspaceTargetKind;
+	label: string;
+	profileId?: null | RunArtifactSuite["profileId"];
+	runnable: boolean;
+	source: WorkspaceTargetSource;
+	status?: null | string;
+	suiteName?: null | string;
+	testType?: null | RunArtifactSuite["testType"];
+}
+export interface WorkspaceRunSummary {
+	durationMs: null | number;
+	files: {
+		failed: number;
+		notRun: number;
+		passed: number;
+		skipped: number;
+		total: number;
+	};
+	generatedAt: null | string;
+	groups: {
+		failed: number;
+		passed: number;
+		skipped: number;
+		total: number;
+	};
+	id: null | string;
+	source: WorkspaceRunSource;
+	startedAt: null | string;
+	status: string;
+	suites: {
+		completed: number;
+		failed: number;
+		passed: number;
+		skipped: number;
+		total: number;
+	};
+	types: string[];
+}
+export interface WorkspaceRuntimeGraphStatus {
+	currentRuntimeDirCount: number;
+	desired: DesiredRuntimeGraphStatus | null;
+	exists: boolean;
+	name: string;
+	orphan: boolean;
+	runtimeDirCount: number;
+	staleRuntimeDirCount: number;
+}
+export interface WorkspaceServiceStatus {
+	caches: {
+		bundles: BundleCacheStatus;
+	};
+	hasState: boolean;
+	name: string;
+	product: StatusProduct;
+	runtimeGraphs: WorkspaceRuntimeGraphStatus[];
+	runs: {
+		active: number;
+		stale: number;
+		total: number;
+	};
+	warnings: string[];
+}
+export interface WorkspaceStatus {
+	ok: boolean;
+	results: WorkspaceServiceStatus[];
+}
+export interface WorkspaceInspection {
+	activity: {
+		activeRuns: number;
+		staleRuns: number;
+	};
+	discovery: {
+		configFile: null | string;
+		diagnostics: DiscoveryDiagnostic[];
+		summary: DiscoverySummary;
+	} | null;
+	generatedAt: string;
+	product: DiscoveryResult["product"];
+	runs: {
+		latest: WorkspaceRunSummary | null;
+		live: WorkspaceRunSummary | null;
+	};
+	schemaVersion: typeof WORKSPACE_SCHEMA_VERSION;
+	source: "testkit-workspace";
+	status: WorkspaceStatus;
+	targets: WorkspaceTargetRef[];
+	warnings: string[];
+}
+export interface InspectWorkspaceOptions {
+	dir?: string;
+	group?: null | string;
+	status?: boolean;
+	targetLimit?: number;
+}
+export declare function inspectWorkspace(options?: Readonly<InspectWorkspaceOptions>): Promise<WorkspaceInspection>;
+
+export {};