@flemist/test-variants 3.0.3 → 5.0.1

package/build/common/test-variants/run/RunContext.d.ts

@@ -0,0 +1,21 @@
+import { IAbortSignalFast, IAbortControllerFast } from '@flemist/abort-controller-fast';
+import { Obj } from '@flemist/simple-utils';
+import { IPool } from '@flemist/time-limits';
+import { VariantsIterator } from '../iterator/types';
+import { TestOptions } from '../types';
+import { RunState } from './createRunState';
+import { RunOptionsResolved } from './resolveRunOptions';
+import { TestVariantsTestRun } from './types';
+/** Context for test variants iteration loop */
+export type RunContext<Args extends Obj> = {
+    options: RunOptionsResolved<Args>;
+    testRun: TestVariantsTestRun<Args>;
+    variantsIterator: VariantsIterator<Args>;
+    testOptions: TestOptions;
+    testOptionsParallel: TestOptions;
+    abortControllerGlobal: IAbortControllerFast;
+    abortControllerParallel: IAbortControllerFast;
+    abortSignal: IAbortSignalFast;
+    pool: IPool | null;
+    state: RunState;
+};

package/build/common/test-variants/run/createRunResult.d.ts

@@ -0,0 +1,6 @@
+import { Obj } from '@flemist/simple-utils';
+import { VariantsIterator } from '../iterator/types';
+import { TestVariantsResult } from '../types';
+import { RunState } from './createRunState';
+/** Create test variants run result */
+export declare function createRunResult<Args extends Obj>(state: RunState, variantsIterator: VariantsIterator<Args>, dontThrowIfError: boolean | null | undefined): TestVariantsResult<Args>;

package/build/common/test-variants/run/createRunState.d.ts

@@ -0,0 +1,23 @@
+import { ITimeController } from '@flemist/time-controller';
+import { ModeChangeEvent } from '../types';
+/** Runtime state for test variants run */
+export type RunState = {
+    startTime: number;
+    startMemory: number | null;
+    /** Few repeats of error variant if JS debugger is attached */
+    debugMode: boolean;
+    /** Number of test function calls */
+    tests: number;
+    /** Sum of iterationsSync + iterationsAsync from test results */
+    iterations: number;
+    iterationsAsync: number;
+    prevLogTime: number;
+    prevLogMemory: number | null;
+    /** Mode change event waiting to be logged with next progress */
+    pendingModeChange: ModeChangeEvent | null;
+    prevGcTime: number;
+    prevGcIterations: number;
+    prevGcIterationsAsync: number;
+};
+/** Create initial run state */
+export declare function createRunState(timeController: ITimeController, startMemory: number | null): RunState;

package/build/common/test-variants/run/errorHandlers.d.ts

@@ -0,0 +1,20 @@
+import { PromiseOrValue } from '@flemist/async-utils';
+import { Obj } from '@flemist/simple-utils';
+import { ArgsWithSeed } from '../types';
+import { RunContext } from './RunContext';
+/**
+ * Handle test error in parallel execution mode.
+ *
+ * In findBestError mode:
+ * - With sequentialOnError=true: adds limit, saves args, aborts parallel (fall back to sequential)
+ * - With sequentialOnError=false: adds limit, saves args, continues parallel with new limits
+ * Without findBestError: saves args and aborts with error.
+ */
+export declare function handleErrorParallel<Args extends Obj>(runContext: RunContext<Args>, args: ArgsWithSeed<Args>, error: unknown, tests: number): void;
+/**
+ * Handle test error in sequential execution mode.
+ *
+ * In findBestError mode: adds limit to iterator, saves args.
+ * Without findBestError: saves args and throws error.
+ */
+export declare function handleErrorSequential<Args extends Obj>(runContext: RunContext<Args>, args: ArgsWithSeed<Args>, error: unknown, tests: number): PromiseOrValue<void>;

package/build/common/test-variants/run/gcManager.d.ts

@@ -0,0 +1,6 @@
+import { RunContext } from './RunContext';
+import { RunState } from './createRunState';
+/** Check if GC should be triggered */
+export declare function shouldTriggerGC(runContext: RunContext<any>, now: number): boolean;
+/** Trigger GC and update state */
+export declare function triggerGC(state: RunState, now: number): Promise<void>;

