@flemist/test-variants 3.0.3 → 5.0.0

package/README.md

@@ -1,66 +1,300 @@
 [![NPM Version][npm-image]][npm-url]
 [![NPM Downloads][downloads-image]][downloads-url]
 [![Build Status][github-image]][github-url]
-[![Test Coverage][coveralls-image]][coveralls-url]
+<!-- [![Test Coverage][coveralls-image]][coveralls-url] -->
 
-Runs a test function with all possible combinations of its parameters.
+# @flemist/test-variants
 
-# Usage
+TypeScript library for combinatorial randomized testing - runs a test function with all possible parameter combinations
+
+## Terms
+
+- `test` - function being tested with different parameter combinations
+- `createTestVariants` - function that creates the testVariants function
+- `testVariants` - function that runs the test iterating through parameter combinations
+- `variant` - specific combination of parameters for the test
+- `parameter template` - object where each test parameter corresponds to an array of possible values
+- `seed` - value for initializing the pseudo-random generator inside the test, for reproducibility of randomized tests
+- `iteration` - single test run with a specific parameter combination
+- `iterating` - traversing parameter combinations (forward, backward, random)
+- `async iteration` - iteration where the test function returns Promise
+- `sync iteration` - iteration where the test function returns void or a value
+- `iteration mode` - method of traversing variants (forward, backward, random)
+- `full pass` - when all possible variants within constraints have been used at least once (possible only for forward and backward iteration modes)
+- `variant attempts` - number of test runs with the same parameter variant before moving to the next variant
+- `cycle` - full pass through all parameter variants
+- `best error` - error that occurred on the lexicographically smallest parameter variant, i.e., the most convenient for debugging
+- `IAbortSignalFast` - interface for aborting async operations (see @flemist/abort-controller-fast)
+
+## Public API
 
-## Sync only
 ```ts
-const result = []
-const testVariants = createTestVariants(({a, b, c}: { a: number, b: string, c: boolean }) => {
-    result.push([a, b, c])
+// Creates a function for running tests with all parameter combinations
+// The test function is passed as parameter, it can be: sync, async, or hybrid
+const testVariants = createTestVariants(async (
+  // test parameters that will be iterated
+  {
+    arg1,
+    arg2,
+    arg3,
+    seed,
+  }: {
+    arg1: Type1,
+    arg2: Type2,
+    arg3: Type3,
+    // seed is generated automatically or by getSeed function,
+    // can be any type: number, string, object, function, etc.
+    // intended for pseudo-random generator and reproducibility of randomized tests
+    seed?: number | null,
+  },
+  {
+    // created by testVariants, combined with abortSignal from run options if provided
+    // use to abort async operations or check abortSignal.aborted
+    abortSignal,
+    // from run options timeController, or timeControllerDefault if not specified
+    // use for time-dependent operations: timeController.now(), delays, etc.
+    timeController,
+  }: TestVariantsTestOptions,
+) => {
+  // test body
+
+  // Returns: void | number | { iterationsAsync: number, iterationsSync: number }
+  // Return iterationsAsync and iterationsSync if you need to count the total number
+  // of async and sync iterations inside the test
+  // number is equivalent to iterationsSync
 })
-const count = await testVariants({
-    a: [1, 2],
-    b: ['3', '4'],
-    c: [true, false],
+
+const result = await testVariants({
+  // parameter templates
+  arg1: [value1, value2, value3],
+  arg2: (args) => [valueA, valueB],  // args: { arg1 } - already assigned parameters
+  arg3: [valueX],
 })({
-  pauseInterval: 10000, // pause after each 10 seconds and log inerations count, it needed for karma tests
-  pauseTime: 10, // continue after 10 milliseconds
-})
+  // All parameters are optional
+  // Missing values or null mean default value is used
 
-// result == [
-//     [1, '3', true],
-//     [1, '3', false],
-//     [1, '4', true],
-//     [1, '4', false],
-//     [2, '3', true],
-//     [2, '3', false],
-//     [2, '4', true],
-//     [2, '4', false],
-// ]
-// count == 8
-```
+  // Automatic garbage collection after N iterations or after time interval
+  // Useful for preventing timeout in karma for sync tests,
+  // or preventing hangs in Node.js due to Promise bugs
+  GC_Iterations: number,      // default: 1000000
+  GC_IterationsAsync: number, // default: 10000
+  GC_Interval: number,        // default: 1000 (milliseconds)
 
