@plyaz/types 1.3.2 → 1.3.3

package/dist/testing/features/feature-flags/types.d.ts

@@ -0,0 +1,1133 @@
+/**
+ * @fileoverview Feature Flag Testing Types
+ *
+ * Comprehensive type definitions for testing feature flag functionality across
+ * different providers, evaluation strategies, and contexts. Provides type safety
+ * for feature flag test scenarios, mocking, and validation.
+ *
+ * This module includes types for:
+ * - Feature flag builders and factories
+ * - Mock feature flag providers
+ * - Feature flag test scenarios and assertions
+ * - Context and evaluation testing
+ * - Integration with React components and hooks
+ * - Provider switching and configuration testing
+ *
+ * @example
+ * ```typescript
+ * import type {
+ *   FeatureFlagBuilder,
+ *   MockFeatureFlagProvider,
+ *   FeatureFlagTestScenario
+ * } from './types';
+ *
+ * // Build test feature flags
+ * const flag = featureFlagBuilder
+ *   .withKey('new-checkout')
+ *   .withValue(true)
+ *   .withContext({ userId: '123' })
+ *   .build();
+ *
+ * // Mock provider for testing
+ * const mockProvider: MockFeatureFlagProvider = createMockProvider();
+ * mockProvider.get.mockResolvedValue(true);
+ *
+ * // Test scenarios
+ * const scenario: FeatureFlagTestScenario = {
+ *   name: 'Checkout flag enabled',
+ *   flags: { 'new-checkout': true },
+ *   expectedBehavior: () => expect(checkoutButton).toBeVisible()
+ * };
+ * ```
+ *
+ * @module FeatureFlagTestingTypes
+ * @since 1.0.0
+ */
+import type * as Vitest from 'vitest';
+import type * as React from 'react';
+import type { FeatureFlag, FeatureFlagCondition, FeatureFlagConfig, FeatureFlagContext, FeatureFlagEvaluation, FeatureFlagRule, FeatureFlagValue, FeatureFlagProvider as IFeatureFlagProvider, FeatureFlagContextValue } from '../../../features';
+import type { MockLogger, RenderFunction, RenderHookFunction } from '../../common';
+/**
+ * Builder interface for creating feature flag test objects with fluent API
+ *
+ * @example
+ * ```typescript
+ * const flag = featureFlagBuilder
+ *   .withKey('new-checkout')
+ *   .withValue(true)
+ *   .withEnabled(true)
+ *   .withRolloutPercentage(50)
+ *   .withCondition({ field: 'userId', operator: 'in', value: ['user1', 'user2'] })
+ *   .build();
+ * ```
+ */
+export interface FeatureFlagBuilder<FeatureFlagKey extends string> {
+    /** Set the feature flag key */
+    withKey: (key: FeatureFlagKey) => FeatureFlagBuilder<FeatureFlagKey>;
+    /** Set the feature flag value */
+    withValue: (value: FeatureFlagValue) => FeatureFlagBuilder<FeatureFlagKey>;
+    /** Set whether the flag is enabled */
+    withEnabled: (enabled: boolean) => FeatureFlagBuilder<FeatureFlagKey>;
+    /** Set the flag description */
+    withDescription: (description: string) => FeatureFlagBuilder<FeatureFlagKey>;
+    /** Set the rollout percentage (0-100) */
+    withRolloutPercentage: (percentage: number) => FeatureFlagBuilder<FeatureFlagKey>;
+    /** Add a single condition */
+    withCondition: (condition: FeatureFlagCondition) => FeatureFlagBuilder<FeatureFlagKey>;
+    /** Set multiple conditions */
+    withConditions: (conditions: FeatureFlagCondition[]) => FeatureFlagBuilder<FeatureFlagKey>;
+    /** Set the creation date */
+    withCreatedAt: (date: Date) => FeatureFlagBuilder<FeatureFlagKey>;
+    /** Set the last update date */
+    withUpdatedAt: (date: Date) => FeatureFlagBuilder<FeatureFlagKey>;
+    /** Build the final feature flag object */
+    build: () => FeatureFlag<FeatureFlagKey>;
+}
+/**
+ * Mock objects for feature flag module testing
+ *
+ * @example
+ * ```typescript
+ * const mocks: SetupFeatureFlagModuleMocks = {
+ *   mockLogger: createMockLogger(),
+ *   HttpException: vi.fn(),
+ *   HttpStatus: { OK: 200, NOT_FOUND: 404, INTERNAL_SERVER_ERROR: 500 }
+ * };
+ * ```
+ */
+export interface SetupFeatureFlagModuleMocks {
+    /** Mock logger instance */
+    mockLogger: MockLogger;
+    /** Mock HTTP exception constructor */
+    HttpException: Vitest.Mock;
+    /** HTTP status code constants */
+    HttpStatus: Record<string, number>;
+}
+/**
+ * Builder interface for creating feature flag context objects
+ *
+ * @example
+ * ```typescript
+ * const context = contextBuilder
+ *   .withUserId('user-123')
+ *   .withEnvironment('production')
+ *   .withCountry('US')
+ *   .withCustom({ tier: 'premium', beta: true })
+ *   .build();
+ * ```
+ */
+export interface FeatureFlagContextBuilder {
+    /** Set the user identifier */
+    withUserId: (userId: string) => FeatureFlagContextBuilder;
+    /** Set the group identifier */
+    withGroupId: (groupId: string) => FeatureFlagContextBuilder;
+    /** Set the environment (dev, staging, prod) */
+    withEnvironment: (environment: string) => FeatureFlagContextBuilder;
+    /** Set the user's country */
+    withCountry: (country: string) => FeatureFlagContextBuilder;
+    /** Set the user's language */
+    withLanguage: (language: string) => FeatureFlagContextBuilder;
+    /** Set the platform (web, mobile, api) */
+    withPlatform: (platform: string) => FeatureFlagContextBuilder;
+    /** Set the application version */
+    withVersion: (version: string) => FeatureFlagContextBuilder;
+    /** Set custom context properties */
+    withCustom: (custom: Record<string, unknown>) => FeatureFlagContextBuilder;
+    /** Build the final context object */
+    build: () => FeatureFlagContext;
+}
+/**
+ * Builder interface for creating feature flag condition objects
+ *
+ * @example
+ * ```typescript
+ * const condition = conditionBuilder
+ *   .withField('userId')
+ *   .withOperator('in')
+ *   .withValue(['user1', 'user2', 'user3'])
+ *   .build();
+ * ```
+ */
+export interface FeatureFlagConditionBuilder {
+    /** Set the field to evaluate */
+    withField: (field: FeatureFlagCondition['field']) => FeatureFlagConditionBuilder;
+    /** Set the comparison operator */
+    withOperator: (operator: FeatureFlagCondition['operator']) => FeatureFlagConditionBuilder;
+    /** Set the comparison value(s) */
+    withValue: (value: string | number | string[] | number[]) => FeatureFlagConditionBuilder;
+    /** Build the final condition object */
+    build: () => FeatureFlagCondition;
+}
+/**
+ * Factory interface for creating various types of feature flag test objects
+ *
+ * @example
+ * ```typescript
+ * const factory: FeatureFlagFactory = createFeatureFlagFactory();
+ *
+ * // Create basic flag
+ * const flag = factory.create({ key: 'my-flag', enabled: true });
+ *
+ * // Create rollout flag
+ * const rolloutFlag = factory.createWithRollout(25, { key: 'gradual-rollout' });
+ *
+ * // Create typed flags
+ * const boolFlag = factory.createBoolean('feature-enabled', true);
+ * const stringFlag = factory.createString('theme', 'dark');
+ * ```
+ */
+export interface FeatureFlagFactory<FeatureFlagKey extends string> {
+    /** Create a basic feature flag */
+    create: (overrides?: Partial<FeatureFlag<FeatureFlagKey>>) => FeatureFlag<FeatureFlagKey>;
+    /** Create multiple feature flags */
+    createList: (count: number, overrides?: Partial<FeatureFlag<FeatureFlagKey>>) => FeatureFlag<FeatureFlagKey>[];
+    /** Create an enabled feature flag */
+    createEnabled: (overrides?: Partial<FeatureFlag<FeatureFlagKey>>) => FeatureFlag<FeatureFlagKey>;
+    /** Create a disabled feature flag */
+    createDisabled: (overrides?: Partial<FeatureFlag<FeatureFlagKey>>) => FeatureFlag<FeatureFlagKey>;
+    /** Create a feature flag with rollout percentage */
+    createWithRollout: (percentage: number, overrides?: Partial<FeatureFlag<FeatureFlagKey>>) => FeatureFlag<FeatureFlagKey>;
+    /** Create a feature flag with conditions */
+    createWithConditions: (conditions: FeatureFlagCondition[], overrides?: Partial<FeatureFlag<FeatureFlagKey>>) => FeatureFlag<FeatureFlagKey>;
+    /** Create a boolean feature flag */
+    createBoolean: (key: string, value: boolean, overrides?: Partial<FeatureFlag<FeatureFlagKey>>) => FeatureFlag<FeatureFlagKey>;
+    /** Create a string feature flag */
+    createString: (key: string, value: string, overrides?: Partial<FeatureFlag<FeatureFlagKey>>) => FeatureFlag<FeatureFlagKey>;
+    /** Create a number feature flag */
+    createNumber: (key: string, value: number, overrides?: Partial<FeatureFlag<FeatureFlagKey>>) => FeatureFlag<FeatureFlagKey>;
+    /** Create an object feature flag */
+    createObject: (key: string, value: Record<string, unknown>, overrides?: Partial<FeatureFlag<FeatureFlagKey>>) => FeatureFlag<FeatureFlagKey>;
+}
+/**
+ * Pre-defined feature flag scenario generators for common testing patterns
+ *
+ * @example
+ * ```typescript
+ * const scenarios: FeatureFlagScenarios = createFeatureFlagScenarios();
+ *
+ * // Get basic enabled/disabled flags
+ * const basicFlags = scenarios.basic();
+ *
+ * // Get flags with rollout percentages
+ * const rolloutFlags = scenarios.rollout();
+ *
+ * // Get flags with complex conditions
+ * const conditionalFlags = scenarios.conditional();
+ * ```
+ */
+export interface FeatureFlagScenarios<FeatureFlagKey extends string> {
+    /** Generate basic enabled/disabled flags */
+    basic: () => FeatureFlag<FeatureFlagKey>[];
+    /** Generate flags with rollout percentages */
+    rollout: () => FeatureFlag<FeatureFlagKey>[];
+    /** Generate flags with conditions */
+    conditional: () => FeatureFlag<FeatureFlagKey>[];
+    /** Generate flags with multiple variants */
+    multiVariant: () => FeatureFlag<FeatureFlagKey>[];
+    /** Generate flags targeting specific users */
+    userTargeting: () => FeatureFlag<FeatureFlagKey>[];
+    /** Generate flags targeting user groups */
+    groupTargeting: () => FeatureFlag<FeatureFlagKey>[];
+    /** Generate flags targeting environments */
+    environmentTargeting: () => FeatureFlag<FeatureFlagKey>[];
+    /** Generate mixed scenario flags */
+    mixed: () => FeatureFlag<FeatureFlagKey>[];
+}
+/**
+ * Mock feature flag provider interface for testing provider interactions
+ *
+ * @example
+ * ```typescript
+ * const mockProvider: MockFeatureFlagProvider = {
+ *   getFlag: vi.fn().mockResolvedValue(mockFlag),
+ *   getAllFlags: vi.fn().mockResolvedValue([mockFlag1, mockFlag2]),
+ *   evaluateFlag: vi.fn().mockResolvedValue({ value: true, reason: 'enabled' }),
+ *   isEnabled: vi.fn().mockResolvedValue(true),
+ *   getValue: vi.fn().mockResolvedValue('default-value'),
+ *   // ... other methods
+ * };
+ * ```
+ */
+export interface MockFeatureFlagProvider {
+    /** Get a specific feature flag */
+    getFlag: Vitest.Mock;
+    /** Get all feature flags */
+    getAllFlags: Vitest.Mock;
+    /** Evaluate a feature flag */
+    evaluateFlag: Vitest.Mock;
+    /** Check if a flag is enabled */
+    isEnabled: Vitest.Mock;
+    /** Get a flag's value */
+    getValue: Vitest.Mock;
+    /** Update a feature flag */
+    updateFlag: Vitest.Mock;
+    /** Delete a feature flag */
+    deleteFlag: Vitest.Mock;
+    /** Refresh flag data */
+    refresh: Vitest.Mock;
+    /** Subscribe to flag changes */
+    subscribe: Vitest.Mock;
+    /** Unsubscribe from flag changes */
+    unsubscribe: Vitest.Mock;
+}
+/**
+ * Mock feature flag repository interface for database operations testing
+ *
+ * @example
+ * ```typescript
+ * const mockRepository: MockFeatureFlagRepository = {
+ *   find: vi.fn().mockResolvedValue(mockFlag),
+ *   findAll: vi.fn().mockResolvedValue([mockFlag1, mockFlag2]),
+ *   create: vi.fn().mockResolvedValue(newMockFlag),
+ *   update: vi.fn().mockResolvedValue(updatedMockFlag),
+ *   delete: vi.fn().mockResolvedValue(true),
+ *   save: vi.fn().mockResolvedValue(savedMockFlag),
+ *   exists: vi.fn().mockResolvedValue(true),
+ *   count: vi.fn().mockResolvedValue(5)
+ * };
+ * ```
+ */
+export interface MockFeatureFlagRepository {
+    /** Find a single flag by criteria */
+    find: Vitest.Mock;
+    /** Find all flags */
+    findAll: Vitest.Mock;
+    /** Create a new flag */
+    create: Vitest.Mock;
+    /** Update an existing flag */
+    update: Vitest.Mock;
+    /** Delete a flag */
+    delete: Vitest.Mock;
+    /** Save a flag */
+    save: Vitest.Mock;
+    /** Check if a flag exists */
+    exists: Vitest.Mock;
+    /** Count total flags */
+    count: Vitest.Mock;
+}
+/**
+ * Mock feature flag service interface for business logic testing
+ *
+ * @example
+ * ```typescript
+ * const mockService: MockFeatureFlagService = {
+ *   evaluate: vi.fn().mockResolvedValue({ value: true, reason: 'enabled' }),
+ *   evaluateAll: vi.fn().mockResolvedValue(evaluationResults),
+ *   isEnabled: vi.fn().mockResolvedValue(true),
+ *   getValue: vi.fn().mockResolvedValue('variant-a'),
+ *   getVariation: vi.fn().mockResolvedValue('control'),
+ *   track: vi.fn().mockResolvedValue(undefined),
+ *   refresh: vi.fn().mockResolvedValue(undefined),
+ *   invalidateCache: vi.fn().mockResolvedValue(undefined)
+ * };
+ * ```
+ */
+export interface MockFeatureFlagService {
+    /** Evaluate a single flag */
+    evaluate: Vitest.Mock;
+    /** Evaluate all flags */
+    evaluateAll: Vitest.Mock;
+    /** Check if flag is enabled */
+    isEnabled: Vitest.Mock;
+    /** Get flag value */
+    getValue: Vitest.Mock;
+    /** Get flag variation */
+    getVariation: Vitest.Mock;
+    /** Track flag usage */
+    track: Vitest.Mock;
+    /** Refresh flag data */
+    refresh: Vitest.Mock;
+    /** Clear cache */
+    invalidateCache: Vitest.Mock;
+}
+/**
+ * Mock feature flag evaluation engine interface for testing flag logic
+ *
+ * @example
+ * ```typescript
+ * const mockEngine: MockFeatureFlagEngine = {
+ *   evaluate: vi.fn().mockReturnValue({ value: true, reason: 'match' }),
+ *   evaluateConditions: vi.fn().mockReturnValue(true),
+ *   checkRollout: vi.fn().mockReturnValue(true),
+ *   calculateVariation: vi.fn().mockReturnValue('variant-b'),
+ *   getDefaultValue: vi.fn().mockReturnValue(false)
+ * };
+ * ```
+ */
+export interface MockFeatureFlagEngine {
+    /** Evaluate flag with context */
+    evaluate: Vitest.Mock;
+    /** Evaluate conditions */
+    evaluateConditions: Vitest.Mock;
+    /** Check rollout eligibility */
+    checkRollout: Vitest.Mock;
+    /** Calculate variation */
+    calculateVariation: Vitest.Mock;
+    /** Get default value */
+    getDefaultValue: Vitest.Mock;
+}
+/**
+ * Mock feature flag cache interface for testing caching behavior
+ *
+ * @example
+ * ```typescript
+ * const mockCache: MockFeatureFlagCache = {
+ *   get: vi.fn().mockResolvedValue(cachedFlag),
+ *   set: vi.fn().mockResolvedValue(undefined),
+ *   delete: vi.fn().mockResolvedValue(true),
+ *   clear: vi.fn().mockResolvedValue(undefined),
+ *   has: vi.fn().mockResolvedValue(true),
+ *   keys: vi.fn().mockResolvedValue(['flag1', 'flag2']),
+ *   values: vi.fn().mockResolvedValue([flag1, flag2]),
+ *   size: vi.fn().mockResolvedValue(10)
+ * };
+ * ```
+ */
+export interface MockFeatureFlagCache {
+    /** Get cached value */
+    get: Vitest.Mock;
+    /** Set cache value */
+    set: Vitest.Mock;
+    /** Delete cached value */
+    delete: Vitest.Mock;
+    /** Clear all cache */
+    clear: Vitest.Mock;
+    /** Check if key exists */
+    has: Vitest.Mock;
+    /** Get all cache keys */
+    keys: Vitest.Mock;
+    /** Get all cache values */
+    values: Vitest.Mock;
+    /** Get cache size */
+    size: Vitest.Mock;
+}
+/**
+ * Test context for feature flag testing with React components
+ *
+ * @example
+ * ```typescript
+ * const testContext: FeatureFlagTestContext = await setupFeatureFlagTest<FeatureFlagKey>({
+ *   flags: [testFlag1, testFlag2],
+ *   context: { userId: 'test-user' }
+ * });
+ *
+ * // Use in component tests
+ * const { getByText } = testContext.render(
+ *   <testContext.wrapper>
+ *     <MyComponent />
+ *   </testContext.wrapper>
+ * );
+ *
+ * // Clean up after test
+ * await testContext.cleanup();
+ * ```
+ */
+export interface FeatureFlagTestContext<FeatureFlagKey extends string> {
+    /** Feature flag provider instance */
+    provider: IFeatureFlagProvider<FeatureFlagKey>;
+    /** Cleanup function for test teardown */
+    cleanup: () => Promise<void>;
+    /** React wrapper component with provider */
+    wrapper: (props: {
+        children: React.ReactNode;
+    }) => React.ReactNode;
+    /** Enhanced render function */
+    render: RenderFunction;
+    /** Enhanced renderHook function */
+    renderHook: RenderHookFunction;
+}
+/**
+ * Options for configuring feature flag tests
+ *
+ * @example
+ * ```typescript
+ * const options: FeatureFlagTestOptions = {
+ *   flags: [enabledFlag, disabledFlag],
+ *   context: { userId: 'test-user', environment: 'test' },
+ *   provider: 'memory',
+ *   cache: false,
+ *   timeout: 5000
+ * };
+ *
+ * const testContext = await setupFeatureFlagTest<FeatureFlagKey>(options);
+ * ```
+ */
+export interface FeatureFlagTestOptions<FeatureFlagKey extends string> {
+    /** Initial flags to load */
+    flags?: FeatureFlag<FeatureFlagKey>[];
+    /** Default evaluation context */
+    context?: FeatureFlagContext;
+    /** Provider type to use */
+    provider?: 'memory' | 'file' | 'database' | 'api' | 'redis';
+    /** Enable caching */
+    cache?: boolean;
+    /** Enable auto-refresh */
+    refresh?: boolean;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Single feature flag test scenario definition
+ *
+ * @example
+ * ```typescript
+ * const scenario: FeatureFlagScenario = {
+ *   name: 'Premium user sees new feature',
+ *   description: 'Premium users should see the new checkout flow',
+ *   flags: [newCheckoutFlag],
+ *   context: { userId: 'premium-user-1', tier: 'premium' },
+ *   expectedResults: {
+ *     'new-checkout': true,
+ *     'old-checkout': false
+ *   },
+ *   setup: async () => {
+ *     await seedTestData();
+ *   },
+ *   teardown: async () => {
+ *     await cleanupTestData();
+ *   }
+ * };
+ * ```
+ */
+export interface FeatureFlagScenario<FeatureFlagKey extends string> {
+    /** Scenario name */
+    name: string;
+    /** Optional scenario description */
+    description?: string;
+    /** Feature flags for this scenario */
+    flags: FeatureFlag<FeatureFlagKey>[];
+    /** Evaluation context */
+    context?: FeatureFlagContext;
+    /** Expected flag evaluation results */
+    expectedResults: Record<string, FeatureFlagValue>;
+    /** Setup function run before scenario */
+    setup?: () => void | Promise<void>;
+    /** Teardown function run after scenario */
+    teardown?: () => void | Promise<void>;
+}
+/**
+ * Test suite for managing and running multiple feature flag scenarios
+ *
+ * @example
+ * ```typescript
+ * const testSuite: FeatureFlagTestSuite = createFeatureFlagTestSuite();
+ *
+ * // Add scenarios
+ * testSuite.addScenario(premiumUserScenario);
+ * testSuite.addScenario(freeUserScenario);
+ *
+ * // Run specific scenario
+ * await testSuite.run('Premium user sees new feature');
+ *
+ * // Run all scenarios
+ * await testSuite.runAll();
+ *
+ * // Clean up
+ * testSuite.clear();
+ * ```
+ */
+export interface FeatureFlagTestSuite<FeatureFlagKey extends string> {
+    /** All scenarios in the suite */
+    scenarios: FeatureFlagScenario<FeatureFlagKey>[];
+    /** Run a specific scenario by name */
+    run: (scenarioName?: string) => Promise<void>;
+    /** Run all scenarios in sequence */
+    runAll: () => Promise<void>;
+    /** Add a new scenario */
+    addScenario: (scenario: FeatureFlagScenario<FeatureFlagKey>) => void;
+    /** Remove a scenario by name */
+    removeScenario: (name: string) => void;
+    /** Clear all scenarios */
+    clear: () => void;
+}
+/**
+ * Custom assertion methods for feature flag testing
+ *
+ * @example
+ * ```typescript
+ * // Custom matchers extend expect
+ * expect(featureFlag).toBeEnabled();
+ * expect(featureFlag).toHaveValue(true);
+ * expect(featureFlag).toHaveRolloutPercentage(25);
+ * expect(featureFlag).toBeEvaluatedAs(true, userContext);
+ * ```
+ */
+export interface FeatureFlagAssertion {
+    /** Assert flag is enabled */
+    toBeEnabled: () => void;
+    /** Assert flag is disabled */
+    toBeDisabled: () => void;
+    /** Assert flag has specific value */
+    toHaveValue: (value: FeatureFlagValue) => void;
+    /** Assert flag has specific rollout percentage */
+    toHaveRolloutPercentage: (percentage: number) => void;
+    /** Assert flag has specific conditions */
+    toHaveConditions: (conditions: FeatureFlagCondition[]) => void;
+    /** Assert flag matches a condition */
+    toMatchCondition: (condition: FeatureFlagCondition) => void;
+    /** Assert flag evaluates to specific value in context */
+    toBeEvaluatedAs: (value: FeatureFlagValue, context?: FeatureFlagContext) => void;
+    /** Assert flag is targeted to specific context */
+    toBeTargetedTo: (context: FeatureFlagContext) => void;
+    /** Assert flag is rolled out to percentage */
+    toBeRolledOutTo: (percentage: number) => void;
+}
+/**
+ * Helper utilities for feature flag testing operations
+ *
+ * @example
+ * ```typescript
+ * const helpers: FeatureFlagHelpers = createFeatureFlagHelpers();
+ *
+ * // Create mocks
+ * const mockProvider = helpers.createProvider({ cache: true });
+ * const mockRepository = helpers.createRepository();
+ *
+ * // Setup scenario
+ * await helpers.setupScenario(testScenario);
+ *
+ * // Evaluate flags
+ * const evaluation = helpers.evaluateFlag(flag, context);
+ * const isEnabled = helpers.evaluateCondition(condition, context);
+ *
+ * // Generate test data
+ * const testContext = helpers.generateContext({ userId: 'test' });
+ * const testFlags = helpers.generateFlags(10);
+ * ```
+ */
+export interface FeatureFlagHelpersMock<FeatureFlagKey extends string> {
+    /** Create mock provider */
+    createProvider: (options?: FeatureFlagTestOptions<FeatureFlagKey>) => MockFeatureFlagProvider;
+    /** Create mock repository */
+    createRepository: () => MockFeatureFlagRepository;
+    /** Create mock service */
+    createService: () => MockFeatureFlagService;
+    /** Create mock engine */
+    createEngine: () => MockFeatureFlagEngine;
+    /** Create mock cache */
+    createCache: () => MockFeatureFlagCache;
+    /** Setup test scenario */
+    setupScenario: (scenario: FeatureFlagScenario<FeatureFlagKey>) => Promise<void>;
+    /** Evaluate flag manually */
+    evaluateFlag: (flag: FeatureFlag<FeatureFlagKey>, context?: FeatureFlagContext) => FeatureFlagEvaluation<FeatureFlagKey>;
+    /** Evaluate condition manually */
+    evaluateCondition: (condition: FeatureFlagCondition, context: FeatureFlagContext) => boolean;
+    /** Calculate rollout eligibility */
+    calculateRollout: (percentage: number, context: FeatureFlagContext) => boolean;
+    /** Generate test context */
+    generateContext: (overrides?: Partial<FeatureFlagContext>) => FeatureFlagContext;
+    /** Generate test flags */
+    generateFlags: (count: number, overrides?: Partial<FeatureFlag<FeatureFlagKey>>) => FeatureFlag<FeatureFlagKey>[];
+}
+/**
+ * Configuration for feature flag testing environment
+ *
+ * @example
+ * ```typescript
+ * const config: FeatureFlagTestConfig = {
+ *   defaultProvider: 'memory',
+ *   defaultTimeout: 5000,
+ *   enableCache: false,
+ *   cacheTimeout: 300000,
+ *   enableLogging: true,
+ *   logLevel: 'warn',
+ *   mockOptions: {
+ *     autoResolve: true,
+ *     defaultEnabled: false,
+ *     defaultValue: false,
+ *     rolloutStrategy: 'deterministic'
+ *   }
+ * };
+ *
+ * setupFeatureFlagTesting(config);
+ * ```
+ */
+export interface FeatureFlagTestConfig {
+    /** Default provider type */
+    defaultProvider: 'memory' | 'file' | 'database' | 'api' | 'redis';
+    /** Default request timeout */
+    defaultTimeout: number;
+    /** Enable caching */
+    enableCache: boolean;
+    /** Cache timeout in milliseconds */
+    cacheTimeout: number;
+    /** Enable logging */
+    enableLogging: boolean;
+    /** Log level */
+    logLevel: 'debug' | 'info' | 'warn' | 'error';
+    /** Mock behavior options */
+    mockOptions: {
+        /** Auto-resolve promises */
+        autoResolve: boolean;
+        /** Default enabled state */
+        defaultEnabled: boolean;
+        /** Default flag value */
+        defaultValue: FeatureFlagValue;
+        /** Rollout calculation strategy */
+        rolloutStrategy: 'random' | 'deterministic';
+    };
+}
+/**
+ * Feature flag event for tracking flag operations and changes
+ *
+ * @example
+ * ```typescript
+ * const event: FeatureFlagEvent = {
+ *   type: 'evaluation',
+ *   flagKey: 'new-checkout',
+ *   context: { userId: 'user-123' },
+ *   value: true,
+ *   timestamp: new Date(),
+ *   metadata: { source: 'api', version: '1.0' }
+ * };
+ *
+ * // Emit event
+ * eventEmitter.emit(event);
+ * ```
+ */
+export interface FeatureFlagEvent {
+    /** Type of flag operation */
+    type: 'evaluation' | 'update' | 'create' | 'delete' | 'refresh';
+    /** Flag identifier */
+    flagKey: string;
+    /** Evaluation context (for evaluations) */
+    context?: FeatureFlagContext;
+    /** Flag value (for evaluations/updates) */
+    value?: FeatureFlagValue;
+    /** Event timestamp */
+    timestamp: Date;
+    /** Additional event metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Handler function for feature flag events
+ *
+ * @example
+ * ```typescript
+ * const handler: FeatureFlagEventHandler = async (event) => {
+ *   console.log(`Flag ${event.flagKey} was ${event.type}`);
+ *
+ *   if (event.type === 'evaluation') {
+ *     await logFlagUsage(event.flagKey, event.context, event.value);
+ *   }
+ * };
+ *
+ * eventEmitter.on('evaluation', handler);
+ * ```
+ */
+export interface FeatureFlagEventHandler {
+    (event: FeatureFlagEvent): void | Promise<void>;
+}
+/**
+ * Event emitter for feature flag events with subscription management
+ *
+ * @example
+ * ```typescript
+ * const emitter: FeatureFlagEventEmitter = createFeatureFlagEventEmitter();
+ *
+ * // Subscribe to events
+ * const unsubscribe = emitter.on('evaluation', (event) => {
+ *   console.log(`Flag ${event.flagKey} evaluated to ${event.value}`);
+ * });
+ *
+ * // One-time subscription
+ * emitter.once('update', (event) => {
+ *   console.log('Flag updated:', event.flagKey);
+ * });
+ *
+ * // Emit events
+ * emitter.emit({
+ *   type: 'evaluation',
+ *   flagKey: 'my-flag',
+ *   value: true,
+ *   timestamp: new Date()
+ * });
+ *
+ * // Clean up
+ * unsubscribe();
+ * emitter.removeAllListeners();
+ * ```
+ */
+export interface FeatureFlagEventEmitter {
+    /** Subscribe to events */
+    on: (type: FeatureFlagEvent['type'], handler: FeatureFlagEventHandler) => () => void;
+    /** Subscribe to single event */
+    once: (type: FeatureFlagEvent['type'], handler: FeatureFlagEventHandler) => () => void;
+    /** Emit an event */
+    emit: (event: FeatureFlagEvent) => void;
+    /** Unsubscribe from events */
+    off: (type: FeatureFlagEvent['type'], handler: FeatureFlagEventHandler) => void;
+    /** Remove all listeners */
+    removeAllListeners: (type?: FeatureFlagEvent['type']) => void;
+}
+/**
+ * Custom assertions for React hook testing with feature flags
+ *
+ * @example
+ * ```typescript
+ * const { result } = renderHook(() => useFeatureFlag('my-flag'), {
+ *   wrapper: FeatureFlagProvider
+ * });
+ *
+ * // Custom hook assertions
+ * expect(result).toBeEnabled('my-flag');
+ * expect(result).toBeDisabled('old-flag');
+ * expect(result).toHaveValue('theme-flag', 'dark');
+ * ```
+ */
+export interface FeatureFlagHookAssertion<FeatureFlagKey extends string> {
+    /** Assert hook shows flag as enabled */
+    toBeEnabled: (flagKey: FeatureFlagKey) => void;
+    /** Assert hook shows flag as disabled */
+    toBeDisabled: (flagKey: FeatureFlagKey) => void;
+    /** Assert hook shows flag with specific value */
+    toHaveValue: (flagKey: FeatureFlagKey, value: FeatureFlagValue) => void;
+}
+/**
+ * Stub definition for temporarily overriding feature flags in tests
+ *
+ * @example
+ * ```typescript
+ * const stub: FeatureFlagStub = {
+ *   key: 'premium-feature',
+ *   value: true,
+ *   enabled: true,
+ *   conditions: [{ field: 'tier', operator: 'equals', value: 'premium' }],
+ *   rolloutPercentage: 100,
+ *   temporary: true,
+ *   priority: 10
+ * };
+ *
+ * stubManager.add(stub, { duration: 5000 });
+ * ```
+ */
+export interface FeatureFlagStub {
+    /** Flag key to stub */
+    key: string;
+    /** Value to return */
+    value: FeatureFlagValue;
+    /** Whether flag is enabled */
+    enabled: boolean;
+    /** Conditions for evaluation */
+    conditions?: FeatureFlagCondition[];
+    /** Rollout percentage override */
+    rolloutPercentage?: number;
+    /** Auto-remove after test */
+    temporary?: boolean;
+    /** Stub priority (higher wins) */
+    priority?: number;
+}
+/**
+ * Options for configuring feature flag stubs
+ *
+ * @example
+ * ```typescript
+ * const options: FeatureFlagStubOptions = {
+ *   duration: 10000, // Auto-remove after 10 seconds
+ *   priority: 5,
+ *   overrideExisting: true,
+ *   applyToAllTests: false,
+ *   scoped: true // Only apply to current test
+ * };
+ *
+ * stubManager.add(myStub, options);
+ * ```
+ */
+export interface FeatureFlagStubOptions {
+    /** Auto-remove duration in milliseconds */
+    duration?: number;
+    /** Stub priority for conflicts */
+    priority?: number;
+    /** Override existing stubs */
+    overrideExisting?: boolean;
+    /** Apply to all tests in suite */
+    applyToAllTests?: boolean;
+    /** Scope to current test only */
+    scoped?: boolean;
+}
+/**
+ * Manager for feature flag stubs with full lifecycle management
+ *
+ * @example
+ * ```typescript
+ * const manager: FeatureFlagStubManager = createStubManager();
+ *
+ * // Add stub
+ * manager.add({
+ *   key: 'test-feature',
+ *   value: true,
+ *   enabled: true
+ * });
+ *
+ * // Quick modifications
+ * manager.enable('disabled-feature');
+ * manager.setValue('config-flag', { theme: 'dark' });
+ * manager.setRollout('gradual-feature', 25);
+ *
+ * // Condition management
+ * manager.addCondition('targeted-feature', {
+ *   field: 'userId',
+ *   operator: 'in',
+ *   value: ['user1', 'user2']
+ * });
+ *
+ * // Cleanup
+ * manager.clear();
+ * ```
+ */
+export interface FeatureFlagStubManager {
+    /** Add a new stub */
+    add: (stub: FeatureFlagStub, options?: FeatureFlagStubOptions) => void;
+    /** Remove stub by key */
+    remove: (key: string) => void;
+    /** Update existing stub */
+    update: (key: string, updates: Partial<FeatureFlagStub>) => void;
+    /** Clear all stubs */
+    clear: () => void;
+    /** List all stubs */
+    list: () => FeatureFlagStub[];
+    /** Get stub by key */
+    get: (key: string) => FeatureFlagStub | undefined;
+    /** Check if stub exists */
+    exists: (key: string) => boolean;
+    /** Enable flag stub */
+    enable: (key: string) => void;
+    /** Disable flag stub */
+    disable: (key: string) => void;
+    /** Set flag value */
+    setValue: (key: string, value: FeatureFlagValue) => void;
+    /** Set rollout percentage */
+    setRollout: (key: string, percentage: number) => void;
+    /** Add condition to flag */
+    addCondition: (key: string, condition: FeatureFlagCondition) => void;
+    /** Remove condition by index */
+    removeCondition: (key: string, index: number) => void;
+}
+/**
+ * Feature flag update operation with timing control
+ *
+ * @example
+ * ```typescript
+ * const update: FeatureFlagUpdate = {
+ *   key: 'gradual-rollout',
+ *   value: true,
+ *   delay: 2000 // Apply after 2 seconds
+ * };
+ *
+ * // Schedule update
+ * await scheduleFeatureFlagUpdate(update);
+ * ```
+ */
+export interface FeatureFlagUpdate<FeatureFlagKey extends string> {
+    /** Flag key to update */
+    key: FeatureFlagKey;
+    /** New flag value */
+    value: FeatureFlagValue;
+    /** Delay before applying update (ms) */
+    delay: number;
+}
+/**
+ * Result of feature flag operation
+ *
+ * @example
+ * ```typescript
+ * const result: FeatureFlagResult = {
+ *   success: true,
+ *   value: { theme: 'dark', language: 'en' }
+ * };
+ *
+ * if (result.success) {
+ *   console.log('Flag value:', result.value);
+ * }
+ * ```
+ */
+export interface FeatureFlagResult {
+    /** Whether operation succeeded */
+    success?: boolean;
+    /** Operation result value */
+    value?: unknown;
+}
+/**
+ * Result wrapper for feature flag hook values
+ *
+ * @typeParam T - Type of the hook result value
+ *
+ * @example
+ * ```typescript
+ * const hookResult: FeatureFlagHookResult<boolean> = {
+ *   current: true
+ * };
+ *
+ * // Usage in hook
+ * const { result } = renderHook(() => useFeatureFlag('my-flag'));
+ * expect(result.current).toBe(true);
+ * ```
+ */
+export interface FeatureFlagHookResult<T> {
+    /** Current hook value */
+    current: T;
+}
+/**
+ * Props for feature flag test wrapper component
+ *
+ * @example
+ * ```typescript
+ * const WrapperComponent: React.FC<FeatureFlagWrapperProps> = ({ children }) => (
+ *   <FeatureFlagProvider provider={mockProvider}>
+ *     {children}
+ *   </FeatureFlagProvider>
+ * );
+ *
+ * render(<MyComponent />, { wrapper: WrapperComponent });
+ * ```
+ */
+export interface FeatureFlagWrapperProps {
+    /** Child components to wrap */
+    children: React.ReactNode;
+}
+/**
+ * Feature flag operation descriptor for batch operations
+ *
+ * @example
+ * ```typescript
+ * const operations: FeatureFlagOperation[] = [
+ *   { type: 'set', key: 'feature-a', value: true },
+ *   { type: 'set', key: 'feature-b', value: 'variant-1' },
+ *   { type: 'remove', key: 'old-feature' },
+ *   { type: 'get', key: 'current-feature' }
+ * ];
+ *
+ * const results = await batchFeatureFlagOperations(operations);
+ * ```
+ */
+export interface FeatureFlagOperation<FeatureFlagKey extends string> {
+    /** Operation type */
+    type: 'set' | 'remove' | 'get';
+    /** Flag key */
+    key: FeatureFlagKey;
+    /** Value for set operations */
+    value?: FeatureFlagValue;
+}
+/**
+ * Performance metrics for feature flag operations
+ *
+ * @example
+ * ```typescript
+ * const metrics: FeatureFlagPerformanceMetrics = {
+ *   avg: 15.5, // Average response time in ms
+ *   min: 8.2,  // Fastest response
+ *   max: 45.1, // Slowest response
+ *   total: 1000 // Total operations measured
+ * };
+ *
+ * console.log(`Average evaluation time: ${metrics.avg}ms`);
+ * ```
+ */
+export interface FeatureFlagPerformanceMetrics {
+    /** Average operation time (ms) */
+    avg: number;
+    /** Minimum operation time (ms) */
+    min: number;
+    /** Maximum operation time (ms) */
+    max: number;
+    /** Total operations measured */
+    total: number;
+}
+export interface FeatureFlagLoadTestResult {
+    duration: number;
+    errors: Error[];
+}
+export interface ControllableProvider<FeatureFlagKey extends string> {
+    provider: IFeatureFlagProvider<FeatureFlagKey>;
+    control: {
+        resolveMethod: (method: string) => void;
+        rejectMethod: (method: string, error: Error) => void;
+        resolveAll: () => void;
+        rejectAll: (error: Error) => void;
+        reset: () => void;
+    };
+}
+export interface SubscriptionFeatureFlagTracker<FeatureFlagKey extends string> {
+    track: (provider: IFeatureFlagProvider<FeatureFlagKey>, id?: string) => {
+        id: string;
+        callback: Vitest.Mock;
+        unsubscribe: () => void;
+    };
+    unsubscribe: (id: string) => void;
+    unsubscribeAll: () => void;
+    getCallCount: (id: string) => number;
+    getLastCall: (id: string) => unknown;
+    reset: () => void;
+}
+export interface EvaluationAssertions {
+    hasValue: (expected: unknown) => void;
+    hasReason: (expected: string) => void;
+    hasSource: (expected: string) => void;
+    hasRuleId: (expected: string) => void;
+    wasEvaluatedRecently: (maxAgeMs?: number) => void;
+}
+export interface TestFeatureFlagProviderProps<FeatureFlagKey extends string> {
+    provider: IFeatureFlagProvider<FeatureFlagKey>;
+    children: React.ReactNode;
+    context?: React.Context<FeatureFlagContextValue<FeatureFlagKey> | null>;
+}
+export interface CreateProviderForTestOptions<FeatureFlagKey extends string> {
+    provider?: IFeatureFlagProvider<FeatureFlagKey>;
+    config?: Partial<FeatureFlagConfig<FeatureFlagKey>>;
+    flags?: Record<string, FeatureFlagValue>;
+    features?: Record<FeatureFlagKey, FeatureFlagValue>;
+    ProviderClass?: new (config: FeatureFlagConfig<FeatureFlagKey>, features: Record<FeatureFlagKey, FeatureFlagValue>) => IFeatureFlagProvider<FeatureFlagKey>;
+}
+export interface SetupFeatureFlagTestOptions<FeatureFlagKey extends string> {
+    provider?: IFeatureFlagProvider<FeatureFlagKey>;
+    config?: Partial<FeatureFlagConfig<FeatureFlagKey>>;
+    flags?: Record<string, FeatureFlagValue>;
+    setupBeforeEach?: boolean;
+    autoInit: boolean;
+    context?: React.Context<FeatureFlagContextValue<FeatureFlagKey> | null>;
+    ProviderClass?: new (config: FeatureFlagConfig<FeatureFlagKey>, features: Record<FeatureFlagKey, FeatureFlagValue>) => IFeatureFlagProvider<FeatureFlagKey>;
+    features?: Record<FeatureFlagKey, FeatureFlagValue>;
+}
+export interface PercentageRolloutScenario<FeatureFlagKey extends string> {
+    rule: FeatureFlagRule<FeatureFlagKey>;
+    users: string[];
+    expectedEnabled: number;
+    evaluate: (userId: string) => boolean;
+}
+export interface TimeBasedRolloutScenario<FeatureFlagKey extends string> {
+    rule: FeatureFlagRule<FeatureFlagKey>;
+    isActive: (date?: Date) => boolean;
+}
+export interface TargetedUsersScenario<FeatureFlagKey extends string> {
+    rule: FeatureFlagRule<FeatureFlagKey>;
+    isTargeted: (userId: string) => boolean;
+}
+export interface ABTestScenario<FeatureFlagKey extends string> {
+    rules: FeatureFlagRule<FeatureFlagKey>[];
+    variants: Record<string, FeatureFlagValue>;
+    distribution: Record<string, number>;
+    assignVariant: (userId: string) => string;
+}
+export interface ComplexRulesScenario<FeatureFlagKey extends string> {
+    rules: FeatureFlagRule<FeatureFlagKey>[];
+    evaluate: (context: FeatureFlagContext) => FeatureFlagEvaluation<FeatureFlagKey>;
+}
+export interface MockFeatureFlagProviderWithState<FeatureFlagKey extends string> extends IFeatureFlagProvider<FeatureFlagKey> {
+    _mockState: {
+        flags: Map<FeatureFlagKey, FeatureFlag<FeatureFlagKey>>;
+        overrides: Map<FeatureFlagKey, FeatureFlagValue>;
+        subscribers: Set<(flags: FeatureFlag<FeatureFlagKey>[]) => void>;
+    };
+}
+export interface TestFeatureFlagContextValue<FeatureFlagKey extends string> {
+    provider: IFeatureFlagProvider<FeatureFlagKey>;
+    isInitialized: boolean;
+    isLoading: boolean;
+    error: Error | null;
+    lastUpdated: Date;
+    refresh: () => Promise<void>;
+}
+export interface WaitForFlagValueOptions {
+    context?: FeatureFlagContext;
+    timeout?: number;
+}