package/build/common/test-variants/run/resolveRunOptions.d.ts

@@ -0,0 +1,23 @@
+import { IAbortSignalFast } from '@flemist/abort-controller-fast';
+import { RequiredNonNullable, Obj } from '@flemist/simple-utils';
+import { ITimeController } from '@flemist/time-controller';
+import { TestVariantsLogOptions, FindBestErrorOptions } from '../types';
+import { TestVariantsRunOptionsInternal, SaveErrorVariantsStore } from './types';
+/** Resolved configuration for test variants run */
+export type RunOptionsResolved<Args extends Obj> = {
+    store: SaveErrorVariantsStore<Args> | null;
+    GC_Iterations: number;
+    GC_IterationsAsync: number;
+    GC_Interval: number;
+    logOptions: RequiredNonNullable<TestVariantsLogOptions>;
+    abortSignalExternal: IAbortSignalFast | null | undefined;
+    findBestError: FindBestErrorOptions | null | undefined;
+    dontThrowIfError: boolean | null | undefined;
+    timeController: ITimeController;
+    /** Maximum number of parallel threads */
+    parallel: number;
+    /** Switch to sequential mode after first error in findBestError mode */
+    sequentialOnError: boolean;
+};
+/** Resolve run options into normalized structure */
+export declare function resolveRunOptions<Args extends Obj, SavedArgs = Args>(options: TestVariantsRunOptionsInternal<Args, SavedArgs> | null | undefined): RunOptionsResolved<Args>;

package/build/common/test-variants/run/runIterationLoop.d.ts

@@ -0,0 +1,9 @@
+import { PromiseOrValue } from '@flemist/async-utils';
+import { Obj } from '@flemist/simple-utils';
+import { RunContext } from './RunContext';
+/**
+ * Main iteration loop with sync mode optimization.
+ * Runs synchronously when all tests are sync and no async operations are triggered.
+ * Iterator handles all termination conditions internally via next() returning null.
+ */
+export declare function runIterationLoop<Args extends Obj>(runContext: RunContext<Args>): PromiseOrValue<void>;

package/build/common/test-variants/run/runLogger.d.ts

@@ -0,0 +1,9 @@
+import { RequiredNonNullable } from '@flemist/simple-utils';
+import { TestVariantsLogOptions } from '../types';
+import { RunContext } from './RunContext';
+export declare function logStart(logOptions: RequiredNonNullable<TestVariantsLogOptions>, startMemory: number | null): void;
+export declare function logCompleted(runContext: RunContext<any>): void;
+/** Log pending mode change and clear it */
+export declare function logModeChange(runContext: RunContext<any>): void;
+/** Returns true if logging was performed */
+export declare function logProgress(runContext: RunContext<any>): boolean;

package/build/common/test-variants/run/types.d.ts