-## Async
-```ts
-const result = []
-const testVariants = createTestVariants(async ({a, b, c}: { a: number, b: string, c: boolean }) => {
-  await delay(10)
-  result.push([a, b, c])
+  // Console output parameters, default: true
+  log: true, // all console output parameters default
+  log: boolean | {
+    // message about test start
+    start: boolean,           // default: true
+    // every N milliseconds shows progress info and statistics; false/0 to disable
+    progress: number | false, // default: 5000 (milliseconds)
+    // message about test completion
+    completed: boolean,       // default: true
+    // full error log with stack trace
+    error: boolean,           // default: true
+    // message about iteration mode change, with info about current mode
+    modeChange: boolean,      // default: true
+    // debug logging for internal behavior
+    debug: boolean,           // default: false
+    // custom log function; receives log type and formatted message
+    func: (type: 'start' | 'progress' | 'completed' | 'error' | 'modeChange' | 'debug', message: string) => void,
+  },
+
+  // for aborting async operations inside the test
+  abortSignal: IAbortSignalFast,
+
+  // Parallel execution (for async tests)
+  parallel: boolean | number | ParallelOptions, // default: 1 - no parallel
+  parallel: true,             // all parallel
+  parallel: 4,                // maximum 4 parallel
+  parallel: false | 1,        // sequential
+  parallel: {
+    count: 4,                 // maximum 4 parallel
+    sequentialOnError: true,  // switch to sequential after first error (findBestError mode)
+  },
+
+  // Global limits
+  // Maximum total number of tests run (including attemptsPerVariant)
+  limitTests: number,         // default: null - unlimited
+  // Maximum total runtime of testVariants
+  limitTime: number,          // default: null - unlimited, (milliseconds)
+  // Test terminates when min(completedCount) across sequential modes (forward/backward) >= cycles
+  // Random mode is excluded from this calculation - it is limited only by global limits
+  // (limitTests, limitTime) or when no valid variants exist within current constraints
+  // Until termination conditions are met, iteration modes switch in a circle
+  // If all modes executed zero tests in their last round, the cycle terminates (stuck)
+  cycles: 3,                  // default: 1
+
+  // Iteration modes (variant traversal), default: forward
+  // All modes preserve their current positions between mode switches,
+  // so with multiple executions, they will eventually traverse all variants
+  // When traversal reaches the last variant and no termination conditions are met,
+  // traversal starts over
+  iterationModes: [
+    {
+      // Lexicographic traversal of variants (like numeric counting)
+      // from first (the very last argument in template)
+      // to last (the very first argument in template) or until limits reached
+      mode: 'forward',
+      // number of tests for each variant before moving to the next variant
+      attemptsPerVariant: number, // default: 1
+      // maximum number of attempted full passes of all variants, before mode switch
+      cycles: number,             // default: 1
+      // maximum runtime before mode switch
+      limitTime: number,          // default: null - unlimited, (milliseconds)
+      // maximum number of tests run before mode switch (including attemptsPerVariant)
+      limitTests: number,         // default: null - unlimited
+    },
+    {
+      // Lexicographic traversal of variants in reverse order
+      // from the last possible or from current constraint to the first variant
+      // Same parameters as for 'forward'
+      mode: 'backward',
+      cycles: number,
+      attemptsPerVariant: number,
+      limitTime: number,
+      limitTests: number,
+    },
+    {
+      // Random traversal of variants within current constraints
+      mode: 'random',
+      limitTime: 10000,
+      limitTests: 1000,
+    },
+  ],
+
+  // Iteration modes are best used in tandem with best error search
+  // Best error is the error that occurred on the lexicographically smallest variant
+  // Ideally the best error will be a variant with all argument values
+  // equal to the first value in the template
+  // Search is performed by repeated iteration and introducing new constraints
+  // when an error is found, thus the number of variants constantly decreases,
+  // and tests run faster
+  findBestError: {
+    equals: (a, b) => boolean,
+    // Extra per-arg constraint (does NOT replace lexicographic, both apply):
+    // each arg[i] <= errorArg[i]
+    limitArgOnError: boolean | Function,  // default: false
+    limitArgOnError: true,                // rule applies to all arguments
+    // Custom rule, whether to limit argument value
+    limitArgOnError: ({
+      name,          // argument name
+      values,        // all possible argument values in template
+      maxValueIndex, // current max value index limit for this arg; null if no limit
+    }) => boolean,
+    // the following is equivalent to limitArgOnError: true
+    limitArgOnError: () => true,
+
+    // Option intended only for system verification
+    // If true, iteration will include the last error variant
+    includeErrorVariant: boolean, // default: false
+
+    // If true, when testVariants completes, if an error was found,
+    // no exception will be thrown, instead
+    // all error info will be returned in the result
+    dontThrowIfError: boolean, // default: false
+  },
+
+  // Seed generation for pseudo-random generator
+  // Seed will be set in test parameters as seed field, even if it's null or undefined
+  // This seed will be used for exact reproduction of pseudo-random behavior inside the test
+  getSeed: ({ // default: null - seed disabled, not set in test arguments
+    // total number of tests run
+    tests,
+  }) => any,
+  getSeed: () => Math.random() * 0xFFFFFFFF, // example - random numeric seed
+
+  // Saving error variants to files for subsequent checks
+  // or continuing best error search
+  // Before iterating all variants, saved variants from files will be checked first
+  // in descending order of their save date (newest first)
+  saveErrorVariants: {
+    dir: './error-variants',
+    // Maximum number of checks for each saved variant
+    // Useful when error doesn't reproduce on first try
+    // due to factors independent of parameters or random generator
+    // If error is found, exception is thrown by default and testVariants terminates
+    attemptsPerVariant: 1, // default: 1
+    // Custom file path generation for saving variant
+    // Either relative to dir folder, or absolute path
+    // default: 2025-12-30_12-34-37_vw3h626wg7m.json
+    getFilePath: ({ sessionDate }) => string | null,
+    // Custom serialization, in case arguments are class instances
+    argsToJson: (args) => string | SavedArgs,
+    // Custom deserialization
+    jsonToArgs: (json) => Args,
+    // If true and findBestError is enabled, all files are checked,
+    // all errors from them are collected and used as initial constraints for findBestError
+    // Useful when you need to continue best error search after testVariants restart
+    useToFindBestError: false,
+  },
+
+  // Called when an error occurs in the test
+  // before logging and throwing exception
+  onError: ({
+    error,  // the error caught via try..catch
+    args,   // test parameters that caused the error
+    tests,  // number of tests run before the error (including attemptsPerVariant)
+  }) => void | Promise<void>,
+
+  // Called when iteration mode changes
+  // Invoked at test start and when switching to next mode
+  onModeChange: ({
+    mode,      // current mode configuration (ModeConfig)
+    modeIndex, // current mode index in iterationModes array
+    tests,     // number of tests run before this mode change
+  }) => void | Promise<void>,
+
+  // Time controller for all internal delays, timeouts and getting current time
+  // Used inside testVariants instead of direct setTimeout, Date.now calls, etc
+  // Intended only for testing and debugging the test-variants library itself
+  timeController: ITimeController, // default: null - use timeControllerDefault
 })
-const count = await testVariants({
-    a: [1, 2],
-    b: ['3', '4'],
-    c: [true, false],
-})() // no extra parameters
+
+// Result:
+{
+  iterations: number,
+  // Best error found during testing; set when findBestError is enabled and an error occurred
+  // If dontThrowIfError is true, error is returned here instead of thrown
+  bestError: null | {
+    error: any, // the error caught via try..catch
+    args: { // test parameters that caused the error
+      arg1: Type1,
+      arg2: Type2,
+      arg3: Type3,
+      seed?: number | null,
+    },
+    tests: number, // number of tests run before the error (including attemptsPerVariant)
+  },
+}
 ```
 
