@plyaz/types 1.5.2 → 1.5.3

package/dist/testing/common/utils/types.d.ts

@@ -68,11 +68,8 @@ import type { UnknownRecord } from 'type-fest';
  * ```
  */
 export interface SubscriptionInfo<T = unknown> {
-    /** Unique identifier for the subscription */
     id: string;
-    /** Mocked callback function that receives subscription data */
     callback: Vitest.MockedFunction<(data: T) => void>;
-    /** Function to unsubscribe from the event */
     unsubscribe: () => void;
 }
 /**
@@ -99,25 +96,15 @@ export interface SubscriptionInfo<T = unknown> {
  * ```
  */
 export interface SubscriptionTracker<T = unknown> {
-    /** Track a new subscription with optional ID */
     track: (subscribeFn: (callback: (data: T) => void) => () => void, id?: string) => SubscriptionInfo<T>;
-    /** Unsubscribe a specific subscription by ID */
     unsubscribe: (id: string) => void;
-    /** Unsubscribe all tracked subscriptions */
     unsubscribeAll: () => void;
-    /** Get the number of times a subscription callback was called */
     getCallCount: (id: string) => number;
-    /** Get the data from the last callback invocation */
     getLastCall: (id: string) => T | null;
-    /** Get all data from all callback invocations */
     getAllCalls: (id: string) => T[];
-    /** Reset all subscriptions and their call history */
     reset: () => void;
-    /** Reset only the callback history, keeping subscriptions active */
     resetCallbacks: () => void;
-    /** Get list of active subscription IDs */
     getActiveSubscriptions: () => string[];
-    /** Check if a subscription is currently active */
     hasSubscription: (id: string) => boolean;
 }
 /**
@@ -142,13 +129,9 @@ export interface SubscriptionTracker<T = unknown> {
  * ```
  */
 export interface CreateTrackedEventEmitterReturn<T> {
-    /** Subscribe to an event with a callback, returns unsubscribe function */
     on: (event: string, callback: (data: T) => void) => () => void;
-    /** Emit an event with data to all listeners */
     emit: (event: string, data: T) => void;
-    /** Remove all listeners for a specific event or all events */
     removeAllListeners: (event?: string) => void;
-    /** Subscription tracker for monitoring event activity */
     tracker: SubscriptionTracker<T>;
 }
 /**
@@ -175,17 +158,11 @@ export interface CreateTrackedEventEmitterReturn<T> {
  * ```
  */
 export interface DeferredPromise<T = void> {
-    /** The promise that can be awaited */
     promise: Promise<T>;
-    /** Function to resolve the promise with a value */
     resolve: (value: T) => void;
-    /** Function to reject the promise with an error */
     reject: (error: unknown) => void;
-    /** Whether the promise has been resolved */
     isResolved: boolean;
-    /** Whether the promise has been rejected */
     isRejected: boolean;
-    /** Whether the promise is still pending */
     isPending: boolean;
 }
 /**
@@ -203,11 +180,8 @@ export interface DeferredPromise<T = void> {
  * ```
  */
 export interface WaitOptions {
-    /** Maximum time to wait in milliseconds (default: 5000) */
     timeout?: number;
-    /** Polling interval in milliseconds (default: 50) */
     interval?: number;
-    /** Custom error message if timeout is reached */
     message?: string;
 }
 /**
@@ -233,17 +207,11 @@ export interface WaitOptions {
  * ```
  */
 export interface RetryOptions {
-    /** Maximum number of retry attempts (default: 3) */
     attempts?: number;
-    /** Initial delay between retries in ms (default: 100) */
     delay?: number;
-    /** Backoff multiplier for exponential delay (default: 2) */
     backoff?: number;
-    /** Maximum delay between retries in ms (default: 10000) */
     maxDelay?: number;
-    /** Function to determine if retry should occur based on error */
     shouldRetry?: (error: Error, attempt: number) => boolean;
-    /** Callback invoked before each retry attempt */
     onRetry?: (error: Error, attempt: number) => void;
 }
 /**
@@ -270,15 +238,10 @@ export interface RetryOptions {
  * ```
  */
 export interface MockAsync<T = void> {
-    /** The mock function that returns promises */
     mock: Vitest.Mock;
-    /** Resolve the next pending promise with a value */
     resolve: (value: T) => void;
-    /** Reject the next pending promise with an error */
     reject: (error: unknown) => void;
-    /** Reset the mock and clear all pending promises */
     reset: () => void;
-    /** Array of currently pending promises */
     pending: DeferredPromise<T>[];
 }
 /**
@@ -300,15 +263,10 @@ export interface MockAsync<T = void> {
  * ```
  */
 export interface ControllableTimer {
-    /** Start the timer */
     start: () => void;
-    /** Stop the timer */
     stop: () => void;
-    /** Manually advance the timer by specified milliseconds */
     tick: (ms: number) => void;
-    /** Reset the timer to zero */
     reset: () => void;
-    /** Get elapsed time in milliseconds */
     elapsed: number;
 }
 /**
@@ -336,19 +294,12 @@ export interface ControllableTimer {
  * ```
  */
 export interface TestEventEmitter<T = unknown> {
-    /** Add event listener, returns unsubscribe function */
     on: (handler: (data: T) => void) => () => void;
-    /** Add one-time event listener, returns unsubscribe function */
     once: (handler: (data: T) => void) => () => void;
-    /** Emit event synchronously to all listeners */
     emit: (data: T) => void;
-    /** Emit event and wait for all async handlers to complete */
     emitAsync: (data: T) => Promise<void>;
-    /** Remove all event listeners */
     removeAllListeners: () => void;
-    /** Get current number of listeners */
     listenerCount: () => number;
-    /** Wait for the next event with optional timeout */
     waitForEvent: (timeout?: number) => Promise<T>;
 }
 /**
@@ -378,15 +329,10 @@ export interface TestEventEmitter<T = unknown> {
  * ```
  */
 export interface AsyncTestStep<T = unknown> {
-    /** Descriptive name for the step */
     name: string;
-    /** Function to execute for this step */
     action: () => Promise<T> | T;
-    /** Optional delay before executing this step (ms) */
     delay?: number;
-    /** Optional assertion to run after step completes */
     assertion?: (result: T) => void | Promise<void>;
-    /** Optional error handler for this step */
     onError?: (error: Error) => void;
 }
 /**
@@ -409,13 +355,9 @@ export interface AsyncTestStep<T = unknown> {
  * ```
  */
 export interface ConcurrentTestOptions {
-    /** Array of async operations to execute */
     operations: Array<() => Promise<unknown>>;
-    /** Maximum number of operations to run simultaneously */
     maxConcurrency?: number;
-    /** Timeout for all operations in milliseconds */
     timeout?: number;
-    /** Whether to expect some operations to fail */
     expectErrors?: boolean;
 }
 /**
@@ -435,13 +377,9 @@ export interface ConcurrentTestOptions {
  * ```
  */
 export interface RateLimitTestOptions {
-    /** The operation to test for rate limiting */
     operation: () => Promise<unknown>;
-    /** Target requests per second */
     requestsPerSecond: number;
-    /** How long to run the test in milliseconds */
     duration: number;
-    /** Whether to expect throttling to occur */
     expectThrottle?: boolean;
 }
 /**
@@ -467,13 +405,9 @@ export interface RateLimitTestOptions {
  * ```
  */
 export interface StateTransition<T> {
-    /** Expected state before transition */
     from: T;
-    /** Expected state after transition */
     to: T;
-    /** Action that triggers the transition */
     action: () => Promise<void> | void;
-    /** Optional delay after action before checking state */
     delay?: number;
 }
 /**
@@ -490,9 +424,7 @@ export interface StateTransition<T> {
  * ```
  */
 export interface EventSequence {
-    /** Expected event names in order */
     events: string[];
-    /** Whether events must occur in exact order (default: true) */
     strict?: boolean;
 }
 /**
@@ -518,11 +450,8 @@ export interface EventSequence {
  * ```
  */
 export interface AsyncCleanupItem {
-    /** Descriptive name for the cleanup operation */
     name: string;
-    /** Cleanup function to execute */
     cleanup: () => Promise<void> | void;
-    /** Optional timeout for cleanup operation */
     timeout?: number;
 }
 /**
@@ -544,15 +473,10 @@ export interface AsyncCleanupItem {
  * ```
  */
 export interface PollingTestOptions {
-    /** Function to call on each poll */
     pollFn: () => Promise<unknown> | unknown;
-    /** Condition to check if polling should stop */
     condition: (result: unknown) => boolean;
-    /** Maximum number of polling attempts */
     maxAttempts?: number;
-    /** Interval between polls in milliseconds */
     interval?: number;
-    /** Callback invoked after each poll */
     onPoll?: (attempt: number, result: unknown) => void;
 }
 /**
@@ -699,6 +623,24 @@ export interface TestBedConfig {
     imports?: unknown[];
     exports?: unknown[];
 }
+/**
+ * Options for testing NestJS controllers.
+ * Configures controller dependencies and mocking.
+ *
+ * @template T - Type of controller being tested
+ *
+ * @example
+ * ```typescript
+ * const options: ControllerTestHarnessOptions<UserController> = {
+ *   Controller: UserController,
+ *   dependencies: [
+ *     { token: UserService, value: mockUserService },
+ *     { token: AuthGuard, value: mockAuthGuard }
+ *   ],
+ *   mockLogger: true
+ * };
+ * ```
+ */
 export interface ControllerTestHarnessOptions<T> {
     Controller: Type<T>;
     dependencies?: Array<{
@@ -707,6 +649,19 @@ export interface ControllerTestHarnessOptions<T> {
     }>;
     mockLogger?: boolean;
 }
+/**
+ * Expected response from middleware validation.
+ * Used to assert middleware behavior in tests.
+ *
+ * @example
+ * ```typescript
+ * const expected: ValidateMiddlwareResponseExpected = {
+ *   type: 'redirect',
+ *   url: '/login',
+ *   status: 302
+ * };
+ * ```
+ */
 export interface ValidateMiddlwareResponseExpected {
     type: 'next' | 'redirect' | 'rewrite' | 'response';
     url?: string;
@@ -739,6 +694,21 @@ export interface ServiceTestHarnessOptions<T> {
     mockLogger?: boolean;
 }
 export type NestModule = Type<unknown>;
+/**
+ * Options for testing NestJS modules.
+ * Configures module dependencies and overrides.
+ *
+ * @example
+ * ```typescript
+ * const options: ModuleTestHarnessOptions = {
+ *   Module: UserModule,
+ *   overrideProviders: [
+ *     { token: DatabaseService, useValue: mockDb },
+ *     { token: CacheService, useFactory: () => mockCache }
+ *   ]
+ * };
+ * ```
+ */
 export interface ModuleTestHarnessOptions {
     Module: NestModule;
     overrideProviders?: Array<{
@@ -747,6 +717,18 @@ export interface ModuleTestHarnessOptions {
         useFactory?: (...args: unknown[]) => unknown;
     }>;
 }
+/**
+ * Options for testing Next.js pages.
+ * Extends React Testing Library render options with Next.js specific mocks.
+ *
+ * @example
+ * ```typescript
+ * const options: NextPageTestOptions = {
+ *   router: { pathname: '/dashboard', query: { id: '123' } },
+ *   mockModules: ['router', 'image']
+ * };
+ * ```
+ */
 export interface NextPageTestOptions extends RenderOptions {
     router?: Partial<MockNextRouter>;
     mockModules?: Array<'router' | 'image' | 'link' | 'head'>;
@@ -805,12 +787,43 @@ export interface MiddlewareTestContext {
     expectHeader: (name: string, value: string) => void;
     expectNext: () => void;
 }
+/**
+ * Options for testing Next.js App Router hooks.
+ * Provides App Router specific context for hook testing.
+ *
+ * @template TProps - Type of hook props
+ *
+ * @example
+ * ```typescript
+ * const options: AppRouterHookTestOptions<UseUserProps> = {
+ *   pathname: '/user/profile',
+ *   searchParams: { tab: 'settings' },
+ *   params: { userId: '123' }
+ * };
+ * ```
+ */
 export interface AppRouterHookTestOptions<TProps> extends RenderHookOptions<TProps> {
     pathname?: string;
     searchParams?: Record<string, string | string[]>;
     params?: Record<string, string | string[]>;
 }
 export type UserEvent = UserEventLib;
+/**
+ * Configuration for user event simulation.
+ * Controls timing and behavior of simulated user interactions.
+ *
+ * @example
+ * ```typescript
+ * const config: UserEventConfig = {
+ *   delay: 10, // 10ms between keystrokes
+ *   advanceTimers: vi.advanceTimersByTime,
+ *   applyAccept: true,
+ *   autoModify: true,
+ *   skipAutoClose: false,
+ *   writeToClipboard: true
+ * };
+ * ```
+ */
 export interface UserEventConfig {
     delay?: number;
     advanceTimers?: (ms: number) => void | Promise<void>;
@@ -859,6 +872,19 @@ export interface InteractionSequence {
         distance?: number;
     };
 }
+/**
+ * Mock child process instance for testing.
+ * Simulates Node.js child process behavior.
+ *
+ * @example
+ * ```typescript
+ * const mockProcess: MockChildProcessInstance = {
+ *   stdout: { on: { mock: { calls: [] } } },
+ *   stderr: { on: { mock: { calls: [] } } },
+ *   on: { mock: { calls: [] } }
+ * };
+ * ```
+ */
 export interface MockChildProcessInstance {
     stdout: {
         on: {
@@ -881,6 +907,21 @@ export interface MockChildProcessInstance {
     };
     [key: string]: unknown;
 }
+/**
+ * Utilities for testing process-level operations.
+ * Provides helpers for simulating process events and signals.
+ *
+ * @example
+ * ```typescript
+ * const utils: ProcessTestUtils = {
+ *   simulateSignal: (signal) => process.emit(signal),
+ *   expectExit: (code) => expect(process.exit).toHaveBeenCalledWith(code),
+ *   captureOutput: () => ({ stdout: [], stderr: [] }),
+ *   simulateUncaughtException: (error) => process.emit('uncaughtException', error),
+ *   simulateUnhandledRejection: (reason) => process.emit('unhandledRejection', reason)
+ * };
+ * ```
+ */
 export interface ProcessTestUtils {
     simulateSignal: (signal: string) => void;
     expectExit: (code?: number) => void;
@@ -891,6 +932,21 @@ export interface ProcessTestUtils {
     simulateUncaughtException: (error: Error) => void;
     simulateUnhandledRejection: (reason: unknown) => void;
 }
+/**
+ * Utilities for testing child process operations.
+ * Provides helpers for asserting and simulating child process behavior.
+ *
+ * @example
+ * ```typescript
+ * const utils: ChildProcessTestUtils = {
+ *   expectCommand: (cmd, args) => expect(spawn).toHaveBeenCalledWith(cmd, args),
+ *   simulateOutput: (stdout, stderr) => mockProcess.stdout.emit('data', stdout),
+ *   simulateError: (error) => mockProcess.emit('error', error),
+ *   simulateExit: (code) => mockProcess.emit('exit', code),
+ *   getLastProcess: () => mockProcesses[mockProcesses.length - 1]
+ * };
+ * ```
+ */
 export interface ChildProcessTestUtils {
     expectCommand: (command: string, args?: string[]) => void;
     simulateOutput: (stdout: string, stderr?: string) => void;
@@ -898,12 +954,41 @@ export interface ChildProcessTestUtils {
     simulateExit: (code: number) => void;
     getLastProcess: () => unknown;
 }
+/**
+ * Utilities for testing stream operations.
+ * Provides helpers for simulating stream behavior.
+ *
+ * @example
+ * ```typescript
+ * const utils: StreamTestUtils = {
+ *   pipeData: (data) => stream.write(data),
+ *   endStream: () => stream.end(),
+ *   expectPipedTo: (dest) => expect(stream.pipe).toHaveBeenCalledWith(dest),
+ *   getWrittenData: () => writtenChunks
+ * };
+ * ```
+ */
 export interface StreamTestUtils {
     pipeData: (data: string | globalThis.Buffer) => void;
     endStream: () => void;
     expectPipedTo: (destination: unknown) => void;
     getWrittenData: () => Array<string | globalThis.Buffer>;
 }
+/**
+ * Utilities for testing event-driven systems.
+ * Provides helpers for event simulation and assertion.
+ *
+ * @example
+ * ```typescript
+ * const utils: EventDrivenTestUtils = {
+ *   emitter: createMockEventEmitter(),
+ *   expectEvent: (event, payload) => expect(emitter.emit).toHaveBeenCalledWith(event, payload),
+ *   expectNoEvent: (event) => expect(emitter.emit).not.toHaveBeenCalledWith(event),
+ *   simulateEvents: async (events) => { // simulate },
+ *   getEventHistory: () => eventHistory
+ * };
+ * ```
+ */
 export interface EventDrivenTestUtils {
     emitter: MockEventEmitter;
     expectEvent: (event: string, payload?: unknown) => void;
@@ -911,18 +996,60 @@ export interface EventDrivenTestUtils {
     simulateEvents: (events: Array<SimulatedEvent>) => Promise<void>;
     getEventHistory: () => Array<EventHistoryEntry>;
 }
+/**
+ * Test server instance for integration testing.
+ * Provides methods to manage a test server lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const server: TestServer = {
+ *   url: 'http://localhost:3000',
+ *   port: 3000,
+ *   close: async () => await serverInstance.close(),
+ *   on: (event, handler) => serverInstance.on(event, handler)
+ * };
+ * ```
+ */
 export interface TestServer {
     url: string;
     port: number;
     close: () => Promise<void>;
     on: (event: string, handler: Function) => void;
 }
+/**
+ * Result from a single concurrent operation.
+ * Contains success status and timing information.
+ *
+ * @example
+ * ```typescript
+ * const result: ConcurrentOperationResult = {
+ *   success: true,
+ *   result: { id: 1, status: 'uploaded' },
+ *   duration: 250
+ * };
+ * ```
+ */
 export interface ConcurrentOperationResult {
     success: boolean;
     result?: unknown;
     error?: Error;
     duration: number;
 }
+/**
+ * Aggregated results from concurrent operations testing.
+ * Contains statistics across all concurrent operations.
+ *
+ * @example
+ * ```typescript
+ * const result: ConcurrentTestResult = {
+ *   results: [ ...operation results ],
+ *   totalDuration: 5000,
+ *   successCount: 95,
+ *   errorCount: 5,
+ *   averageDuration: 250
+ * };
+ * ```
+ */
 export interface ConcurrentTestResult {
     results: ConcurrentOperationResult[];
     totalDuration: number;
@@ -930,48 +1057,168 @@ export interface ConcurrentTestResult {
     errorCount: number;
     averageDuration: number;
 }
+/**
+ * Result from a single rate-limited request.
+ * Contains timing and success information.
+ *
+ * @example
+ * ```typescript
+ * const result: RateLimitResult = {
+ *   timestamp: Date.now(),
+ *   success: true
+ * };
+ * ```
+ */
 export interface RateLimitResult {
     timestamp: number;
     success: boolean;
     error?: Error;
 }
+/**
+ * Aggregated results from rate limit testing.
+ * Contains actual rate and throttling information.
+ *
+ * @example
+ * ```typescript
+ * const result: RateLimitTestResult = {
+ *   results: [ ...individual results ],
+ *   actualRate: 9.5, // requests per second
+ *   wasThrottled: true
+ * };
+ * ```
+ */
 export interface RateLimitTestResult {
     results: RateLimitResult[];
     actualRate: number;
     wasThrottled: boolean;
 }
+/**
+ * Single polling attempt record.
+ * Contains attempt number and result data.
+ *
+ * @example
+ * ```typescript
+ * const attempt: PollingAttempt = {
+ *   attempt: 3,
+ *   result: { status: 'processing' },
+ *   timestamp: Date.now()
+ * };
+ * ```
+ */
 export interface PollingAttempt {
     attempt: number;
     result: unknown;
     timestamp: number;
 }
+/**
+ * Results from polling operation testing.
+ * Contains attempt history and success status.
+ *
+ * @example
+ * ```typescript
+ * const result: PollingTestResult = {
+ *   attempts: [ ..polling attempts ],
+ *   conditionMet: true,
+ *   totalAttempts: 5,
+ *   totalDuration: 4500
+ * };
+ * ```
+ */
 export interface PollingTestResult {
     attempts: PollingAttempt[];
     conditionMet: boolean;
     totalAttempts: number;
     totalDuration: number;
 }
+/**
+ * Results from debounce testing.
+ * Tracks call count and timing.
+ *
+ * @example
+ * ```typescript
+ * const result: DebounceTestResult = {
+ *   callCount: 1,
+ *   lastCallTime: Date.now()
+ * };
+ * ```
+ */
 export interface DebounceTestResult {
     callCount: number;
     lastCallTime: number;
 }
+/**
+ * Single throttled call record.
+ * Contains arguments and delay information.
+ *
+ * @example
+ * ```typescript
+ * const call: ThrottleCall = {
+ *   args: ['data', { id: 1 }],
+ *   delay: 100
+ * };
+ * ```
+ */
 export interface ThrottleCall {
     args: unknown[];
     delay: number;
 }
+/**
+ * Result from throttle testing.
+ * Indicates whether call was executed.
+ *
+ * @example
+ * ```typescript
+ * const result: ThrottleResult = {
+ *   called: true,
+ *   args: ['test', 123]
+ * };
+ * ```
+ */
 export interface ThrottleResult {
     called: boolean;
     args?: unknown[];
 }
+/**
+ * Async testing scenario definition.
+ * Defines setup, action, and verification steps.
+ *
+ * @template T - Type of value returned by action
+ *
+ * @example
+ * ```typescript
+ * const scenario: AsyncScenario<User> = {
+ *   name: 'Create user flow',
+ *   setup: async () => await db.connect(),
+ *   action: async () => await createUser({ name: 'Test' }),
+ *   verify: (user) => expect(user.id).toBeDefined(),
+ *   cleanup: async () => await db.disconnect(),
+ *   expectedHooks: ['beforeCreate', 'afterCreate']
+ * };
+ * ```
+ */
 export interface AsyncScenario<T = void> {
     name: string;
     setup: () => Promise<void>;
     action: () => Promise<T>;
     verify: (result: T) => void | Promise<void>;
     cleanup?: () => Promise<void>;
-    /** Expected hooks */
     expectedHooks: string[];
 }
+/**
+ * Options for waiting for value changes.
+ * Configures polling and comparison behavior.
+ *
+ * @template T - Type of value being watched
+ *
+ * @example
+ * ```typescript
+ * const options: WaitForChangeOptions<number> = {
+ *   timeout: 5000,
+ *   interval: 100,
+ *   compareFn: (a, b) => Math.abs(a - b) > 0.01
+ * };
+ * ```
+ */
 export interface WaitForChangeOptions<T> {
     timeout?: number;
     interval?: number;
@@ -1004,24 +1251,92 @@ export interface PerformanceMetrics {
     p99: number;
     runs: number[];
 }
+/**
+ * Options for timing measurements.
+ * Configures warmup and run counts.
+ *
+ * @example
+ * ```typescript
+ * const options: MeasureTimeOptions = {
+ *   warmup: 10,
+ *   runs: 100
+ * };
+ * ```
+ */
 export interface MeasureTimeOptions {
     warmup?: number;
     runs?: number;
 }
+/**
+ * Result from timing measurement.
+ * Contains result value and performance metrics.
+ *
+ * @template T - Type of value returned by measured function
+ *
+ * @example
+ * ```typescript
+ * const result: MeasureTimeResult<string> = {
+ *   result: 'processed',
+ *   duration: 125,
+ *   metrics: { ...performance metrics }
+ * };
+ * ```
+ */
 export interface MeasureTimeResult<T> {
     result: T;
     duration: number;
     metrics?: PerformanceMetrics;
 }
+/**
+ * Benchmark results by function name.
+ * Maps function names to their performance metrics.
+ *
+ * @example
+ * ```typescript
+ * const result: BenchmarkResult = {
+ *   'sort': { mean: 25, median: 24, ... },
+ *   'filter': { mean: 15, median: 14, ... }
+ * };
+ * ```
+ */
 export interface BenchmarkResult {
     [functionName: string]: PerformanceMetrics;
 }
+/**
+ * Options for load testing.
+ * Configures duration, concurrency, and ramp-up.
+ *
+ * @example
+ * ```typescript
+ * const options: LoadTestOptions = {
+ *   duration: 60000, // 1 minute
+ *   concurrency: 50,
+ *   rampUp: 5000, // 5 seconds
+ *   onProgress: (stats) => console.log('Progress:', stats)
+ * };
+ * ```
+ */
 export interface LoadTestOptions {
     duration?: number;
     concurrency?: number;
     rampUp?: number;
     onProgress?: (stats: LoadTestStats) => void;
 }
+/**
+ * Statistics collected during load testing.
+ * Contains request counts and latency data.
+ *
+ * @example
+ * ```typescript
+ * const stats: LoadTestStats = {
+ *   totalRequests: 5000,
+ *   successfulRequests: 4950,
+ *   failedRequests: 50,
+ *   latencies: [120, 125, 130, ...],
+ *   errors: [ ..rror objects ]
+ * };
+ * ```
+ */
 export interface LoadTestStats {
     totalRequests: number;
     successfulRequests: number;
@@ -1054,35 +1369,146 @@ export interface LoadTestResult {
     throughput: number;
     errors: Error[];
 }
+/**
+ * Options for CPU profiling.
+ * Configures sampling interval.
+ *
+ * @example
+ * ```typescript
+ * const options: ProfileCPUOptions = {
+ *   sampleInterval: 10 // sample every 10ms
+ * };
+ * ```
+ */
 export interface ProfileCPUOptions {
     sampleInterval?: number;
 }
+/**
+ * CPU profile data.
+ * Contains samples and timing information.
+ *
+ * @example
+ * ```typescript
+ * const profile: CPUProfile = {
+ *   samples: [15, 20, 18, 22, 25],
+ *   duration: 1000
+ * };
+ * ```
+ */
 export interface CPUProfile {
     samples: number[];
     duration: number;
 }
+/**
+ * Result from CPU profiling.
+ * Contains function result and CPU profile.
+ *
+ * @template T - Type of value returned by profiled function
+ *
+ * @example
+ * ```typescript
+ * const result: ProfileCPUResult<number> = {
+ *   result: 42,
+ *   profile: { samples: [...CPU samples ], duration: 1000 }
+ * };
+ * ```
+ */
 export interface ProfileCPUResult<T> {
     result: T;
     profile: CPUProfile;
 }
+/**
+ * Options for scalability testing.
+ * Configures expected complexity and tolerance.
+ *
+ * @example
+ * ```typescript
+ * const options: ScalabilityTestOptions = {
+ *   expectedComplexity: 'linear',
+ *   tolerance: 0.1 // 10% tolerance
+ * };
+ * ```
+ */
 export interface ScalabilityTestOptions {
     expectedComplexity?: 'constant' | 'logarithmic' | 'linear' | 'quadratic';
     tolerance?: number;
 }
+/**
+ * Single scalability measurement point.
+ * Contains input size and execution time.
+ *
+ * @example
+ * ```typescript
+ * const measurement: ScalabilityMeasurement = {
+ *   size: 1000,
+ *   time: 250 // milliseconds
+ * };
+ * ```
+ */
 export interface ScalabilityMeasurement {
     size: number;
     time: number;
 }
+/**
+ * Results from scalability testing.
+ * Contains complexity analysis and measurements.
+ *
+ * @example
+ * ```typescript
+ * const result: ScalabilityTestResult = {
+ *   measurements: [ ...measurement points ],
+ *   complexity: 'O(n)',
+ *   isWithinExpected: true
+ * };
+ * ```
+ */
 export interface ScalabilityTestResult {
     measurements: ScalabilityMeasurement[];
     complexity: string;
     isWithinExpected: boolean;
 }
-export interface PerformanceComparisonOptions {
-    runs?: number;
-    chart?: boolean;
-}
-export interface PerformanceComparisonInput<T> {
+/**
+ * Options for performance comparison testing.
+ * Configures comparison runs and visualization preferences.
+ *
+ * @example
+ * ```typescript
+ * const options: PerformanceComparisonOptions = {
+ *   runs: 100,
+ *   chart: true
+ * };
+ *
+ * const result = await comparePerformance([
+ *   { name: 'quickSort', fn: () => quickSort(data) },
+ *   { name: 'mergeSort', fn: () => mergeSort(data) }
+ * ], options);
+ * ```
+ */
+export interface PerformanceComparisonOptions {
+    runs?: number;
+    chart?: boolean;
+}
+/**
+ * Input data for performance comparison testing.
+ * Represents a named test case with associated value or function.
+ *
+ * @template T - Type of the comparison input value
+ *
+ * @example
+ * ```typescript
+ * const inputs: PerformanceComparisonInput<() => number[]>[] = [
+ *   {
+ *     name: 'Bubble Sort',
+ *     value: () => bubbleSort([...testData])
+ *   },
+ *   {
+ *     name: 'Quick Sort',
+ *     value: () => quickSort([...testData])
+ *   }
+ * ];
+ * ```
+ */
+export interface PerformanceComparisonInput<T> {
     name: string;
     value: T;
 }
@@ -1106,33 +1532,152 @@ export interface MemoryMeasurement {
     delta: number;
     peak: number;
 }
+/**
+ * Options for memory measurement during testing.
+ * Configures garbage collection and test run parameters.
+ *
+ * @example
+ * ```typescript
+ * const options: MeasureMemoryOptions = {
+ *   forceGC: true,
+ *   runs: 5
+ * };
+ *
+ * const result = await measureMemory(() => {
+ *   return processLargeDataset(data);
+ * }, options);
+ * ```
+ */
 export interface MeasureMemoryOptions {
     forceGC?: boolean;
     runs?: number;
 }
+/**
+ * Result from memory measurement testing.
+ * Contains the function result and memory usage statistics.
+ *
+ * @template T - Type of the measured function's return value
+ *
+ * @example
+ * ```typescript
+ * const result: MeasureMemoryResult<ProcessedData> = {
+ *   result: processedData,
+ *   memory: {
+ *     before: 50 * 1024 * 1024,
+ *     after: 75 * 1024 * 1024,
+ *     delta: 25 * 1024 * 1024,
+ *     peak: 80 * 1024 * 1024
+ *   }
+ * };
+ * ```
+ */
 export interface MeasureMemoryResult<T> {
     result: T;
     memory: MemoryMeasurement;
 }
+/**
+ * Performance constraints for testing operations.
+ * Defines maximum acceptable limits for time, memory, and throughput.
+ *
+ * @example
+ * ```typescript
+ * const constraints: PerformanceConstraints = {
+ *   maxTime: 1000, // 1 second
+ *   maxMemory: 100 * 1024 * 1024, // 100MB
+ *   minThroughput: 1000 // 1000 operations per second
+ * };
+ *
+ * await assertPerformance(() => processData(), constraints);
+ * ```
+ */
 export interface PerformanceConstraints {
     maxTime?: number;
     maxMemory?: number;
     minThroughput?: number;
 }
+/**
+ * Options for performance assertion testing.
+ * Configures test runs and duration for performance validation.
+ *
+ * @example
+ * ```typescript
+ * const options: AssertPerformanceOptions = {
+ *   runs: 10,
+ *   duration: 5000 // 5 seconds total test duration
+ * };
+ *
+ * await assertPerformance(() => {
+ *   return expensiveOperation();
+ * }, constraints, options);
+ * ```
+ */
 export interface AssertPerformanceOptions {
     runs?: number;
     duration?: number;
 }
+/**
+ * Entry in event history tracking.
+ * Records event name, payload, and timestamp for testing event sequences.
+ *
+ * @example
+ * ```typescript
+ * const entry: EventHistoryEntry = {
+ *   event: 'user:login',
+ *   payload: { userId: '123', timestamp: Date.now() },
+ *   timestamp: 1640995200000
+ * };
+ * ```
+ */
 export interface EventHistoryEntry {
     event: string;
     payload: unknown;
     timestamp: number;
 }
+/**
+ * Configuration for simulating events in tests.
+ * Defines event name, payload, and optional delay for event simulation.
+ *
+ * @example
+ * ```typescript
+ * const simulatedEvents: SimulatedEvent[] = [
+ *   {
+ *     event: 'connect',
+ *     payload: { connectionId: 'conn-123' }
+ *   },
+ *   {
+ *     event: 'message',
+ *     payload: { text: 'Hello World' },
+ *     delay: 100
+ *   },
+ *   {
+ *     event: 'disconnect',
+ *     delay: 5000
+ *   }
+ * ];
+ * ```
+ */
 export interface SimulatedEvent {
     event: string;
     payload?: unknown;
     delay?: number;
 }
+/**
+ * Configuration options for mocking WebSocket connections.
+ * Defines WebSocket properties and state for testing.
+ *
+ * @example
+ * ```typescript
+ * const options: WebSocketMockOptions = {
+ *   url: 'ws://localhost:8080',
+ *   protocol: 'chat',
+ *   extensions: 'permessage-deflate',
+ *   readyState: WebSocket.OPEN,
+ *   bufferedAmount: 0
+ * };
+ *
+ * const mockWS = createMockWebSocket(options);
+ * ```
+ */
 export interface WebSocketMockOptions {
     url?: string;
     protocol?: string;
@@ -1140,6 +1685,21 @@ export interface WebSocketMockOptions {
     readyState?: number;
     bufferedAmount?: number;
 }
+/**
+ * Configuration options for mocking WebSocket servers.
+ * Defines server properties and connection limits for testing.
+ *
+ * @example
+ * ```typescript
+ * const serverOptions: WebSocketServerMockOptions = {
+ *   port: 8080,
+ *   host: 'localhost',
+ *   maxClients: 100
+ * };
+ *
+ * const mockServer = createMockWebSocketServer(serverOptions);
+ * ```
+ */
 export interface WebSocketServerMockOptions {
     port?: number;
     host?: string;
@@ -1169,6 +1729,24 @@ export interface WebSocketTestScenario {
     shouldError?: boolean;
     errorMessage?: string;
 }
+/**
+ * Configuration options for WebSocket connections in tests.
+ * Defines connection parameters and behavior settings.
+ *
+ * @example
+ * ```typescript
+ * const connectionOptions: WebSocketConnectionOptions = {
+ *   url: 'wss://api.example.com/ws',
+ *   protocols: ['chat', 'notifications'],
+ *   headers: {
+ *     'Authorization': 'Bearer token123'
+ *   },
+ *   timeout: 10000
+ * };
+ *
+ * const ws = await connectWebSocket(connectionOptions);
+ * ```
+ */
 export interface WebSocketConnectionOptions {
     url: string;
     protocols?: string | string[];
@@ -1200,6 +1778,28 @@ export interface FileOperationTest {
     expectedFiles?: Map<string, string | globalThis.Buffer>;
     expectedError?: string | RegExp;
 }
+/**
+ * Test configuration for process signals.
+ * Defines signal name and expected behavior for testing signal handling.
+ *
+ * @example
+ * ```typescript
+ * const signalTests: SignalTest[] = [
+ *   {
+ *     signal: 'SIGTERM',
+ *     expectedBehavior: () => {
+ *       expect(gracefulShutdown).toHaveBeenCalled();
+ *     }
+ *   },
+ *   {
+ *     signal: 'SIGINT',
+ *     expectedBehavior: () => {
+ *       expect(process.exit).toHaveBeenCalledWith(0);
+ *     }
+ *   }
+ * ];
+ * ```
+ */
 export interface SignalTest {
     signal: string;
     expectedBehavior: () => void;
@@ -1241,17 +1841,82 @@ export interface AriaAttributes {
     role?: string;
     tabIndex?: number;
 }
+/**
+ * Test configuration for keyboard navigation behavior.
+ * Defines element, key press, and expected navigation outcome.
+ *
+ * @example
+ * ```typescript
+ * const navTests: KeyboardNavigationTest[] = [
+ *   {
+ *     element: submitButton,
+ *     key: 'Enter',
+ *     expectedBehavior: 'activate'
+ *   },
+ *   {
+ *     element: inputField,
+ *     key: 'Tab',
+ *     expectedBehavior: 'navigate',
+ *     expectedTarget: nextButton
+ *   }
+ * ];
+ * ```
+ */
 export interface KeyboardNavigationTest {
     element: HTMLElement;
     key: string;
     expectedBehavior: 'focus' | 'activate' | 'navigate' | 'ignore';
     expectedTarget?: HTMLElement;
 }
+/**
+ * Test configuration for screen reader accessibility.
+ * Defines element and expected screen reader text output.
+ *
+ * @example
+ * ```typescript
+ * const screenReaderTests: ScreenReaderTest[] = [
+ *   {
+ *     element: submitButton,
+ *     expectedText: 'Submit form button',
+ *     includeHidden: false
+ *   },
+ *   {
+ *     element: errorMessage,
+ *     expectedText: /error|invalid|required/i,
+ *     includeHidden: true
+ *   }
+ * ];
+ * ```
+ */
 export interface ScreenReaderTest {
     element: HTMLElement;
     expectedText: string | RegExp;
     includeHidden?: boolean;
 }
+/**
+ * Configuration for lifecycle hook testing.
+ * Defines hook properties and execution characteristics.
+ *
+ * @example
+ * ```typescript
+ * const hooks: LifecycleHook[] = [
+ *   {
+ *     name: 'componentDidMount',
+ *     method: 'componentDidMount',
+ *     phase: 'mount',
+ *     required: true,
+ *     async: false
+ *   },
+ *   {
+ *     name: 'onModuleInit',
+ *     method: 'onModuleInit',
+ *     phase: 'init',
+ *     required: false,
+ *     async: true
+ *   }
+ * ];
+ * ```
+ */
 export interface LifecycleHook {
     name: string;
     method: string;
@@ -1289,6 +1954,31 @@ export interface ComponentLifecycleTest {
         expectedHooksAfter: string[];
     }>;
 }
+/**
+ * Interface for services that support NestJS lifecycle hooks.
+ * Defines optional lifecycle methods for service initialization and cleanup.
+ *
+ * @example
+ * ```typescript
+ * class DatabaseService implements ServiceWithLifecycle {
+ *   async onModuleInit() {
+ *     await this.connect();
+ *   }
+ *
+ *   async onModuleDestroy() {
+ *     await this.disconnect();
+ *   }
+ *
+ *   async onApplicationBootstrap() {
+ *     await this.runMigrations();
+ *   }
+ *
+ *   async onApplicationShutdown() {
+ *     await this.gracefulShutdown();
+ *   }
+ * }
+ * ```
+ */
 export interface ServiceWithLifecycle {
     onModuleInit?: () => Promise<void>;
     onModuleDestroy?: () => Promise<void>;
@@ -1296,6 +1986,24 @@ export interface ServiceWithLifecycle {
     onApplicationShutdown?: () => Promise<void>;
     [key: string]: unknown;
 }
+/**
+ * Test configuration for service lifecycle hooks.
+ * Defines service class and expected lifecycle behavior for testing.
+ *
+ * @example
+ * ```typescript
+ * const serviceTest: ServiceLifecycleTest = {
+ *   name: 'DatabaseService lifecycle',
+ *   Service: DatabaseService,
+ *   dependencies: [mockConfig, mockLogger],
+ *   expectedHooks: [
+ *     { name: 'onModuleInit', method: 'onModuleInit', phase: 'init', async: true },
+ *     { name: 'onModuleDestroy', method: 'onModuleDestroy', phase: 'destroy', async: true }
+ *   ],
+ *   cleanupExpected: true
+ * };
+ * ```
+ */
 export interface ServiceLifecycleTest {
     name: string;
     Service: new (...args: unknown[]) => ServiceWithLifecycle;
@@ -1303,6 +2011,19 @@ export interface ServiceLifecycleTest {
     expectedHooks: LifecycleHook[];
     cleanupExpected?: boolean;
 }
+/**
+ * Provider with lifecycle hooks.
+ * Contains constructor name and lifecycle methods.
+ *
+ * @example
+ * ```typescript
+ * const provider: ProviderWithLifecycle = {
+ *   constructor: { name: 'CacheProvider' },
+ *   onModuleInit: async () => { await cache.warm(); },
+ *   onModuleDestroy: async () => { await cache.clear(); }
+ * };
+ * ```
+ */
 export interface ProviderWithLifecycle {
     constructor: {
         name: string;
@@ -1311,6 +2032,21 @@ export interface ProviderWithLifecycle {
     onModuleDestroy?: () => Promise<void>;
     [key: string]: unknown;
 }
+/**
+ * Test configuration for module lifecycle.
+ * Defines expected provider initialization order.
+ *
+ * @example
+ * ```typescript
+ * const test: ModuleLifecycleTest = {
+ *   name: 'AppModule lifecycle',
+ *   Module: AppModule,
+ *   providers: [ // providers with lifecycle],
+ *   expectedInitOrder: ['DatabaseProvider', 'CacheProvider'],
+ *   expectedDestroyOrder: ['CacheProvider', 'DatabaseProvider']
+ * };
+ * ```
+ */
 export interface ModuleLifecycleTest {
     name: string;
     Module: new (...args: unknown[]) => unknown;
@@ -1318,6 +2054,21 @@ export interface ModuleLifecycleTest {
     expectedInitOrder: string[];
     expectedDestroyOrder: string[];
 }
+/**
+ * Test configuration for application lifecycle.
+ * Defines expected startup and shutdown sequences.
+ *
+ * @example
+ * ```typescript
+ * const test: ApplicationLifecycleTest = {
+ *   name: 'Application lifecycle',
+ *   app: applicationInstance,
+ *   modules: [CoreModule, AuthModule],
+ *   expectedStartupSequence: ['CoreModule', 'AuthModule'],
+ *   expectedShutdownSequence: ['AuthModule', 'CoreModule']
+ * };
+ * ```
+ */
 export interface ApplicationLifecycleTest {
     name: string;
     app: Record<string, unknown>;
@@ -1352,9 +2103,38 @@ export interface TestSuiteConfig<T> {
     teardownAfterEach?: () => void | Promise<void>;
     teardownAfterAll?: () => void | Promise<void>;
 }
+/**
+ * Environment configuration for testing.
+ * Maps environment variable names to values.
+ *
+ * @example
+ * ```typescript
+ * const config: EnvironmentConfig = {
+ *   NODE_ENV: 'test',
+ *   DATABASE_URL: 'postgres://localhost/test',
+ *   API_KEY: 'test-api-key'
+ * };
+ * ```
+ */
 export interface EnvironmentConfig {
     [key: string]: string | undefined;
 }
+/**
+ * Options for testing CSS animations.
+ * Configures animation properties and behavior.
+ *
+ * @example
+ * ```typescript
+ * const options: AnimationTestOptions = {
+ *   duration: 1000,
+ *   easing: 'ease-in-out',
+ *   delay: 200,
+ *   iterations: 2,
+ *   direction: 'alternate',
+ *   fillMode: 'forwards'
+ * };
+ * ```
+ */
 export interface AnimationTestOptions {
     duration?: number;
     easing?: string;
@@ -1363,12 +2143,41 @@ export interface AnimationTestOptions {
     direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
     fillMode?: 'none' | 'forwards' | 'backwards' | 'both';
 }
+/**
+ * Options for testing CSS transitions.
+ * Configures transition properties and timing.
+ *
+ * @example
+ * ```typescript
+ * const options: TransitionTestOptions = {
+ *   property: 'transform',
+ *   duration: 300,
+ *   timingFunction: 'cubic-bezier(0.4, 0, 0.2, 1)',
+ *   delay: 50
+ * };
+ * ```
+ */
 export interface TransitionTestOptions {
     property?: string;
     duration?: number;
     timingFunction?: string;
     delay?: number;
 }
+/**
+ * Keyframe test configuration.
+ * Defines styles at specific animation percentage.
+ *
+ * @example
+ * ```typescript
+ * const keyframe: KeyframeTest = {
+ *   percentage: 50,
+ *   styles: {
+ *     opacity: '0.5',
+ *     transform: 'scale(1.2)'
+ *   }
+ * };
+ * ```
+ */
 export interface KeyframeTest {
     percentage: number;
     styles: Record<string, string>;
@@ -1399,12 +2208,44 @@ export interface AnimationSequence {
         easing?: string;
     }>;
 }
+/**
+ * Test case for environment-specific behavior.
+ * Defines environment setup and expected behavior.
+ *
+ * @example
+ * ```typescript
+ * const testCase: EnvironmentTestCase = {
+ *   name: 'Production environment',
+ *   environment: { NODE_ENV: 'production' },
+ *   expectedBehavior: async () => {
+ *     expect(logger.level).toBe('error');
+ *   },
+ *   cleanup: async () => { process.env.NODE_ENV = 'test'; }
+ * };
+ * ```
+ */
 export interface EnvironmentTestCase {
     name: string;
     environment: EnvironmentConfig;
     expectedBehavior: () => void | Promise<void>;
     cleanup?: () => void | Promise<void>;
 }
+/**
+ * Configuration test scenario.
+ * Defines config values and expected results.
+ *
+ * @example
+ * ```typescript
+ * const scenario: ConfigTestScenario = {
+ *   name: 'Invalid database config',
+ *   config: { database: { host: '' } },
+ *   environment: { DB_HOST: '' },
+ *   expectedValues: {},
+ *   shouldThrow: true,
+ *   expectedError: /Database host is required/
+ * };
+ * ```
+ */
 export interface ConfigTestScenario {
     name: string;
     config: Record<string, unknown>;
@@ -1413,35 +2254,139 @@ export interface ConfigTestScenario {
     shouldThrow?: boolean;
     expectedError?: string | RegExp;
 }
+/**
+ * Spring animation configuration.
+ * Defines physical properties for spring animations.
+ *
+ * @example
+ * ```typescript
+ * const spring: SpringConfig = {
+ *   tension: 170,
+ *   friction: 26,
+ *   mass: 1
+ * };
+ * ```
+ */
 export interface SpringConfig {
     tension: number;
     friction: number;
     mass: number;
 }
+/**
+ * RequestAnimationFrame callback wrapper.
+ * Stores callback ID and function reference.
+ *
+ * @example
+ * ```typescript
+ * const rafCallback: RAFCallback = {
+ *   id: 1,
+ *   callback: (timestamp) => { // animation logic }
+ * };
+ * ```
+ */
 export interface RAFCallback {
     id: number;
     callback: FrameRequestCallback;
 }
+/**
+ * Loading state interface.
+ * Represents loading status in async operations.
+ *
+ * @example
+ * ```typescript
+ * const state: LoadingState = {
+ *   isLoading: true,
+ *   loading: true
+ * };
+ * ```
+ */
 export interface LoadingState {
     isLoading?: boolean;
     loading?: boolean;
 }
+/**
+ * Options for text waiting utilities.
+ * Configures timeout for text appearance.
+ *
+ * @example
+ * ```typescript
+ * const options: ForTextOptions = {
+ *   timeout: 3000 // Wait up to 3 seconds
+ * };
+ * ```
+ */
 export interface ForTextOptions {
     timeout?: number;
 }
+/**
+ * Test value with index wrapper.
+ * Associates test values with their position.
+ *
+ * @template T - Type of test value
+ *
+ * @example
+ * ```typescript
+ * const testValue: TestValueWithIndex<string> = {
+ *   value: 'test-data',
+ *   index: 2
+ * };
+ * ```
+ */
 export interface TestValueWithIndex<T> {
     value: T;
     index: number;
 }
+/**
+ * Record of a function call.
+ * Tracks method name, arguments, and timestamp.
+ *
+ * @example
+ * ```typescript
+ * const call: CallRecord = {
+ *   method: 'saveUser',
+ *   args: [{ id: 1, name: 'John' }],
+ *   timestamp: Date.now()
+ * };
+ * ```
+ */
 export interface CallRecord {
     method: string;
     args: unknown[];
     timestamp: number;
 }
+/**
+ * Module spy for tracking calls.
+ * Wraps module with call tracking.
+ *
+ * @template T - Type of module being spied on
+ *
+ * @example
+ * ```typescript
+ * const spy: ModuleSpy<UserService> = {
+ *   module: userService,
+ *   calls: [...tracked calls]
+ * };
+ * ```
+ */
 export interface ModuleSpy<T> {
     module: T;
     calls: CallRecord[];
 }
+/**
+ * Named test case for table-driven tests.
+ * Associates name with input and expected output.
+ *
+ * @template T - Type of test input
+ *
+ * @example
+ * ```typescript
+ * const testCase: NamedTestCase<number> = {
+ *   name: 'handles negative numbers',
+ *   input: -5,
+ *   expected: 5
+ * };
+ * ```
+ */
 export interface NamedTestCase<T> {
     name: string;
     input: T;
@@ -1610,6 +2555,19 @@ export interface MiddlewareTestScenarioWithRequest {
         status?: number;
     };
 }
+/**
+ * API route handler methods for Next.js.
+ * Maps HTTP methods to handler functions.
+ *
+ * @example
+ * ```typescript
+ * const handlers: ApiRouteHandlerMethods = {
+ *   GET: async (req, res) => res.json({ users: [] }),
+ *   POST: async (req, res) => res.status(201).json({ id: 1 }),
+ *   DELETE: async (req, res) => res.status(204).end()
+ * };
+ * ```
+ */
 export interface ApiRouteHandlerMethods {
     GET?: Function;
     POST?: Function;
@@ -1617,106 +2575,422 @@ export interface ApiRouteHandlerMethods {
     DELETE?: Function;
     PATCH?: Function;
 }
+/**
+ * Test scenario for route handlers.
+ * Defines request method and expected response.
+ *
+ * @example
+ * ```typescript
+ * const scenario: RouteHandlerTestScenario = {
+ *   method: 'POST',
+ *   request: [{ url: '/api/users', body: { name: 'John' } }],
+ *   expectedStatus: 201,
+ *   expectedBody: { id: 1, name: 'John' }
+ * };
+ * ```
+ */
 export interface RouteHandlerTestScenario {
     method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
     request: Parameters<CreateMockNextRequestFunction>;
     expectedStatus: number;
     expectedBody?: unknown;
 }
+/**
+ * Test scenario for image loader.
+ * Defines input parameters and expected URL.
+ *
+ * @example
+ * ```typescript
+ * const scenario: ImageLoaderTestScenario = {
+ *   input: { src: '/img.jpg', width: 800, quality: 75 },
+ *   expectedUrl: '/_next/image?url=%2Fimg.jpg&w=800&q=75'
+ * };
+ * ```
+ */
 export interface ImageLoaderTestScenario {
     input: ImageLoaderInput;
     expectedUrl: string | RegExp;
 }
+/**
+ * Parameterized test runner.
+ * Provides method to run tests with different inputs.
+ *
+ * @template T - Type of test input
+ *
+ * @example
+ * ```typescript
+ * const paramTest: ParameterizedTest<number> = {
+ *   test: (name, fn) => {
+ *     test(name, () => fn(5, 10));
+ *   }
+ * };
+ * ```
+ */
 export interface ParameterizedTest<T> {
     test: (name: string, fn: (input: T, expected: unknown) => void | Promise<void>) => void;
 }
+/**
+ * Test suite for service testing.
+ * Provides methods for testing service behavior.
+ *
+ * @template T - Type of service being tested
+ *
+ * @example
+ * ```typescript
+ * const suite: ServiceTestSuite<UserService> = {
+ *   testMethods: () => { // test service methods },
+ *   testErrorHandling: (scenarios) => { // test error cases }
+ * };
+ * ```
+ */
 export interface ServiceTestSuite<T> {
     testMethods: () => void;
     testErrorHandling: (errorScenarios: Array<ErrorScenario<T>>) => void;
 }
+/**
+ * Test suite for NestJS applications.
+ * Provides methods for testing providers and injection.
+ *
+ * @example
+ * ```typescript
+ * const suite: NestJSTestSuiteReturn = {
+ *   testProviderRegistration: (tokens) => { // test providers },
+ *   testProviderInjection: (tests) => { // test DI }
+ * };
+ * ```
+ */
 export interface NestJSTestSuiteReturn {
     testProviderRegistration: (providerTokens: unknown[]) => void;
     testProviderInjection: (injectionTests: Array<ProviderInjectionTest>) => void;
 }
+/**
+ * Test suite for Next.js pages.
+ * Provides methods for testing SSG, SSR, and rendering.
+ *
+ * @example
+ * ```typescript
+ * const suite: NextJSTestSuite = {
+ *   testStaticGeneration: (getStaticProps, getStaticPaths) => { // test SSG },
+ *   testServerSideRendering: (getServerSideProps) => { // test SSR },
+ *   testPageRendering: (scenarios) => { // test rendering }
+ * };
+ * ```
+ */
 export interface NextJSTestSuite {
     testStaticGeneration: (getStaticProps?: Function, getStaticPaths?: Function) => void;
     testServerSideRendering: (getServerSideProps?: Function) => void;
     testPageRendering: (scenarios: Array<PropsTestScenario>) => void;
 }
+/**
+ * Factory for creating test suites.
+ * Provides methods for various test patterns.
+ *
+ * @template T - Type of object being tested
+ *
+ * @example
+ * ```typescript
+ * const factory: TestSuiteFactory<Calculator> = {
+ *   runScenarios: (scenarios) => { // run test scenarios },
+ *   testMethod: (method, cases) => { // test specific method },
+ *   testLifecycle: (hooks) => { // test lifecycle },
+ *   testErrorHandling: (errors) => { // test errors }
+ * };
+ * ```
+ */
 export interface TestSuiteFactory<T extends UnknownRecord> {
     runScenarios: (scenarios: TestScenario<T, unknown, unknown>[]) => void;
     testMethod: (methodName: keyof T, testCases: Array<TestCaseWithSetup<T>>) => void;
     testLifecycle: (lifecycleHooks: Array<LifecycleHookTestConfig<T>>) => void;
     testErrorHandling: (errorScenarios: Array<ErrorHandlingScenario<T>>) => void;
 }
+/**
+ * Conditional behavior for mocks.
+ * Returns different results based on predicate.
+ *
+ * @template T - Type of mock return value
+ *
+ * @example
+ * ```typescript
+ * const behavior: ConditionalMockBehavior<string> = {
+ *   predicate: (id) => id === 'admin',
+ *   result: 'admin-response'
+ * };
+ * ```
+ */
 export interface ConditionalMockBehavior<T> {
     predicate: (...args: unknown[]) => boolean;
     result: T | (() => T);
 }
+/**
+ * Result from mocking a module.
+ * Provides unmock function for cleanup.
+ *
+ * @example
+ * ```typescript
+ * const mockResult: MockModuleResult = mockModule('fs');
+ * // Use mocked module
+ * mockResult.unmock(); // Restore original
+ * ```
+ */
 export interface MockModuleResult {
     unmock: () => void;
 }
+/**
+ * Result from mocking multiple modules.
+ * Provides function to unmock all.
+ *
+ * @example
+ * ```typescript
+ * const result: MockManyResult = mockMany(['fs', 'path']);
+ * // Use mocked modules
+ * result.unmockAll(); // Restore all
+ * ```
+ */
 export interface MockManyResult {
     unmockAll: () => void;
 }
+/**
+ * Result from route matching.
+ * Contains extracted params and match status.
+ *
+ * @example
+ * ```typescript
+ * const result: RouteMatchResult = {
+ *   params: { id: '123', slug: 'post-title' },
+ *   isMatch: true
+ * };
+ * ```
+ */
 export interface RouteMatchResult {
     params: Record<string, string | string[]>;
     isMatch: boolean;
 }
+/**
+ * Performance entry with metrics.
+ * Contains name and performance data.
+ *
+ * @example
+ * ```typescript
+ * const entry: PerformanceEntryResult = {
+ *   name: 'api-call',
+ *   metrics: { mean: 50, median: 45, p95: 100 }
+ * };
+ * ```
+ */
 export interface PerformanceEntryResult {
     name: string;
     metrics: PerformanceMetrics;
 }
+/**
+ * Result from memory measurement.
+ * Contains memory data and function result.
+ *
+ * @template T - Type of function result
+ *
+ * @example
+ * ```typescript
+ * const result: MemoryMeasurementResult<string[]> = {
+ *   measurement: { before: 1000, after: 2000, delta: 1000, peak: 2500 },
+ *   result: ['item1', 'item2']
+ * };
+ * ```
+ */
 export interface MemoryMeasurementResult<T> {
     measurement: MemoryMeasurement;
     result: T;
 }
+/**
+ * Global object with garbage collection.
+ * Provides manual GC trigger for testing.
+ *
+ * @example
+ * ```typescript
+ * const global: GlobalWithGC = globalThis as GlobalWithGC;
+ * if (global.gc) {
+ *   global.gc(); // Force garbage collection
+ * }
+ * ```
+ */
 export interface GlobalWithGC {
     gc?: () => void;
 }
+/**
+ * Result from memory leak testing.
+ * Contains memory usage before and after.
+ *
+ * @example
+ * ```typescript
+ * const result: MemoryLeakTestResult = {
+ *   initialMemory: 50000000,
+ *   finalMemory: 55000000,
+ *   memoryIncrease: 5000000,
+ *   iterations: 1000
+ * };
+ * ```
+ */
 export interface MemoryLeakTestResult {
     initialMemory: number;
     finalMemory: number;
     memoryIncrease: number;
     iterations: number;
 }
+/**
+ * Property variation for component testing.
+ * Defines props and expected behavior.
+ *
+ * @example
+ * ```typescript
+ * const variation: PropVariation = {
+ *   name: 'with loading state',
+ *   props: { isLoading: true },
+ *   expectation: () => expect(screen.getByTestId('spinner')).toBeVisible()
+ * };
+ * ```
+ */
 export interface PropVariation {
     name: string;
     props: Record<string, unknown>;
     expectation: () => void;
 }
+/**
+ * Valid input test case.
+ * Defines input that should succeed.
+ *
+ * @template T - Type of expected result
+ *
+ * @example
+ * ```typescript
+ * const testCase: ValidTestCase<User> = {
+ *   name: 'valid email format',
+ *   input: 'user@example.com',
+ *   expected: { email: 'user@example.com', valid: true }
+ * };
+ * ```
+ */
 export interface ValidTestCase<T> {
     name: string;
     input: unknown;
     expected?: T;
 }
+/**
+ * Invalid input test case.
+ * Defines input that should fail with error.
+ *
+ * @example
+ * ```typescript
+ * const testCase: InvalidTestCase = {
+ *   name: 'invalid email format',
+ *   input: 'not-an-email',
+ *   expectedError: /Invalid email format/
+ * };
+ * ```
+ */
 export interface InvalidTestCase {
     name: string;
     input: unknown;
     expectedError: string | RegExp;
 }
+/**
+ * Created resource for cleanup tracking.
+ * Stores resource reference and name.
+ *
+ * @example
+ * ```typescript
+ * const resource: CreatedResource = {
+ *   name: 'test-database',
+ *   resource: dbConnection
+ * };
+ * ```
+ */
 export interface CreatedResource {
     name: string;
     resource: unknown;
 }
+/**
+ * Record of lifecycle hook execution.
+ * Tracks phase, method, and timestamp.
+ *
+ * @example
+ * ```typescript
+ * const record: LifecycleHookRecord = {
+ *   phase: 'mount',
+ *   method: 'componentDidMount',
+ *   timestamp: Date.now()
+ * };
+ * ```
+ */
 export interface LifecycleHookRecord {
     phase: string;
     method: string;
     timestamp: number;
 }
+/**
+ * Test case for path matching.
+ * Defines path and expected match result.
+ *
+ * @example
+ * ```typescript
+ * const test: PathMatchTest = {
+ *   path: '/users/123',
+ *   shouldMatch: true
+ * };
+ * ```
+ */
 export interface PathMatchTest {
     path: string;
     shouldMatch: boolean;
 }
+/**
+ * Error scenario for service testing.
+ * Defines setup and expected error.
+ *
+ * @template T - Type of service being tested
+ *
+ * @example
+ * ```typescript
+ * const scenario: ErrorScenario<UserService> = {
+ *   method: 'createUser',
+ *   setup: (service) => vi.spyOn(db, 'save').mockRejectedValue(new Error()),
+ *   expectedError: 'Database error'
+ * };
+ * ```
+ */
 export interface ErrorScenario<T> {
     method: string;
     setup: (service: T) => void;
     expectedError: unknown;
 }
+/**
+ * Test scenario for component props.
+ * Defines props and expected content.
+ *
+ * @example
+ * ```typescript
+ * const scenario: PropsTestScenario = {
+ *   props: { title: 'Hello', isActive: true },
+ *   expectedContent: 'Hello - Active'
+ * };
+ * ```
+ */
 export interface PropsTestScenario {
     props: Record<string, unknown>;
     expectedContent?: string;
 }
+/**
+ * Responsive breakpoint test configuration.
+ * Defines viewport size and expectations.
+ *
+ * @example
+ * ```typescript
+ * const breakpoint: ResponsiveBreakpoint = {
+ *   width: 768,
+ *   height: 1024,
+ *   expectations: () => {
+ *     expect(screen.getByTestId('mobile-menu')).toBeVisible();
+ *   }
+ * };
+ * ```
+ */
 export interface ResponsiveBreakpoint {
     width: number;
     height: number;
@@ -1725,6 +2999,18 @@ export interface ResponsiveBreakpoint {
 export type TestCombination<T extends Record<string, unknown[]>> = {
     [K in keyof T]: T[K][number];
 };
+/**
+ * Test dependency configuration.
+ * Maps token to test value.
+ *
+ * @example
+ * ```typescript
+ * const dependency: TestDependency = {
+ *   token: DatabaseService,
+ *   value: mockDatabaseService
+ * };
+ * ```
+ */
 export interface TestDependency {
     token: unknown;
     value: unknown;
@@ -1763,12 +3049,43 @@ export interface TableTestCase<TInput, TExpected> {
     only?: boolean;
     error?: boolean;
 }
+/**
+ * Edge case test definition.
+ * Tests boundary conditions and edge cases.
+ *
+ * @template T - Type of input
+ * @template R - Type of expected result
+ *
+ * @example
+ * ```typescript
+ * const test: EdgeCaseTest<number, string> = {
+ *   name: 'handles MAX_SAFE_INTEGER',
+ *   input: Number.MAX_SAFE_INTEGER,
+ *   expected: '9007199254740991'
+ * };
+ * ```
+ */
 export interface EdgeCaseTest<T, R> {
     name: string;
     input: T;
     expected?: R;
     shouldThrow?: string | RegExp | Error;
 }
+/**
+ * Metrics for animation performance.
+ * Contains frame time statistics.
+ *
+ * @example
+ * ```typescript
+ * const metrics: AnimationPerformanceMetrics = {
+ *   avgFrameTime: 16.67,
+ *   avgFPS: 60,
+ *   maxFrameTime: 33,
+ *   minFrameTime: 8,
+ *   frameTimes: [16, 17, 16, 33, 8]
+ * };
+ * ```
+ */
 export interface AnimationPerformanceMetrics {
     avgFrameTime: number;
     avgFPS: number;
@@ -1776,6 +3093,19 @@ export interface AnimationPerformanceMetrics {
     minFrameTime: number;
     frameTimes: number[];
 }
+/**
+ * Options for animation performance testing.
+ * Configures iterations and thresholds.
+ *
+ * @example
+ * ```typescript
+ * const options: AnimationPerformanceOptions = {
+ *   iterations: 100,
+ *   maxFrameTime: 33, // 30 FPS minimum
+ *   minFPS: 30
+ * };
+ * ```
+ */
 export interface AnimationPerformanceOptions {
     iterations?: number;
     maxFrameTime?: number;
@@ -1796,6 +3126,23 @@ export type StaticPropsResult<T> = {
 } | {
     notFound: true;
 };
+/**
+ * Test result for getServerSideProps.
+ * Contains result and assertion helpers.
+ *
+ * @template T - Type of props
+ *
+ * @example
+ * ```typescript
+ * const result: ServerSidePropsTestResult<PageProps> = {
+ *   result: { props: { user: { id: 1 } } },
+ *   context: mockContext,
+ *   expectProps: (props) => expect(props).toMatchObject({ user: { id: 1 } }),
+ *   expectRedirect: (dest) => expect(result.redirect).toBe(dest),
+ *   expectNotFound: () => expect(result.notFound).toBe(true)
+ * };
+ * ```
+ */
 export interface ServerSidePropsTestResult<T> {
     result: ServerSidePropsResult<T>;
     context: MockGetServerSidePropsContext;
@@ -1803,6 +3150,23 @@ export interface ServerSidePropsTestResult<T> {
     expectRedirect: (destination: string, permanent?: boolean) => void;
     expectNotFound: () => void;
 }
+/**
+ * Test result for getStaticProps.
+ * Contains result and assertion helpers.
+ *
+ * @template T - Type of props
+ *
+ * @example
+ * ```typescript
+ * const result: StaticPropsTestResult<PageProps> = {
+ *   result: { props: { posts: [] }, revalidate: 60 },
+ *   context: mockContext,
+ *   expectProps: (props) => expect(props.posts).toHaveLength(0),
+ *   expectRevalidate: (seconds) => expect(result.revalidate).toBe(seconds),
+ *   expectNotFound: () => expect(result.notFound).toBe(true)
+ * };
+ * ```
+ */
 export interface StaticPropsTestResult<T> {
     result: StaticPropsResult<T>;
     context: MockGetStaticPropsContext;
@@ -1811,27 +3175,103 @@ export interface StaticPropsTestResult<T> {
     expectNotFound: () => void;
     expectRevalidate: (seconds: number) => void;
 }
+/**
+ * Custom query methods for testing.
+ * Provides additional DOM query functions.
+ *
+ * @example
+ * ```typescript
+ * const queries: CreateCustomQueriesReturn = {
+ *   getByClassName: (name) => container.querySelector(`.${name}`),
+ *   getAllByClassName: (name) => Array.from(container.querySelectorAll(`.${name}`)),
+ *   getByAttribute: (attr, value) => container.querySelector(`[${attr}="${value}"]`)
+ * };
+ * ```
+ */
 export interface CreateCustomQueriesReturn {
     getByClassName: (className: string) => HTMLElement;
     getAllByClassName: (className: string) => HTMLElement[];
     getByAttribute: (attribute: string, value?: string) => HTMLElement;
 }
+/**
+ * Boundary value test case.
+ * Tests edge values and boundaries.
+ *
+ * @template T - Type of boundary value
+ *
+ * @example
+ * ```typescript
+ * const test: BoundaryValueTest<number> = {
+ *   value: 0,
+ *   description: 'minimum value',
+ *   expected: 'zero'
+ * };
+ * ```
+ */
 export interface BoundaryValueTest<T> {
     value: T;
     description: string;
     expected: unknown;
 }
+/**
+ * Equivalence class test case.
+ * Tests multiple inputs with same expected result.
+ *
+ * @template T - Type of input samples
+ * @template R - Type of expected result
+ *
+ * @example
+ * ```typescript
+ * const test: EquivalenceClassTest<string, boolean> = {
+ *   name: 'valid emails',
+ *   samples: ['user@example.com', 'test@domain.org'],
+ *   expected: true
+ * };
+ * ```
+ */
 export interface EquivalenceClassTest<T, R> {
     name: string;
     samples: T[];
     expected: R;
 }
+/**
+ * State transition test case.
+ * Defines state change from action.
+ *
+ * @template TState - Type of state
+ * @template TAction - Type of action
+ *
+ * @example
+ * ```typescript
+ * const test: StateTransitionTest<LoadingState, Action> = {
+ *   from: { status: 'idle' },
+ *   action: { type: 'FETCH_START' },
+ *   to: { status: 'loading' },
+ *   description: 'starts loading on fetch'
+ * };
+ * ```
+ */
 export interface StateTransitionTest<TState, TAction> {
     from: TState;
     action: TAction;
     to: TState;
     description?: string;
 }
+/**
+ * Snapshot test case configuration.
+ * Defines input for snapshot testing.
+ *
+ * @template T - Type of input
+ *
+ * @example
+ * ```typescript
+ * const test: SnapshotTestCase<ComponentProps> = {
+ *   name: 'default state',
+ *   input: { title: 'Test', isActive: false },
+ *   transform: (input) => renderComponent(input)
+ * };
+ * ```
+ */
 export interface SnapshotTestCase<T> {
     name: string;
     input: T;
@@ -2035,9 +3475,38 @@ export interface ServerComponentTestScenario {
     params?: Record<string, string>;
     expectedContent?: string | RegExp;
 }
+/**
+ * Configuration for middleware path matching.
+ * Defines which paths the middleware applies to.
+ *
+ * @example
+ * ```typescript
+ * const config: MiddlewareMatcherConfig = {
+ *   matcher: ['/api/:path*', '/admin/:path*']
+ * };
+ * ```
+ */
 export interface MiddlewareMatcherConfig {
     matcher: string | string[];
 }
+/**
+ * Result from mocking Next.js navigation.
+ * Contains navigation methods and restore function.
+ *
+ * @example
+ * ```typescript
+ * const mockNav: MockNextNavigationResult = {
+ *   navigation: {
+ *     push: vi.fn(),
+ *     replace: vi.fn(),
+ *     refresh: vi.fn(),
+ *     back: vi.fn(),
+ *     forward: vi.fn()
+ *   },
+ *   restore: () => { // restore original }
+ * };
+ * ```
+ */
 export interface MockNextNavigationResult {
     navigation: {
         push: ReturnType<typeof Vitest.vi.fn>;
@@ -2048,35 +3517,126 @@ export interface MockNextNavigationResult {
     };
     restore: () => void;
 }
+/**
+ * Options for creating test harness.
+ * Configures instance creation and dependencies.
+ *
+ * @template TOptions - Type of options for creation
+ *
+ * @example
+ * ```typescript
+ * const options: TestHarnessOptions<ServiceOptions> = {
+ *   create: (deps, opts) => new Service(deps, opts),
+ *   dependencies: [{ token: 'DB', value: mockDb }]
+ * };
+ * ```
+ */
 export interface TestHarnessOptions<TOptions> {
     create: (deps: Map<unknown, unknown>, opts: TOptions) => unknown;
     dependencies?: Array<TestDependency>;
 }
+/**
+ * Result from test harness creation.
+ * Contains instance and helper methods.
+ *
+ * @template T - Type of instance created
+ *
+ * @example
+ * ```typescript
+ * const harness: TestHarnessResult<UserService> = {
+ *   instance: userService,
+ *   dependencies: new Map(),
+ *   logger: mockLogger,
+ *   getDependency: (token) => dependencies.get(token)
+ * };
+ * ```
+ */
 export interface TestHarnessResult<T> {
     instance: T;
     dependencies: Map<unknown, unknown>;
     logger?: unknown;
     getDependency: <U>(token: unknown) => U;
 }
+/**
+ * Options for mocking console methods.
+ * Controls which console methods to suppress.
+ *
+ * @example
+ * ```typescript
+ * const options: ConsoleMockOptions = {
+ *   suppressAll: false,
+ *   suppress: ['log', 'debug']
+ * };
+ * ```
+ */
 export interface ConsoleMockOptions {
     suppressAll?: boolean;
     suppress?: Array<'log' | 'error' | 'warn' | 'info' | 'debug'>;
 }
 export type ConsoleMethod = 'log' | 'error' | 'warn' | 'info' | 'debug';
+/**
+ * Result from hook error handling.
+ * Contains error information if present.
+ *
+ * @example
+ * ```typescript
+ * const result: HookErrorResult = {
+ *   error: { message: 'Hook failed to initialize' }
+ * };
+ * ```
+ */
 export interface HookErrorResult {
     error?: {
         message: string;
     };
 }
+/**
+ * Component with loading state property.
+ * Used for testing loading behavior.
+ *
+ * @example
+ * ```typescript
+ * const component: ComponentWithLoading = {
+ *   isLoading: true,
+ *   data: null,
+ *   error: null
+ * };
+ * ```
+ */
 export interface ComponentWithLoading {
     isLoading?: boolean;
     [key: string]: unknown;
 }
+/**
+ * Test for conditional rendering logic.
+ * Defines what should and shouldn't render.
+ *
+ * @example
+ * ```typescript
+ * const test: ConditionalRenderingTest = {
+ *   props: { isLoggedIn: true, isPremium: false },
+ *   shouldRender: ['user-menu', 'logout-button'],
+ *   shouldNotRender: ['login-form', 'premium-features']
+ * };
+ * ```
+ */
 export interface ConditionalRenderingTest {
     props: Record<string, unknown>;
     shouldRender: string[];
     shouldNotRender: string[];
 }
+/**
+ * Configuration for React context provider.
+ * Defines provider component and props.
+ *
+ * @example
+ * ```typescript
+ * const config: ProviderConfig = {
+ *   Provider: ThemeProvider,
+ *   props: { theme: 'dark', primaryColor: '#007bff' }
+ * };
+ * ```
+ */
 export interface ProviderConfig {
     Provider: React.ComponentType<{
         children: React.ReactNode;
@@ -2084,27 +3644,93 @@ export interface ProviderConfig {
     }>;
     props?: Record<string, unknown>;
 }
+/**
+ * Test case for user interactions.
+ * Defines action and expected result.
+ *
+ * @example
+ * ```typescript
+ * const test: UserInteractionTest = {
+ *   name: 'submits form on button click',
+ *   action: async (user) => await user.click(submitButton),
+ *   expectation: () => expect(onSubmit).toHaveBeenCalled()
+ * };
+ * ```
+ */
 export interface UserInteractionTest {
     name: string;
     action: (user: unknown) => Promise<void>;
     expectation: () => void;
 }
+/**
+ * Test for error boundary behavior.
+ * Validates error handling and recovery.
+ *
+ * @example
+ * ```typescript
+ * const test: ErrorBoundaryTest = {
+ *   error: new Error('Component crashed'),
+ *   expectedMessage: 'Something went wrong',
+ *   shouldHaveReset: true
+ * };
+ * ```
+ */
 export interface ErrorBoundaryTest {
     error: Error;
     expectedMessage?: string;
     shouldHaveReset?: boolean;
 }
+/**
+ * Result from component test suite.
+ * Provides methods for various test types.
+ *
+ * @example
+ * ```typescript
+ * const suite: ComponentTestSuiteResult = {
+ *   testRendering: () => { rendering tests  },
+ *   testUserInteractions: (interactions) => { interaction tests },
+ *   testProps: (variations) => { prop tests }
+ * };
+ * ```
+ */
 export interface ComponentTestSuiteResult {
     testRendering: () => void;
     testUserInteractions: (interactions: Array<UserInteractionTest>) => void;
     testProps: (propVariations: Array<PropVariation>) => void;
 }
+/**
+ * Test for resource cleanup behavior.
+ * Validates proper resource disposal.
+ *
+ * @example
+ * ```typescript
+ * const test: ResourceCleanupTest = {
+ *   name: 'database connection cleanup',
+ *   create: () => db.connect(),
+ *   cleanup: async (conn) => await conn.close(),
+ *   isCleanedUp: (conn) => conn.isClosed()
+ * };
+ * ```
+ */
 export interface ResourceCleanupTest {
     name: string;
     create: () => unknown;
     cleanup: (resource: unknown) => Promise<void> | void;
     isCleanedUp: (resource: unknown) => boolean;
 }
+/**
+ * Container for dependency injection.
+ * Manages service registration and resolution.
+ *
+ * @example
+ * ```typescript
+ * const container: DependencyInjectionContainer = {
+ *   register: (token, factory, options) => { // register service },
+ *   resolve: (token) => { // resolve service },
+ *   dispose: async () => { // cleanup all services }
+ * };
+ * ```
+ */
 export interface DependencyInjectionContainer {
     register: (token: unknown, factory: () => unknown, options: {
         lifecycle: 'singleton' | 'transient' | 'scoped';
@@ -2113,6 +3739,21 @@ export interface DependencyInjectionContainer {
     resolve: (token: unknown) => unknown;
     dispose: () => Promise<void>;
 }
+/**
+ * Configuration for dependency injection.
+ * Defines service registration details.
+ *
+ * @example
+ * ```typescript
+ * const config: DependencyInjectionConfig = {
+ *   token: UserService,
+ *   factory: () => new UserService(db),
+ *   dependencies: [DatabaseService],
+ *   lifecycle: 'singleton',
+ *   cleanup: (instance) => instance.dispose()
+ * };
+ * ```
+ */
 export interface DependencyInjectionConfig {
     token: unknown;
     factory: () => unknown;
@@ -2120,6 +3761,21 @@ export interface DependencyInjectionConfig {
     lifecycle: 'singleton' | 'transient' | 'scoped';
     cleanup?: (instance: unknown) => void;
 }
+/**
+ * Async lifecycle hook configuration.
+ * Defines async hook behavior and timing.
+ *
+ * @example
+ * ```typescript
+ * const hook: AsyncLifecycleHook = {
+ *   name: 'onModuleInit',
+ *   method: 'initialize',
+ *   timeout: 5000,
+ *   shouldReject: false,
+ *   expectedError: undefined
+ * };
+ * ```
+ */
 export interface AsyncLifecycleHook {
     name: string;
     method: string;
@@ -2127,6 +3783,25 @@ export interface AsyncLifecycleHook {
     shouldReject?: boolean;
     expectedError?: string | RegExp;
 }
+/**
+ * Result from lifecycle test harness.
+ * Provides lifecycle tracking methods.
+ *
+ * @template T - Type of instance being tested
+ *
+ * @example
+ * ```typescript
+ * const harness: LifecycleTestHarnessResult<Service> = {
+ *   instance: service,
+ *   getHooks: () => recordedHooks,
+ *   clearHooks: () => { recordedHooks = []; },
+ *   getHooksByPhase: (phase) => recordedHooks.filter(h => h.phase === phase),
+ *   getLastHook: () => recordedHooks[recordedHooks.length - 1],
+ *   expectHookCalled: (method) => expect(recordedHooks).toContainEqual({ method }),
+ *   expectHookOrder: (order) => expect(recordedHooks.map(h => h.method)).toEqual(order)
+ * };
+ * ```
+ */
 export interface LifecycleTestHarnessResult<T> {
     instance: T;
     getHooks: () => Array<LifecycleHookRecord>;
@@ -2136,14 +3811,52 @@ export interface LifecycleTestHarnessResult<T> {
     expectHookCalled: (method: string) => void;
     expectHookOrder: (expectedOrder: string[]) => void;
 }
+/**
+ * Options for graceful shutdown testing.
+ * Configures shutdown behavior and expectations.
+ *
+ * @example
+ * ```typescript
+ * const options: GracefulShutdownOptions = {
+ *   shutdownTimeout: 10000,
+ *   signals: ['SIGTERM', 'SIGINT'],
+ *   expectedCleanupActions: ['close-db', 'stop-server', 'flush-cache']
+ * };
+ * ```
+ */
 export interface GracefulShutdownOptions {
     shutdownTimeout?: number;
     signals?: globalThis.NodeJS.Signals[];
     expectedCleanupActions?: string[];
 }
+/**
+ * Cleanup function for React hooks.
+ * Provides unmount method.
+ *
+ * @example
+ * ```typescript
+ * const cleanup: HookCleanupFunction = {
+ *   unmount: () => { // cleanup hook }
+ * };
+ * ```
+ */
 export interface HookCleanupFunction {
     unmount: () => void;
 }
+/**
+ * Mock IntersectionObserver entry.
+ * Simulates intersection observer behavior.
+ *
+ * @example
+ * ```typescript
+ * const entry: MockIntersectionObserverEntry = {
+ *   target: element,
+ *   isIntersecting: true,
+ *   intersectionRatio: 0.75,
+ *   boundingClientRect: element.getBoundingClientRect()
+ * };
+ * ```
+ */
 export interface MockIntersectionObserverEntry {
     target: Element;
     isIntersecting: boolean;
@@ -2171,24 +3884,85 @@ export type PropertyTestFunction<T> = (value: T) => boolean | Promise<boolean>;
 export type StateTransitionApplyFunction<TState, TAction> = (state: TState, action: TAction) => TState;
 export type CombinationTestFunction<T extends Record<string, unknown[]>> = (combination: TestCombination<T>) => void | Promise<void>;
 export type UnknownFunction = (...args: unknown[]) => unknown;
+/**
+ * Configuration for spy target.
+ * Defines object, method, and implementation.
+ *
+ * @example
+ * ```typescript
+ * const config: SpyTargetConfig = {
+ *   obj: userService,
+ *   method: 'findUser',
+ *   implementation: () => ({ id: 1, name: 'Test' })
+ * };
+ * ```
+ */
 export interface SpyTargetConfig {
     obj: UnknownRecord;
     method: string;
     implementation?: UnknownFunction;
 }
 export type ModuleMockFactories = Record<string, () => UnknownRecord>;
+/**
+ * Test case with setup function.
+ * Allows pre-test configuration.
+ *
+ * @template T - Type of instance being tested
+ *
+ * @example
+ * ```typescript
+ * const testCase: TestCaseWithSetup<Calculator> = {
+ *   name: 'adds with precision',
+ *   args: [0.1, 0.2],
+ *   expected: 0.3,
+ *   setup: (calc) => calc.setPrecision(10)
+ * };
+ * ```
+ */
 export interface TestCaseWithSetup<T> {
     name: string;
     args: unknown[];
     expected: unknown;
     setup?: (instance: T) => void;
 }
+/**
+ * Configuration for lifecycle hook testing.
+ * Validates hook execution.
+ *
+ * @template T - Type of instance with lifecycle hooks
+ *
+ * @example
+ * ```typescript
+ * const config: LifecycleHookTestConfig<Component> = {
+ *   name: 'componentDidMount',
+ *   hook: 'componentDidMount',
+ *   expectedCalls: 1,
+ *   expectError: false
+ * };
+ * ```
+ */
 export interface LifecycleHookTestConfig<T> {
     name: string;
     hook: keyof T;
     expectedCalls?: number;
     expectError?: boolean;
 }
+/**
+ * Scenario for error handling tests.
+ * Defines method, arguments, and expected error.
+ *
+ * @template T - Type of instance being tested
+ *
+ * @example
+ * ```typescript
+ * const scenario: ErrorHandlingScenario<UserService> = {
+ *   method: 'createUser',
+ *   args: [{ email: 'invalid' }],
+ *   expectedError: /Invalid email format/,
+ *   setup: (service) => service.enableValidation()
+ * };
+ * ```
+ */
 export interface ErrorHandlingScenario<T> {
     method: keyof T;
     args: unknown[];
@@ -2202,6 +3976,21 @@ export type DataHandler<T> = (data: T) => void;
 export type ValueGetter<T> = () => T;
 export type GenericArgsFunction<T> = (...args: unknown[]) => T;
 export type AsyncFunction<T> = () => Promise<T>;
+/**
+ * Original console methods storage.
+ * Preserves original console functions.
+ *
+ * @example
+ * ```typescript
+ * const original: OriginalConsole = {
+ *   log: console.log,
+ *   error: console.error,
+ *   warn: console.warn,
+ *   info: console.info,
+ *   debug: console.debug
+ * };
+ * ```
+ */
 export interface OriginalConsole {
     log: typeof globalThis.console.log;
     error: typeof globalThis.console.error;
@@ -2209,6 +3998,21 @@ export interface OriginalConsole {
     info: typeof globalThis.console.info;
     debug: typeof globalThis.console.debug;
 }
+/**
+ * Information about DOM element.
+ * Contains element metadata and attributes.
+ *
+ * @example
+ * ```typescript
+ * const info: ElementInfo = {
+ *   tagName: 'button',
+ *   id: 'submit-btn',
+ *   className: 'btn btn-primary',
+ *   textContent: 'Submit',
+ *   attributes: { 'data-testid': 'submit' }
+ * };
+ * ```
+ */
 export interface ElementInfo {
     tagName: string;
     id: string;
@@ -2216,15 +4020,63 @@ export interface ElementInfo {
     textContent: string | null;
     attributes: Record<string, string>;
 }
+/**
+ * Debounced function with control methods.
+ * Delays execution until after wait period.
+ *
+ * @template T - Type of original function
+ *
+ * @example
+ * ```typescript
+ * const debounced: DebouncedFunction<(value: string) => void> = debounce(
+ *   (value) => console.log(value),
+ *   300
+ * );
+ * debounced('test'); // Waits 300ms
+ * debounced.cancel(); // Cancel pending
+ * debounced.flush(); // Execute immediately
+ * ```
+ */
 export interface DebouncedFunction<T extends (...args: unknown[]) => unknown> extends Function {
     (...args: Parameters<T>): void;
     cancel: () => void;
     flush: () => void;
 }
+/**
+ * Throttled function with control methods.
+ * Limits execution frequency.
+ *
+ * @template T - Type of original function
+ *
+ * @example
+ * ```typescript
+ * const throttled: ThrottledFunction<() => void> = throttle(
+ *   () => console.log('scroll'),
+ *   100
+ * );
+ * window.addEventListener('scroll', throttled);
+ * throttled.cancel(); // Cancel pending
+ * ```
+ */
 export interface ThrottledFunction<T extends (...args: unknown[]) => unknown> extends Function {
     (...args: Parameters<T>): void;
     cancel: () => void;
 }
+/**
+ * Stopwatch for timing operations.
+ * Tracks elapsed time and lap times.
+ *
+ * @example
+ * ```typescript
+ * const stopwatch: Stopwatch = {
+ *   start: () => { startTime = Date.now(); },
+ *   lap: () => { // record lap return lapTime; },
+ *   stop: () => { // stop timing return elapsed; },
+ *   getLaps: () => [...laps],
+ *   reset: () => { // reset all }
+ * };
+ * ```
+ */
 export interface Stopwatch {
     start(): void;
     lap(): number;
@@ -2232,6 +4084,21 @@ export interface Stopwatch {
     getLaps(): number[];
     reset(): void;
 }
+/**
+ * Return value from controller test harness.
+ * Provides controller instance and dependencies.
+ *
+ * @template T - Type of controller
+ *
+ * @example
+ * ```typescript
+ * const harness: ControllerTestHarnessReturn<UserController> = {
+ *   controller: userController,
+ *   moduleRef: { get: (token) => mockService },
+ *   logger: mockLogger
+ * };
+ * ```
+ */
 export interface ControllerTestHarnessReturn<T> {
     controller: T;
     moduleRef: {
@@ -2239,6 +4106,24 @@ export interface ControllerTestHarnessReturn<T> {
     };
     logger?: unknown;
 }
+/**
+ * Return value from service test harness.
+ * Provides service instance and test utilities.
+ *
+ * @template T - Type of service
+ *
+ * @example
+ * ```typescript
+ * const harness: ServiceTestHarnessReturn<UserService> = {
+ *   service: userService,
+ *   dependencies: new Map([[DatabaseService, mockDb]]),
+ *   logger: mockLogger,
+ *   resetMocks: () => { // reset all mocks },
+ *   expectCalled: (method, times) => expect(service[method]).toHaveBeenCalledTimes(times),
+ *   expectCalledWith: (method, ...args) => expect(service[method]).toHaveBeenCalledWith(...args)
+ * };
+ * ```
+ */
 export interface ServiceTestHarnessReturn<T> {
     service: T;
     dependencies: Map<unknown, unknown>;
@@ -2247,42 +4132,176 @@ export interface ServiceTestHarnessReturn<T> {
     expectCalled: (method: keyof T, times?: number) => void;
     expectCalledWith: (method: keyof T, ...args: unknown[]) => void;
 }
+/**
+ * Class for dynamic NestJS modules.
+ * Provides configuration methods.
+ *
+ * @example
+ * ```typescript
+ * const moduleClass: DynamicModuleClass = {
+ *   forRoot: (config) => ({
+ *     module: DatabaseModule,
+ *     providers: [{ provide: 'CONFIG', useValue: config }],
+ *     exports: [DatabaseService]
+ *   })
+ * };
+ * ```
+ */
 export interface DynamicModuleClass {
     forRoot: (config: unknown) => Record<string, unknown>;
 }
+/**
+ * Expectations for dynamic module testing.
+ * Validates module structure.
+ *
+ * @example
+ * ```typescript
+ * const expectations: DynamicModuleExpectations = {
+ *   providers: [DatabaseService, ConfigService],
+ *   imports: [CommonModule],
+ *   exports: [DatabaseService]
+ * };
+ * ```
+ */
 export interface DynamicModuleExpectations {
     providers?: unknown[];
     imports?: unknown[];
     exports?: unknown[];
 }
+/**
+ * Return value from NestJS test suite setup.
+ * Contains module and providers.
+ *
+ * @example
+ * ```typescript
+ * const setup: NestJSTestSuiteSetupReturn = {
+ *   module: testingModule,
+ *   providers: new Map([[UserService, mockUserService]])
+ * };
+ * ```
+ */
 export interface NestJSTestSuiteSetupReturn {
     module: unknown;
     providers: Map<unknown, unknown>;
 }
+/**
+ * Test for provider dependency injection.
+ * Validates DI relationships.
+ *
+ * @example
+ * ```typescript
+ * const test: ProviderInjectionTest = {
+ *   token: UserService,
+ *   dependencies: [DatabaseService, CacheService],
+ *   testFn: (instance, deps) => {
+ *     expect(instance).toBeDefined();
+ *     expect(deps).toHaveLength(2);
+ *   }
+ * };
+ * ```
+ */
 export interface ProviderInjectionTest {
     token: unknown;
     dependencies: unknown[];
     testFn: (instance: unknown, deps: unknown[]) => void;
 }
+/**
+ * WebSocket ping message.
+ * Used for connection keep-alive.
+ *
+ * @example
+ * ```typescript
+ * const ping: WebSocketPingMessage = {
+ *   type: 'ping'
+ * };
+ * ```
+ */
 export interface WebSocketPingMessage {
     type: 'ping';
 }
+/**
+ * WebSocket pong message.
+ * Response to ping message.
+ *
+ * @example
+ * ```typescript
+ * const pong: WebSocketPongMessage = {
+ *   type: 'pong'
+ * };
+ * ```
+ */
 export interface WebSocketPongMessage {
     type: 'pong';
 }
+/**
+ * WebSocket echo message.
+ * Echoes data back to sender.
+ *
+ * @example
+ * ```typescript
+ * const echo: WebSocketEchoMessage = {
+ *   type: 'echo',
+ *   data: 'Hello WebSocket'
+ * };
+ * ```
+ */
 export interface WebSocketEchoMessage {
     type: 'echo';
     data: string;
 }
+/**
+ * Generic typed WebSocket message.
+ * Base structure for custom messages.
+ *
+ * @example
+ * ```typescript
+ * const message: WebSocketTypedMessage = {
+ *   type: 'notification',
+ *   data: 'User joined the chat'
+ * };
+ * ```
+ */
 export interface WebSocketTypedMessage {
     type: string;
     data: string;
 }
+/**
+ * Input for Next.js image loader.
+ * Parameters for image optimization.
+ *
+ * @example
+ * ```typescript
+ * const input: ImageLoaderInput = {
+ *   src: '/images/hero.jpg',
+ *   width: 1920,
+ *   quality: 85
+ * };
+ * ```
+ */
 export interface ImageLoaderInput {
     src: string;
     width: number;
     quality?: number;
 }
+/**
+ * Step in user flow testing.
+ * Defines interactions and assertions.
+ *
+ * @example
+ * ```typescript
+ * const step: UserFlowStep = {
+ *   name: 'Login flow',
+ *   interactions: [{ type: 'click', target: '#login' }],
+ *   assertions: async () => {
+ *     expect(screen.getByText('Dashboard')).toBeVisible();
+ *   },
+ *   navigation: {
+ *     expectedUrl: '/dashboard',
+ *     waitForNavigation: true
+ *   }
+ * };
+ * ```
+ */
 export interface UserFlowStep {
     name: string;
     interactions: InteractionSequence[];
@@ -2292,6 +4311,23 @@ export interface UserFlowStep {
         waitForNavigation?: boolean;
     };
 }
+/**
+ * Parameters for creating mock Next.js request.
+ * Configures request properties.
+ *
+ * @example
+ * ```typescript
+ * const params: MockNextRequestCreatorParams = {
+ *   url: 'https://example.com/api/users',
+ *   options: {
+ *     method: 'POST',
+ *     headers: { 'Content-Type': 'application/json' },
+ *     body: { name: 'John' },
+ *     searchParams: { page: '1' }
+ *   }
+ * };
+ * ```
+ */
 export interface MockNextRequestCreatorParams {
     url: string;
     options?: {
@@ -2301,11 +4337,44 @@ export interface MockNextRequestCreatorParams {
         searchParams?: Record<string, string>;
     };
 }
+/**
+ * Provider injection configuration.
+ * Maps providers to dependencies.
+ *
+ * @example
+ * ```typescript
+ * const injection: ProviderInjection = {
+ *   token: UserService,
+ *   dependencies: [DatabaseService],
+ *   testFn: (instance, deps) => {
+ *     expect(instance).toBeInstanceOf(UserService);
+ *   }
+ * };
+ * ```
+ */
 export interface ProviderInjection {
     token: unknown;
     dependencies: unknown[];
     testFn: (instance: unknown, deps: unknown[]) => void;
 }
+/**
+ * Mock Redis client interface.
+ * Provides mocked Redis operations.
+ *
+ * @example
+ * ```typescript
+ * const redis: CreateMockRedisClientMock = {
+ *   set: vi.fn().mockResolvedValue('OK'),
+ *   get: vi.fn().mockResolvedValue('value'),
+ *   del: vi.fn().mockResolvedValue(1),
+ *   keys: vi.fn().mockResolvedValue(['key1', 'key2']),
+ *   quit: vi.fn(),
+ *   on: vi.fn(),
+ *   multi: vi.fn(),
+ *   ping: vi.fn().mockResolvedValue('PONG')
+ * };
+ * ```
+ */
 export interface CreateMockRedisClientMock {
     set: Vitest.Mock;
     get: Vitest.Mock;
@@ -2317,8 +4386,17 @@ export interface CreateMockRedisClientMock {
     ping: Vitest.Mock;
 }
 /**
- * Call tracker interface
- * @interface CallTracker
+ * Call tracker for monitoring function calls.
+ * Records call history with arguments and timestamps.
+ *
+ * @example
+ * ```typescript
+ * const tracker: CallTracker = {
+ *   trackCall: (name, args) => calls.push({ name, args, timestamp: Date.now() }),
+ *   getCalls: (name) => name ? calls.filter(c => c.name === name) : calls,
+ *   reset: () => { calls = []; }
+ * };
+ * ```
  */
 export interface CallTracker {
     trackCall: (name: string, args: unknown[]) => void;
@@ -2330,9 +4408,20 @@ export interface CallTracker {
     reset: () => void;
 }
 /**
- * Tracked spy with additional properties
- * @interface TrackedSpy
- * @extends SpyInstance
+ * Enhanced spy with tracking capabilities.
+ * Extends Vitest spy with call history methods.
+ *
+ * @example
+ * ```typescript
+ * const spy: TrackedSpy = Object.assign(vi.fn(), {
+ *   getCallCount: () => spy.mock.calls.length,
+ *   getCallHistory: () => spy.mock.calls.map((args, i) => ({
+ *     args,
+ *     result: spy.mock.results[i]?.value,
+ *     error: spy.mock.results[i]?.type === 'throw' ? spy.mock.results[i].value : undefined
+ *   }))
+ * });
+ * ```
  */
 export interface TrackedSpy extends SpyInstance {
     getCallCount: () => number;
@@ -2350,9 +4439,21 @@ export type SpyMap<T> = {
     [K in keyof T]: SpyInstance;
 };
 /**
- * Tracked data interface
- * @interface TrackedData
- * @typeParam T - Type of tracked data
+ * Data wrapper with access tracking.
+ * Records property access history.
+ *
+ * @template T - Type of data being tracked
+ *
+ * @example
+ * ```typescript
+ * const tracked: TrackedData<User> = {
+ *   data: { id: 1, name: 'John' },
+ *   accesses: [
+ *     { property: 'name', timestamp: 1699123456 },
+ *     { property: 'id', timestamp: 1699123457 }
+ *   ]
+ * };
+ * ```
  */
 export interface TrackedData<T> {
     data: T;
@@ -2362,8 +4463,17 @@ export interface TrackedData<T> {
     }>;
 }
 /**
- * Access information
- * @interface AccessInfo
+ * Information about property access.
+ * Tracks access frequency and timing.
+ *
+ * @example
+ * ```typescript
+ * const access: AccessInfo = {
+ *   property: 'userName',
+ *   timestamp: Date.now(),
+ *   count: 5
+ * };
+ * ```
  */
 export interface AccessInfo {
     property: string | symbol;
@@ -2371,8 +4481,18 @@ export interface AccessInfo {
     count: number;
 }
 /**
- * Worker-like interface for various worker types
- * @interface WorkerLike
+ * Unified interface for different worker implementations.
+ * Compatible with Web Workers, Worker Threads, and custom workers.
+ *
+ * @example
+ * ```typescript
+ * const worker: WorkerLike = {
+ *   postMessage: (msg) => { // send message },
+ *   onmessage: (event) => { // handle message },
+ *   onerror: (error) => { // handle error },
+ *   terminate: () => { // cleanup }
+ * };
+ * ```
  */
 export interface WorkerLike {
     onError?: (error: Error) => void;
@@ -2393,8 +4513,27 @@ export interface WorkerLike {
     terminate?: () => void;
 }
 /**
- * Worker pool interface
- * @interface WorkerPool
+ * Pool of workers for parallel task execution.
+ * Manages worker lifecycle and task distribution.
+ *
+ * @example
+ * ```typescript
+ * const pool: WorkerPool = {
+ *   addTask: (task) => taskQueue.push(task),
+ *   start: async () => { // initialize workers },
+ *   stop: () => { // terminate workers },
+ *   waitForCompletion: async () => { // wait for all tasks },
+ *   getStats: () => ({
+ *     totalWorkers: 4,
+ *     busyWorkers: 2,
+ *     idleWorkers: 2,
+ *     tasksCompleted: 100,
+ *     tasksFailed: 2,
+ *     tasksRemaining: 10,
+ *     workerStats: [// per-worker stats]
+ *   })
+ * };
+ * ```
  */
 export interface WorkerPool {
     addTask: (task: () => Promise<void>) => void;
@@ -2416,8 +4555,22 @@ export interface WorkerPool {
     };
 }
 /**
- * Worker metrics interface
- * @interface WorkerMetrics
+ * Performance metrics for individual workers.
+ * Tracks execution statistics and resource usage.
+ *
+ * @example
+ * ```typescript
+ * const metrics: WorkerMetrics = {
+ *   workerId: 1,
+ *   taskCount: 50,
+ *   executionTime: 5000,
+ *   errors: [],
+ *   throughput: 10, // tasks per second
+ *   avgTaskTime: 100,
+ *   memoryUsage: 50 * 1024 * 1024,
+ *   cpuUsage: 25
+ * };
+ * ```
  */
 export interface WorkerMetrics {
     workerId: number;
@@ -2430,8 +4583,31 @@ export interface WorkerMetrics {
     cpuUsage?: number;
 }
 /**
- * Worker test harness interface
- * @interface WorkerTestHarness
+ * Test harness for worker pool testing.
+ * Provides methods to run and validate worker tests.
+ *
+ * @example
+ * ```typescript
+ * const harness: WorkerTestHarness = {
+ *   run: async () => ({
+ *     metrics: [// worker metrics],
+ *     totalExecutionTime: 10000,
+ *     totalTasks: 100,
+ *     totalErrors: 2
+ *   }),
+ *   assertResults: (results) => {
+ *     expect(results.totalErrors).toBeLessThan(5);
+ *   },
+ *   getMetrics: () => ({
+ *     workerCount: 4,
+ *     totalTasks: 100,
+ *     avgExecutionTime: 100,
+ *     avgThroughput: 10,
+ *     errorCount: 2,
+ *     workerMetrics: [// metrics]
+ *   })
+ * };
+ * ```
  */
 export interface WorkerTestHarness {
     run: () => Promise<{
@@ -2456,8 +4632,21 @@ export interface WorkerTestHarness {
     };
 }
 /**
- * Worker spy interface
- * @interface WorkerSpy
+ * Spy for worker communication testing.
+ * Tracks messages and simulates worker behavior.
+ *
+ * @example
+ * ```typescript
+ * const spy: WorkerSpy = {
+ *   getMessagesSent: () => sentMessages,
+ *   getMessagesReceived: () => receivedMessages,
+ *   getErrors: () => errors,
+ *   isTerminated: () => terminated,
+ *   simulateMessage: (msg) => worker.onmessage({ data: msg }),
+ *   simulateError: (err) => worker.onerror(err),
+ *   reset: () => { // clear all data }
+ * };
+ * ```
  */
 export interface WorkerSpy {
     getMessagesSent: () => unknown[];
@@ -2469,149 +4658,227 @@ export interface WorkerSpy {
     reset: () => void;
 }
 /**
- * Performance profiling options
- * @interface ProfileOptions
+ * Options for performance profiling.
+ * Configures what metrics to collect.
+ *
+ * @example
+ * ```typescript
+ * const options: ProfileOptions = {
+ *   sampleInterval: 10,
+ *   includeMemory: true,
+ *   includeCPU: true
+ * };
+ * ```
  */
 export interface ProfileOptions {
-    /** Sample interval in milliseconds */
     sampleInterval?: number;
-    /** Include memory profiling */
     includeMemory?: boolean;
-    /** Include CPU profiling */
     includeCPU?: boolean;
 }
 /**
- * Performance profile result
- * @interface ProfileResult
- * @typeParam T - Type of profiled operation result
+ * Result from performance profiling.
+ * Contains operation result and performance data.
+ *
+ * @template T - Type of profiled operation result
+ *
+ * @example
+ * ```typescript
+ * const profile: ProfileResult<string> = {
+ *   result: 'operation completed',
+ *   cpuProfile: {
+ *     samples: [10, 15, 20, 18],
+ *     timestamps: [0, 10, 20, 30],
+ *     duration: 30
+ *   },
+ *   memoryProfile: {
+ *     samples: [1000, 1500, 2000],
+ *     timestamps: [0, 15, 30]
+ *   }
+ * };
+ * ```
  */
 export interface ProfileResult<T> {
-    /** Operation result */
     result: T;
-    /** CPU profile data */
     cpuProfile?: {
-        /** Profile samples */
         samples: number[];
-        /** Sample timestamps */
         timestamps: number[];
         duration: number;
     };
-    /** Memory profile data */
     memoryProfile?: {
-        /** Memory usage samples */
         samples: number[];
-        /** Memory timestamps */
         timestamps: number[];
     };
 }
 /**
- * Stress testing options
- * @interface StressTestOptions
+ * Options for stress testing.
+ * Configures load parameters and error thresholds.
+ *
+ * @example
+ * ```typescript
+ * const options: StressTestOptions = {
+ *   duration: 60000, // 1 minute
+ *   concurrency: 100,
+ *   rampUp: 5000,
+ *   maxErrors: 50,
+ *   errorThreshold: 0.05 // 5% error rate
+ * };
+ * ```
  */
 export interface StressTestOptions {
-    /** Test duration in milliseconds */
     duration?: number;
-    /** Number of concurrent operations */
     concurrency?: number;
-    /** Ramp-up time */
     rampUp?: number;
     maxErrors?: number;
     errorThreshold?: number;
 }
 /**
- * Stress test result
- * @interface StressTestResult
+ * Results from stress testing.
+ * Contains operation statistics and error information.
+ *
+ * @example
+ * ```typescript
+ * const result: StressTestResult = {
+ *   totalOperations: 10000,
+ *   successfulOperations: 9500,
+ *   failedOperations: 500,
+ *   averageResponseTime: 150,
+ *   operationsPerSecond: 166.67,
+ *   errorRate: 0.05,
+ *   errors: [// error objects]
+ * };
+ * ```
  */
 export interface StressTestResult {
-    /** Total operations performed */
     totalOperations: number;
-    /** Successful operations */
     successfulOperations: number;
-    /** Failed operations */
     failedOperations: number;
-    /** Average response time */
     averageResponseTime: number;
     operationsPerSecond: number;
     errorRate: number;
     errors: Error[];
 }
 /**
- * Throughput test result
- * @interface ThroughputResult
+ * Results from throughput testing.
+ * Measures operation rate and latency.
+ *
+ * @example
+ * ```typescript
+ * const result: ThroughputResult = {
+ *   operationsCompleted: 1000,
+ *   duration: 10000,
+ *   throughput: 100, // ops per second
+ *   averageLatency: 10,
+ *   minLatency: 5,
+ *   maxLatency: 50
+ * };
+ * ```
  */
 export interface ThroughputResult {
-    /** Operations completed */
     operationsCompleted: number;
-    /** Test duration */
     duration: number;
-    /** Throughput rate */
     throughput: number;
     averageLatency: number;
     minLatency: number;
     maxLatency: number;
 }
 /**
- * Performance monitoring options
- * @interface MonitorOptions
+ * Options for performance monitoring.
+ * Configures metrics collection.
+ *
+ * @example
+ * ```typescript
+ * const options: MonitorOptions = {
+ *   interval: 100, // sample every 100ms
+ *   metrics: ['cpu', 'memory', 'time']
+ * };
+ * ```
  */
 export interface MonitorOptions {
-    /** Monitoring interval */
     interval?: number;
-    /** Metrics to collect */
     metrics?: Array<'cpu' | 'memory' | 'time'>;
 }
 /**
- * Performance monitor interface
- * @interface PerformanceMonitor
+ * Monitor for collecting performance metrics.
+ * Provides real-time performance tracking.
+ *
+ * @example
+ * ```typescript
+ * const monitor: PerformanceMonitor = {
+ *   start: () => { // begin monitoring },
+ *   stop: () => { // stop monitoring },
+ *   getMetrics: () => ({
+ *     cpu: [25, 30, 28, 35],
+ *     memory: [100, 110, 115, 120],
+ *     timestamps: [0, 100, 200, 300]
+ *   })
+ * };
+ * ```
  */
 export interface PerformanceMonitor {
-    /** Start monitoring */
     start: () => void;
-    /** Stop monitoring */
     stop: () => void;
-    /** Get collected metrics */
     getMetrics: () => {
-        /** CPU metrics */
         cpu?: number[];
-        /** Memory metrics */
         memory?: number[];
-        /** Time metrics */
         timestamps: number[];
     };
 }
 /**
- * Memory leak testing options
- * @interface LeakOptions
+ * Options for memory leak testing.
+ * Configures leak detection parameters.
+ *
+ * @example
+ * ```typescript
+ * const options: LeakOptions = {
+ *   iterations: 100,
+ *   threshold: 10 * 1024 * 1024, // 10MB
+ *   gcBetweenRuns: true
+ * };
+ * ```
  */
 export interface LeakOptions {
-    /** Number of test iterations */
     iterations?: number;
-    /** Memory threshold */
     threshold?: number;
-    /** Run GC between runs */
     gcBetweenRuns?: boolean;
 }
 /**
- * Memory leak test result
- * @interface LeakResult
+ * Result from memory leak testing.
+ * Indicates leak presence and growth rate.
+ *
+ * @example
+ * ```typescript
+ * const result: LeakResult = {
+ *   hasLeak: true,
+ *   memoryGrowth: 5 * 1024 * 1024, // 5MB growth
+ *   measurements: [
+ *     { iteration: 0, memory: 50000000 },
+ *     { iteration: 50, memory: 52500000 },
+ *     { iteration: 100, memory: 55000000 }
+ *   ]
+ * };
+ * ```
  */
 export interface LeakResult {
-    /** Whether leak was detected */
     hasLeak: boolean;
-    /** Memory growth amount */
     memoryGrowth: number;
-    /** Memory measurements */
     measurements: Array<{
-        /** Iteration number */
         iteration: number;
-        /** Memory usage */
         memory: number;
     }>;
 }
 /**
- * Hook testing scenario
- * @interface HookScenario
- * @typeParam T - Type of hook result
+ * Scenario for testing React hooks.
+ * Defines actions and expected state.
+ *
+ * @example
+ * ```typescript
+ * const scenario: HookScenario = {
+ *   name: 'increment counter',
+ *   action: () => result.current.increment(),
+ *   expectedState: { count: 1, loading: false },
+ *   expectedError: null
+ * };
+ * ```
  */
 export interface HookScenario {
     name: string;
@@ -2798,7 +5065,7 @@ export interface DragOptions {
     steps?: number;
     dropEffect?: 'move' | 'copy' | 'link' | 'none';
 }
-export type TouchGestureAdvancedAdvanced = {
+export type TouchGestureAdvanced = {
     type: 'tap';
     x: number;
     y: number;
@@ -2847,36 +5114,24 @@ export interface Interaction {
  * @interface SwipeGestureParams
  */
 export interface SwipeGestureParams {
-    /** Start coordinates */
-    start: {
-        x: number;
-        y: number;
-    };
-    /** End coordinates */
-    end: {
-        x: number;
-        y: number;
-    };
-    /** Gesture duration */
-    duration?: number;
-    /** Number of touch points */
-    touches?: number;
+    element: Element;
+    startX: number;
+    startY: number;
+    endX: number;
+    endY: number;
+    duration: number;
 }
 /**
  * Pinch gesture parameters
  * @interface PinchGestureParams
  */
 export interface PinchGestureParams {
-    /** Center coordinates */
     center: {
         x: number;
         y: number;
     };
-    /** Scale factor */
     scale: number;
-    /** Gesture duration */
     duration?: number;
-    /** Rotation angle */
     rotation?: number;
 }
 /**
@@ -2928,12 +5183,9 @@ export interface IntervalHandle {
  * @interface ScheduleHandle
  */
 export interface ScheduleHandle {
-    /** Timeout ID */
-    id: number;
-    /** Cancel schedule */
-    cancel: () => void;
-    /** Check if pending */
-    isPending: () => boolean;
+    stop: () => void;
+    nextRun: () => Date | null;
+    isRunning: () => boolean;
 }
 /**
  * Timer interface
@@ -2960,14 +5212,11 @@ export interface Countdown {
  * @interface HistoryEntry
  */
 export interface MockHistoryEntry {
-    /** Entry URL */
-    url: string;
-    /** Entry state */
+    pathname: string;
+    search?: string;
+    hash?: string;
     state?: unknown;
-    /** Entry title */
-    title?: string;
-    /** Entry timestamp */
-    timestamp: number;
+    key?: string;
 }
 /**
  * Mock history object
@@ -2993,15 +5242,10 @@ export interface MockHistory {
  * @interface MockLocation
  */
 export interface MockLocation {
-    /** Current pathname */
     pathname: string;
-    /** Current search */
     search: string;
-    /** Current hash */
     hash: string;
-    /** Current state */
     state: unknown;
-    /** Location key */
     key: string;
     href: string;
     origin: string;
@@ -3044,9 +5288,7 @@ export interface GuardScenario {
  * @interface NavOptions
  */
 export interface NavOptions {
-    /** Replace current entry */
     replace?: boolean;
-    /** Navigation state */
     state?: unknown;
     shallow?: boolean;
 }
@@ -3118,13 +5360,9 @@ export interface APIRequest {
  * @interface LifecycleScenario
  */
 export interface LifecycleScenario {
-    /** Scenario name */
     name: string;
-    /** Action to perform */
     action: () => void | Promise<void>;
-    /** Expected state after action */
     expectedState?: Record<string, unknown>;
-    /** Expected events */
     expectedEvents?: string[];
 }
 /**
@@ -3132,21 +5370,17 @@ export interface LifecycleScenario {
  * @interface LifecycleTracker
  */
 export interface LifecycleTracker {
-    /** Recorded events */
     events: Array<{
         type: string;
         timestamp: number;
         data?: unknown;
     }>;
-    /** Clear all events */
     clear: () => void;
-    /** Get all events */
     getEvents: () => Array<{
         type: string;
         timestamp: number;
         data?: unknown;
     }>;
-    /** Get events by type */
     getEventsByType: (type: string) => Array<{
         type: string;
         timestamp: number;
@@ -3158,9 +5392,7 @@ export interface LifecycleTracker {
  * @interface LifecycleEvent
  */
 export interface LifecycleEvent {
-    /** Event type */
     type: string;
-    /** Event data */
     data?: unknown;
 }
 /**
@@ -3168,11 +5400,8 @@ export interface LifecycleEvent {
  * @interface CleanupResult
  */
 export interface CleanupResult {
-    /** Whether cleanup was successful */
     cleanedUp: boolean;
-    /** Cleaned up resources */
     resources: string[];
-    /** Cleanup errors */
     errors: Error[];
 }
 /**
@@ -3180,11 +5409,8 @@ export interface CleanupResult {
  * @interface LifecycleMetrics
  */
 export interface LifecycleMetrics {
-    /** Mount time */
     mountTime: number;
-    /** Update time */
     updateTime: number;
-    /** Unmount time */
     unmountTime: number;
     totalLifecycleTime: number;
     renderCount: number;
@@ -3194,15 +5420,10 @@ export interface LifecycleMetrics {
  * @interface FileSnapshot
  */
 export interface FileSnapshot {
-    /** File path */
     path: string;
-    /** File size */
     size: number;
-    /** Modification time */
     mtime: Date;
-    /** File content */
     content: string;
-    /** Content hash */
     hash: string;
 }
 /**
@@ -3220,7 +5441,6 @@ interface EnvConfig {
  * @interface TestEnvironment
  */
 export interface TestEnvironment {
-    /** Get environment variable */
     get: (key: string) => string | undefined;
     set: (key: string, value: string) => void;
     reset: () => void;
@@ -3231,7 +5451,6 @@ export interface TestEnvironment {
  * @interface EnvMock
  */
 export interface EnvMock {
-    /** Restore original environment */
     restore: () => void;
     update: (vars: Record<string, string>) => void;
     clear: () => void;
@@ -3241,7 +5460,6 @@ export interface EnvMock {
  * @interface EnvSnapshot
  */
 export interface EnvSnapshot {
-    /** Environment variables */
     variables: Record<string, string | undefined>;
     timestamp: number;
 }