@@ -0,0 +1,57 @@
+import { PromiseOrValue } from '@flemist/async-utils';
+import { Obj, RequiredNonNullable } from '@flemist/simple-utils';
+import { TestVariantsTemplatesExt, VariantsIterator } from '../iterator/types';
+import { ArgsWithSeed, OnErrorCallback, SaveErrorVariantsOptions, TestOptions, TestVariantsLogOptions, TestVariantsResult, TestVariantsRunOptions } from '../types';
+/** Result of test run (internal format with separate sync/async counts) */
+export type TestFuncResult = void | {
+    iterationsAsync: number;
+    iterationsSync: number;
+};
+/** Test run function (internal - wraps user's test with error handling) */
+export type TestVariantsTestRun<Args extends Obj> = (args: ArgsWithSeed<Args>, tests: number, options: TestOptions) => PromiseOrValue<TestFuncResult>;
+/** Result of user's test function (number treated as iterationsSync) */
+export type TestVariantsTestResult = number | void | TestFuncResult;
+/** User's test function */
+export type TestVariantsTest<Args extends Obj> = (args: ArgsWithSeed<Args>, options: TestOptions) => PromiseOrValue<TestVariantsTestResult>;
+/**
+ * Store for saving and loading error-causing parameter combinations.
+ * Node.js implementation uses file system. Browser returns null (not supported).
+ */
+export interface SaveErrorVariantsStore<Args extends Obj> {
+    /**
+     * Save error-causing args to storage.
+     * Handles concurrency protection and deduplication internally.
+     */
+    save(args: ArgsWithSeed<Args>): Promise<void>;
+    /**
+     * Replay saved error variants before normal iteration.
+     * If error occurs during replay:
+     * - In findBestError mode (useToFindBestError + findBestErrorEnabled): adds limit and continues
+     * - Otherwise: throws the error
+     */
+    replay(options: SaveErrorVariantsStoreReplayOptions<Args>): Promise<void>;
+}
+/** Options for SaveErrorVariantsStore.replay method */
+export type SaveErrorVariantsStoreReplayOptions<Args extends Obj> = {
+    /** Test run function */
+    testRun: TestVariantsTestRun<Args>;
+    /** Iterator to add limits to */
+    variantsIterator: VariantsIterator<Args>;
+    /** Options passed to test function */
+    testOptions: TestOptions;
+    /** Whether findBestError is enabled */
+    findBestErrorEnabled?: null | boolean;
+};
+/** Factory function for creating SaveErrorVariantsStore */
+export type CreateSaveErrorVariantsStore<Args extends Obj, SavedArgs = Args> = (options: SaveErrorVariantsOptions<Args, SavedArgs>) => SaveErrorVariantsStore<Args> | null;
+/** Internal run options with injected dependencies */
+export type TestVariantsRunOptionsInternal<Args extends Obj = Obj, SavedArgs = Args> = TestVariantsRunOptions<Args, SavedArgs> & {
+    createSaveErrorVariantsStore?: null | CreateSaveErrorVariantsStore<Args, SavedArgs>;
+};
+export type TestVariantsCreateTestRunOptions<Args extends Obj> = {
+    onError?: null | OnErrorCallback<Args>;
+    /** Resolved logging options */
+    log: RequiredNonNullable<TestVariantsLogOptions>;
+};
+export type TestVariantsCall<Args extends Obj> = <SavedArgs = Args>(options?: null | TestVariantsRunOptionsInternal<Args, SavedArgs>) => PromiseOrValue<TestVariantsResult<Args>>;
+export type TestVariantsSetArgs<Args extends Obj> = <ArgsExtra extends Obj>(args: TestVariantsTemplatesExt<Omit<Args, 'seed'>, Omit<ArgsExtra, 'seed'>>) => TestVariantsCall<Args>;

package/build/common/test-variants/testVariantsRun.d.ts

@@ -0,0 +1,6 @@
+import { Obj } from '@flemist/simple-utils';
+import { VariantsIterator } from './iterator/types';
+import { RunState } from './run/createRunState';
+import { TestVariantsTestRun, TestVariantsRunOptionsInternal } from './run/types';
+import { TestVariantsResult } from './types';
+export declare function testVariantsRun<Args extends Obj, SavedArgs = Args>(testRun: TestVariantsTestRun<Args>, variantsIterator: VariantsIterator<Args>, state: RunState, options?: null | TestVariantsRunOptionsInternal<Args, SavedArgs>): Promise<TestVariantsResult<Args>>;

package/build/common/test-variants/types.d.ts