-## Calculable variants
-```ts
-const result = []
-const testVariants = createTestVariants(async ({a, b, c}: { a: number, b: number, c: number }) => {
-  await delay(10)
-  result.push([a, b, c])
-})
-const count = await testVariants({
-    a: [1, 2],
-    b: ({a}) => [ a + 1, a + 2 ], // you can use 'a', but you can't use 'c' because it will initialize after 'b' 
-    c: ({a, b}) => [ a, b, a + b ],
-})()
+### Debug mode
+
+When a test error occurs, the library automatically triggers JavaScript's `debugger` statement.
+If you're running tests with a JS debugger attached:
+
+1. Execution pauses at the `debugger` statement in the error handler
+2. Set breakpoints in your test code where you want to investigate
+3. Resume execution - if resuming took more than 50ms (meaning you were stepping through), the same failing variant will repeat
+4. The variant repeats up to 5 times, allowing step-by-step debugging of the exact failing case
+5. After 5 debug iterations or if you resume quickly (<50ms), the error is thrown normally
+
+This enables debugging the exact parameter combination that caused the failure without manually recreating it.
+
+### Sync mode optimization
+
+The internal implementation operates in a faster synchronous mode (without await and Promise) when the test function is synchronous. The library detects whether each test invocation returns a Promise and switches to async handling only when necessary. This maximizes performance for sync tests while fully supporting async tests when needed.
+
+### Logs format
+```
+[test-variants] start, memory: 139MB
+[test-variants] mode[0]: random
+[test-variants] cycle: 3, variant: 65 (1.0s), tests: 615 (5.0s), async: 12, memory: 148MB (+8.8MB)
+[test-variants] mode[1]: backward, limitTests=10
+[test-variants] cycle: 5, variant: 65/100 (2.0s), tests: 615 (6.0s), async: 123, memory: 139MB (-8.8MB)
+[test-variants] mode[2]: forward, limitTests=100, limitTime=10.9m
+[test-variants] end, tests: 815 (7.0s), async: 123, memory: 138MB (-1.0MB)
+...
 ```
 
 # License

package/build/browser/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("../createTestVariants-CpzwjKTs.js");exports.createTestVariants=e.createTestVariants;

package/build/browser/index.d.ts

@@ -0,0 +1 @@
+export * from '../common';

package/build/browser/index.mjs

@@ -0,0 +1,4 @@
+import { c as r } from "../createTestVariants-BL9wiuRD.mjs";
+export {
+  r as createTestVariants
+};

package/build/common/-test/freezeProps.d.ts

@@ -0,0 +1,2 @@
+import { Obj } from '@flemist/simple-utils';
+export declare function freezeProps<T extends Obj>(obj: T, ...props: (keyof T)[]): T;

package/build/common/garbage-collect/garbageCollect.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Wait for garbage collection and return 0.
+ * It may be required for very long calculations.
+ */
+export declare function garbageCollect(iterations: number): Promise<number>;

package/build/common/helpers/log.d.ts

@@ -0,0 +1,5 @@
+export declare function formatValue(value: unknown): string;
+export declare function formatObject(obj: unknown): string;
+export declare function log(...args: unknown[]): void;
+export declare function getLogLast(): string;
+export declare function resetLog(): void;

package/build/common/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("../createTestVariants-CpzwjKTs.js");exports.createTestVariants=e.createTestVariants;

package/build/common/index.d.ts

@@ -0,0 +1,2 @@
+export { type ErrorEvent, type GenerateErrorVariantFilePathOptions, type GetSeedParams, type LimitArgOnError, type LimitArgOnErrorOptions, type ModeChangeEvent, type ModeConfig, type OnErrorCallback, type OnModeChangeCallback, type ParallelOptions, type SaveErrorVariantsOptions, type TestVariantsBestError, type FindBestErrorOptions, type TestVariantsLogOptions, type TestVariantsRunOptions, type TestVariantsResult, type TestOptions, type TestVariantsTestResult, } from './test-variants/types';
+export { createTestVariants } from './test-variants/createTestVariants';

package/build/common/index.mjs

@@ -0,0 +1,4 @@
+import { c as r } from "../createTestVariants-BL9wiuRD.mjs";
+export {
+  r as createTestVariants
+};

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

@@ -0,0 +1 @@
+export declare function getArgKey(index: number): string;

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

@@ -0,0 +1,8 @@
+import { ModeConfig } from '../..';
+export declare const PARALLEL_MAX = 10;
+export declare const TIME_MAX = 10;
+export declare const LIMIT_MAX = 10000;
+export declare const LIMIT_RANDOM_MODE_DEFAULT = 10;
+export declare const ITERATIONS_SYNC = 10;
+export declare const ITERATIONS_ASYNC = 1000000;
+export declare const MODES_DEFAULT: readonly ModeConfig[];

package/build/common/test-variants/-test/estimations/estimateCallCount.d.ts

@@ -0,0 +1,4 @@
+import { TestVariantsRunOptions } from '../../..';
+import { NumberRange } from '@flemist/simple-utils';
+import { StressTestArgs, TestArgs } from '../types';
+export declare function estimateCallCount(options: StressTestArgs, runOptions: TestVariantsRunOptions<TestArgs>, variantsCount: number, errorVariantIndex: number | null, withDelay: boolean): NumberRange;

package/build/common/test-variants/-test/estimations/estimateModeChanges.d.ts

@@ -0,0 +1,4 @@
+import { TestVariantsRunOptions } from '../../..';
+import { NumberRange } from '@flemist/simple-utils';
+import { StressTestArgs, TestArgs } from '../types';
+export declare function estimateModeChanges(options: StressTestArgs, runOptions: TestVariantsRunOptions<TestArgs>, variantsCount: number, errorVariantIndex: number | null, withDelay: boolean, callCountRange: NumberRange): NumberRange;

package/build/common/test-variants/-test/generators/findBestError.d.ts

@@ -0,0 +1,4 @@
+import { Random } from '@flemist/simple-utils';
+import { StressTestArgs, Template } from '../types';
+import { FindBestErrorOptions } from '../../..';
+export declare function generateFindBestErrorOptions(rnd: Random, options: StressTestArgs, template: Template, argKeys: readonly string[]): FindBestErrorOptions | undefined;

package/build/common/test-variants/-test/generators/primitives.d.ts

@@ -0,0 +1,16 @@
+import { Random } from '@flemist/simple-utils';
+import { StressTestArgs } from '../types';
+export declare function generateBoolean(rnd: Random, booleanOption: boolean | null): boolean;
+/**
+ * Generate integer with boundary values priority:
+ * 0, 1, 2, 3 - if max = 3
+ * 0, 1, 2, max, [3..max-1] - if max >= 4 and isMaxBoundary is true
+ * 0, 1, 2, [3..max] - if max >= 4 and isMaxBoundary is false
+ */
+export declare function generateBoundaryInt(rnd: Random, max: number, isMaxBoundary?: null | boolean): number;
+/**
+ * Generate limit value with priority: 0, 1, max-1, max, max+1, [2..max-2]
+ */
+export declare function generateLimit(rnd: Random, max: number): number;
+export declare function equals(a: unknown, b: unknown): boolean;
+export declare function generateEquals(rnd: Random, options: StressTestArgs): ((a: unknown, b: unknown) => boolean) | undefined;

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

@@ -0,0 +1,9 @@
+import { Random } from '@flemist/simple-utils';
+import { ModeChangeEvent, TestVariantsRunOptions } from '../../..';
+import { StressTestArgs, Template, TestArgs } from '../types';
+import { TestVariantsLogType } from '../../types';
+export declare function generateRunOptions(rnd: Random, options: StressTestArgs, template: Template, argKeys: readonly string[], variantsCount: number, logFunc: (type: TestVariantsLogType, message: string) => void, onError: (event: {
+    error: unknown;
+    args: TestArgs;
+    tests: number;
+}) => void, onModeChange: (event: ModeChangeEvent) => void): TestVariantsRunOptions<TestArgs>;

package/build/common/test-variants/-test/generators/template.d.ts

@@ -0,0 +1,3 @@
+import { Random } from '@flemist/simple-utils';
+import { StressTestArgs, Template } from '../types';
+export declare function generateTemplate(rnd: Random, options: StressTestArgs): Template;

package/build/common/test-variants/-test/generators/testFunc.d.ts

@@ -0,0 +1,3 @@
+import { Random } from '@flemist/simple-utils';
+import { StressTestArgs } from '../types';
+export declare function generateErrorVariantIndex(rnd: Random, options: StressTestArgs, variantsCount: number): number | null;

package/build/common/test-variants/-test/helpers/CallController.d.ts

@@ -0,0 +1,28 @@
+import { IAbortSignalFast } from '@flemist/abort-controller-fast';
+import { TimeControllerMock } from '@flemist/time-controller';
+import { PromiseOrValue } from '@flemist/async-utils';
+import { TestFuncResult } from '../../run/types';
+/**
+ * Emulates test function call with sync/async behavior
+ * Counts number of calls
+ */
+export declare class CallController {
+    private _callCount;
+    private _completedCount;
+    private _currentConcurrent;
+    private _maxConcurrent;
+    private readonly _isAsync;
+    private readonly _withDelay;
+    private readonly _abortController;
+    private readonly _timeController;
+    constructor(isAsync: boolean | null, withDelay: boolean);
+    /** Use inside test func */
+    call(start: () => void, end: () => void): PromiseOrValue<TestFuncResult>;
+    get callCount(): number;
+    get completedCount(): number;
+    get currentConcurrent(): number;
+    get maxConcurrent(): number;
+    get abortSignal(): IAbortSignalFast;
+    get timeController(): TimeControllerMock;
+    finalize(): void;
+}

package/build/common/test-variants/-test/helpers/ErrorVariantController.d.ts

@@ -0,0 +1,17 @@
+import { TestArgs } from '../types';
+import { TestError } from './TestError';
+/**
+ * Emulates error thrown for error variant after N retries
+ */
+export declare class ErrorVariantController {
+    private _retries;
+    private _lastThrownError;
+    private readonly _errorVariantArgs;
+    private readonly _retriesToError;
+    private _nextErrorId;
+    constructor(errorVariantArgs: TestArgs | null | undefined, retriesToError: number);
+    /** Use inside test func */
+    onCall(args: TestArgs): void;
+    get lastThrownError(): TestError | null;
+    get errorVariantArgs(): TestArgs | null;
+}

package/build/common/test-variants/-test/helpers/TestError.d.ts

@@ -0,0 +1,2 @@
+export declare class TestError extends Error {
+}

package/build/common/test-variants/-test/helpers/deepEqualJsonLikeWithoutSeed.d.ts

@@ -0,0 +1 @@
+export declare function deepEqualJsonLikeWithoutSeed(a: any, b: any): boolean;

package/build/common/test-variants/-test/helpers/deepFreezeJsonLike.d.ts

@@ -0,0 +1 @@
+export declare function deepFreezeJsonLike(value: unknown): void;

package/build/common/test-variants/-test/helpers/forEachVariant.d.ts

@@ -0,0 +1,4 @@
+import { Template, TestArgs } from '../types';
+/** @return true to break */
+export type ForEachVariantCallback = (args: TestArgs, index: number) => boolean | null | undefined | void;
+export declare function forEachVariant(template: Template, argKeys: string[], callback?: null | ForEachVariantCallback): number;

package/build/common/test-variants/-test/helpers/getMaxAttemptsPerVariant.d.ts

@@ -0,0 +1,2 @@
+import { ModeConfig } from '../../..';
+export declare function getMaxAttemptsPerVariant(modes: readonly ModeConfig[]): number;

package/build/common/test-variants/-test/helpers/getParallelLimit.d.ts

@@ -0,0 +1,7 @@
+import { ParallelOptions } from '../../types';
+/**
+ * Extracts actual parallel limit from parallel option
+ *
+ * @returns 1 for sequential, Infinity for unlimited, or the specified count
+ */
+export declare function getParallelLimit(parallel: number | boolean | ParallelOptions | null | undefined): number;

package/build/common/test-variants/-test/helpers/getVariantArgs.d.ts

@@ -0,0 +1,12 @@
+import { Template, TestArgs } from '../types';
+export type Variant = {
+    index: number;
+    args: TestArgs;
+};
+export type Variants = {
+    first: null | Variant;
+    middle: null | Variant;
+    last: null | Variant;
+    error: null | Variant;
+};
+export declare function getVariantArgs(template: Template, argKeys: string[], variantsCount: number, errorIndex: number | null): Variants;

package/build/common/test-variants/-test/helpers/runWithTimeController.d.ts

@@ -0,0 +1,7 @@
+import { TimeControllerMock } from '@flemist/time-controller';
+import { TestError } from './TestError';
+export type AwaitResult<T> = {
+    result: T | null;
+    caughtError: TestError | null;
+};
+export declare function runWithTimeController<T>(timeController: TimeControllerMock, func: () => T | Promise<T>): Promise<AwaitResult<T>>;

package/build/common/test-variants/-test/invariants/CallCountInvariant.d.ts

@@ -0,0 +1,18 @@
+import { NumberRange } from '@flemist/simple-utils';
+/**
+ * Validates call count bounds
+ *
+ * ## Applicability
+ * - Every test function call
+ *
+ * ## Invariants
+ * - callCount never exceeds callCountRange
+ */
+export declare class CallCountInvariant {
+    private readonly _callCountRange;
+    constructor(callCountRange: NumberRange);
+    /** Use inside test func */
+    onCall(callCount: number): void;
+    /** Run after test variants completion */
+    validateFinal(callCount: number): void;
+}

package/build/common/test-variants/-test/invariants/CallOptionsInvariant.d.ts

@@ -0,0 +1,32 @@
+import { IAbortSignalFast } from '@flemist/abort-controller-fast';
+import { ITimeController } from '@flemist/time-controller';
+import { CallController } from '../helpers/CallController';
+/**
+ * Validates TestOptions passed to test function
+ *
+ * ## Applicability
+ * Every test function call
+ *
+ * ## Invariants
+ * - abortSignal exists and is not null
+ * - timeController matches expected instance
+ * - abortSignal not aborted on first call
+ * - abortSignal aborted after CallController.finalize (combined signal depends on internal signal)
+ *
+ * ## Skipped Validations
+ * - abortSignal identity (library combines signals via combineAbortSignals)
+ * - abortSignal.aborted state during execution (depends on errors and sequentialOnError)
+ */
+export declare class CallOptionsInvariant {
+    private readonly _timeController;
+    private readonly _callController;
+    private _lastAbortSignal;
+    constructor(timeController: ITimeController, callController: CallController);
+    /** Use inside test func */
+    onCall(callOptions: {
+        abortSignal?: IAbortSignalFast;
+        timeController?: ITimeController;
+    }): void;
+    /** Run after test variants completion */
+    validateFinal(): void;
+}