@@ -0,0 +1,187 @@
+import { IAbortSignalFast } from '@flemist/abort-controller-fast';
+import { PromiseOrValue } from '@flemist/async-utils';
+import { Obj } from '@flemist/simple-utils';
+import { ITimeController } from '@flemist/time-controller';
+export type { TestVariantsTemplatesExt } from './iterator/types';
+export type { TestVariantsCall, TestVariantsSetArgs, TestVariantsTestResult, } from './run/types';
+export type Equals = (a: any, b: any) => boolean;
+/** Args with seed from getSeed */
+export type ArgsWithSeed<Args extends Obj> = Args & {
+    seed: any;
+};
+/** Base mode configuration shared by all modes */
+export type BaseModeConfig = {
+    /** Maximum time in ms for this phase */
+    limitTime?: null | number;
+    /** Maximum total picks in this phase */
+    limitTests?: null | number;
+};
+/** Sequential mode configuration shared by forward and backward modes */
+export type SequentialModeConfig = BaseModeConfig & {
+    /** Number of full passes through all variants */
+    cycles?: null | number;
+    /** Number of repeat tests per variant */
+    attemptsPerVariant?: null | number;
+};
+/** Forward mode configuration */
+export type ForwardModeConfig = SequentialModeConfig & {
+    mode: 'forward';
+};
+/** Backward mode configuration - iterates from last to first combination within limits */
+export type BackwardModeConfig = SequentialModeConfig & {
+    mode: 'backward';
+};
+/** Random mode configuration */
+export type RandomModeConfig = BaseModeConfig & {
+    mode: 'random';
+};
+/** Mode configuration for iteration phase */
+export type ModeConfig = ForwardModeConfig | BackwardModeConfig | RandomModeConfig;
+export type ModeType = ModeConfig['mode'];
+/** Parameters passed to getSeed function for generating test seeds */
+export type GetSeedParams = {
+    /** Total number of tests run */
+    tests: number;
+};
+/** Options for limiting per-arg indexes on error */
+export type LimitArgOnErrorOptions = {
+    /** Arg name */
+    name: string;
+    /** Current template values array for this arg */
+    values: readonly any[];
+    /** Current max value index limit for this arg; null if no limit */
+    maxValueIndex: number | null;
+};
+/** Callback to decide whether to apply limit for specific arg */
+export type LimitArgOnError = (options: LimitArgOnErrorOptions) => boolean;
+/** Log entry type for custom log function */
+export type TestVariantsLogType = Exclude<keyof TestVariantsLogOptions, 'func'>;
+/** Custom log function signature */
+export type TestVariantsLogFunc = (type: TestVariantsLogType, message: string) => void;
+/** Logging options for test-variants */
+export type TestVariantsLogOptions = {
+    /** Log at test start with memory info; default true */
+    start?: null | boolean;
+    /** Progress log interval in ms; false/0 to disable; default 5000 */
+    progress?: null | false | number;
+    /** Log on completion; default true */
+    completed?: null | boolean;
+    /** Log error details (variant index, args, error); default true */
+    error?: null | boolean;
+    /** Log mode changes with all parameters; default true */
+    modeChange?: null | boolean;
+    /** Debug logging for internal behavior; default false */
+    debug?: null | boolean;
+    /** Custom log function; receives log type and formatted message */
+    func?: null | TestVariantsLogFunc;
+};
+/** Options for generating error variant file path */
+export type GenerateErrorVariantFilePathOptions = {
+    sessionDate: Date;
+};
+/** Options for saving and replaying error-causing parameter combinations */
+export type SaveErrorVariantsOptions<Args extends Obj, SavedArgs = Args> = {
+    /** Directory path for error variant JSON files */
+    dir: string;
+    /** Retry attempts per variant during replay phase (default: 1) */
+    attemptsPerVariant?: null | number;
+    /** Custom file path generator; returns path relative to dir, or absolute path; null - use default path */
+    getFilePath?: null | ((options: GenerateErrorVariantFilePathOptions) => string | null);
+    /** Transform args before JSON serialization */
+    argsToJson?: null | ((args: ArgsWithSeed<Args>) => string | SavedArgs);
+    /** Transform parsed JSON back to args */
+    jsonToArgs?: null | ((json: SavedArgs) => ArgsWithSeed<Args>);
+    /** Use saved errors to set findBestError limits instead of throwing on replay */
+    useToFindBestError?: null | boolean;
+    /** Limit per-arg indexes; boolean enables/disables, function for custom per-arg logic */
+    limitArg?: null | boolean | LimitArgOnError;
+    /** Extend template with extra args from limit if they are missing */
+    extendTemplates?: null | boolean;
+};
+/** Options passed to test function */
+export type TestOptions = {
+    abortSignal: IAbortSignalFast;
+    timeController: ITimeController;
+};
+/** Options for finding the earliest failing variant across multiple test runs */
+export type FindBestErrorOptions = {
+    /** Custom equality for comparing arg values when finding indexes */
+    equals?: null | Equals;
+    /** Limit per-arg indexes on error; boolean enables/disables, function for custom per-arg logic */
+    limitArgOnError?: null | boolean | LimitArgOnError;
+    /** When true, error variant is included in iteration (for debugging); default false excludes it */
+    includeErrorVariant?: null | boolean;
+    /** Return found error instead of throwing after all cycles complete */
+    dontThrowIfError?: null | boolean;
+};
+/** Best error found during test run */
+export type TestVariantsBestError<Args extends Obj> = {
+    error: any;
+    args: Args;
+    /** Number of tests run before the error (including attemptsPerVariant) */
+    tests: number;
+};
+/** Result of test variants run */
+export type TestVariantsResult<Args extends Obj> = {
+    iterations: number;
+    bestError: null | TestVariantsBestError<Args>;
+};
+/** Error event passed to onError callback */
+export type ErrorEvent<Args extends Obj> = {
+    error: any;
+    args: Args;
+    /** Number of tests run before this error (including attemptsPerVariant) */
+    tests: number;
+};
+/** Callback invoked when a test variant throws an error */
+export type OnErrorCallback<Args extends Obj> = (event: ErrorEvent<Args>) => PromiseOrValue<void>;
+/** Mode change event passed to onModeChange callback */
+export type ModeChangeEvent = {
+    /** Current mode configuration */
+    mode: ModeConfig;
+    /** Current mode index in iterationModes array */
+    modeIndex: number;
+    /** Number of tests run before this mode change */
+    tests: number;
+};
+/** Callback invoked when iteration mode changes */
+export type OnModeChangeCallback = (event: ModeChangeEvent) => void;
+/** Options for parallel test execution */
+export type ParallelOptions = {
+    /** Number of parallel threads; true = unlimited, false/1 = sequential */
+    count?: null | number | boolean;
+    /** Switch to sequential mode after first error in findBestError mode */
+    sequentialOnError?: null | boolean;
+};
+export type TestVariantsRunOptions<Args extends Obj = Obj, SavedArgs = Args> = {
+    /** Callback invoked when a test variant throws an error */
+    onError?: null | OnErrorCallback<Args>;
+    /** Callback invoked when iteration mode changes */
+    onModeChange?: null | OnModeChangeCallback;
+    /** Wait for garbage collection after iterations */
+    GC_Iterations?: null | number;
+    /** Same as GC_Iterations but only for async test variants, required for 10000 and more of Promise rejections */
+    GC_IterationsAsync?: null | number;
+    /** Wait for garbage collection after time interval, required to prevent the karma browserDisconnectTimeout */
+    GC_Interval?: null | number;
+    /** Logging options; null/true uses defaults; false disables all; object for fine-grained control */
+    log?: null | boolean | TestVariantsLogOptions;
+    abortSignal?: null | IAbortSignalFast;
+    /** Parallel execution; true = unlimited, number = max parallel, false/1 = sequential, object = ParallelOptions */
+    parallel?: null | number | boolean | ParallelOptions;
+    /** Number of full passes through all variants; default 1 */
+    cycles?: null | number;
+    /** Generates seed for reproducible randomized testing; seed is added to args */
+    getSeed?: null | ((params: GetSeedParams) => any);
+    /** Iteration modes (variant traversal methods); each mode runs until its limits are reached */
+    iterationModes?: null | readonly ModeConfig[];
+    findBestError?: null | FindBestErrorOptions;
+    /** Save error-causing args to files and replay them before normal iteration */
+    saveErrorVariants?: null | SaveErrorVariantsOptions<Args, SavedArgs>;
+    /** Tests only first N variants, ignores the rest. If null or not specified, tests all variants */
+    limitTests?: null | number;
+    /** Maximum test run duration in milliseconds; when exceeded, iteration stops and current results are returned */
+    limitTime?: null | number;
+    /** Time controller for testable time-dependent operations; null uses timeControllerDefault */
+    timeController?: null | ITimeController;
+};