@c.a.f/testing 1.0.0

package/.build/src/core/PulseTestHelpers.js

@@ -0,0 +1,106 @@
+/**
+ * Test helpers for Pulse (reactive values).
+ *
+ * Provides utilities for testing Pulse instances.
+ *
+ * @example
+ * ```ts
+ * import { createPulseTester, waitForPulseValue } from '@c.a.f/testing/core';
+ * import { pulse } from '@c.a.f/core';
+ *
+ * const count = pulse(0);
+ * const tester = createPulseTester(count);
+ *
+ * count.value = 5;
+ * await waitForPulseValue(count, (value) => value === 5);
+ * ```
+ */
+export class PulseTester {
+    pulse;
+    valueHistory = [];
+    listener = null;
+    constructor(pulse) {
+        this.pulse = pulse;
+        this.valueHistory.push(pulse.value);
+        this.listener = (value) => {
+            this.valueHistory.push(value);
+        };
+        pulse.subscribe(this.listener);
+    }
+    /**
+     * Get the current value.
+     */
+    getValue() {
+        return this.pulse.value;
+    }
+    /**
+     * Get the value history.
+     */
+    getValueHistory() {
+        return [...this.valueHistory];
+    }
+    /**
+     * Get the initial value.
+     */
+    getInitialValue() {
+        return this.valueHistory[0];
+    }
+    /**
+     * Get the last value change.
+     */
+    getLastValueChange() {
+        return this.valueHistory.length > 1
+            ? this.valueHistory[this.valueHistory.length - 1]
+            : undefined;
+    }
+    /**
+     * Get the number of value changes.
+     */
+    getValueChangeCount() {
+        return Math.max(0, this.valueHistory.length - 1);
+    }
+    /**
+     * Cleanup: unsubscribe from value changes.
+     */
+    cleanup() {
+        if (this.listener) {
+            this.pulse.unsubscribe(this.listener);
+            this.listener = null;
+        }
+    }
+}
+/**
+ * Create a Pulse tester instance.
+ */
+export function createPulseTester(pulse) {
+    return new PulseTester(pulse);
+}
+/**
+ * Wait for a pulse value that matches a predicate.
+ *
+ * @param pulse The Pulse instance to watch
+ * @param predicate Function that returns true when the desired value is reached
+ * @param timeout Maximum time to wait in milliseconds (default: 5000)
+ * @returns Promise that resolves when the predicate returns true
+ */
+export function waitForPulseValue(pulse, predicate, timeout = 5000) {
+    return new Promise((resolve, reject) => {
+        // Check current value first
+        if (predicate(pulse.value)) {
+            resolve(pulse.value);
+            return;
+        }
+        const listener = (value) => {
+            if (predicate(value)) {
+                clearTimeout(timer);
+                pulse.unsubscribe(listener);
+                resolve(value);
+            }
+        };
+        const timer = setTimeout(() => {
+            pulse.unsubscribe(listener);
+            reject(new Error(`Timeout waiting for pulse value (${timeout}ms)`));
+        }, timeout);
+        pulse.subscribe(listener);
+    });
+}

package/.build/src/core/RepositoryTestHelpers.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Test helpers for domain repository interfaces (I*Repository).
+ *
+ * Provides a generic stub so you can override only the methods your test needs.
+ *
+ * @example
+ * ```ts
+ * import { createMockRepository } from '@c.a.f/testing/core';
+ * import type { IUserRepository } from '../domain';
+ *
+ * const mockRepo = createMockRepository<IUserRepository>({
+ *   getUsers: async () => [{ id: '1', name: 'John' }],
+ *   getUserById: async (id) => ({ id, name: 'User ' + id }),
+ * });
+ * // getUsers and getUserById are stubbed; other methods return undefined (can be overridden)
+ *
+ * // Or use an empty stub and assign/spy later
+ * const stub = createMockRepository<IUserRepository>();
+ * stub.getUsers = async () => [];
+ * ```
+ */
+/**
+ * Create a generic mock repository stub.
+ * - With no args: returns a proxy that implements any method as async () => undefined.
+ *   You can assign specific methods or use with a test spy.
+ * - With methods: returns an object with those methods; any other method call
+ *   returns undefined (optional second argument can provide a default).
+ *
+ * @example
+ * ```ts
+ * const repo = createMockRepository<IUserRepository>({
+ *   getUsers: async () => [],
+ *   getUserById: async (id) => ({ id, name: 'Test' }),
+ * });
+ * ```
+ */
+export declare function createMockRepository<T extends Record<string, (...args: any[]) => Promise<any>>>(methods?: Partial<T>): T;
+/**
+ * Create an empty repository stub. Every method returns Promise.resolve(undefined).
+ * Assign or spy on methods as needed.
+ *
+ * @example
+ * ```ts
+ * const repo = createMockRepositoryStub<IUserRepository>();
+ * repo.getUsers = vi.fn().mockResolvedValue([{ id: '1', name: 'John' }]);
+ * ```
+ */
+export declare function createMockRepositoryStub<T>(): T;

package/.build/src/core/RepositoryTestHelpers.js

@@ -0,0 +1,76 @@
+/**
+ * Test helpers for domain repository interfaces (I*Repository).
+ *
+ * Provides a generic stub so you can override only the methods your test needs.
+ *
+ * @example
+ * ```ts
+ * import { createMockRepository } from '@c.a.f/testing/core';
+ * import type { IUserRepository } from '../domain';
+ *
+ * const mockRepo = createMockRepository<IUserRepository>({
+ *   getUsers: async () => [{ id: '1', name: 'John' }],
+ *   getUserById: async (id) => ({ id, name: 'User ' + id }),
+ * });
+ * // getUsers and getUserById are stubbed; other methods return undefined (can be overridden)
+ *
+ * // Or use an empty stub and assign/spy later
+ * const stub = createMockRepository<IUserRepository>();
+ * stub.getUsers = async () => [];
+ * ```
+ */
+const defaultAsyncStub = async () => undefined;
+/**
+ * Create a generic mock repository stub.
+ * - With no args: returns a proxy that implements any method as async () => undefined.
+ *   You can assign specific methods or use with a test spy.
+ * - With methods: returns an object with those methods; any other method call
+ *   returns undefined (optional second argument can provide a default).
+ *
+ * @example
+ * ```ts
+ * const repo = createMockRepository<IUserRepository>({
+ *   getUsers: async () => [],
+ *   getUserById: async (id) => ({ id, name: 'Test' }),
+ * });
+ * ```
+ */
+export function createMockRepository(methods) {
+    const base = (methods ?? {});
+    return new Proxy(base, {
+        get(target, prop) {
+            if (prop in target && typeof target[prop] === 'function') {
+                return target[prop];
+            }
+            return defaultAsyncStub;
+        },
+    });
+}
+/**
+ * Create an empty repository stub. Every method returns Promise.resolve(undefined).
+ * Assign or spy on methods as needed.
+ *
+ * @example
+ * ```ts
+ * const repo = createMockRepositoryStub<IUserRepository>();
+ * repo.getUsers = vi.fn().mockResolvedValue([{ id: '1', name: 'John' }]);
+ * ```
+ */
+export function createMockRepositoryStub() {
+    const target = {};
+    return new Proxy(target, {
+        get(target, prop) {
+            // If property exists on target (was assigned), return it
+            if (prop in target) {
+                return target[prop];
+            }
+            // Otherwise return default stub
+            return defaultAsyncStub;
+        },
+        set(target, prop, value) {
+            // Allow assignment
+            target[prop] = value;
+            return true;
+        },
+    });
+}

package/.build/src/core/RouteTestHelpers.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Test helpers for RouteManager and RouteRepository.
+ *
+ * Provides mock implementations and utilities for testing routing.
+ *
+ * @example
+ * ```ts
+ * import { createMockRouteRepository, createRouteManagerTester } from '@c.a.f/testing/core';
+ * import { RouteManager } from '@c.a.f/core';
+ *
+ * const mockRepo = createMockRouteRepository();
+ * const routeManager = new RouteManager(mockRepo);
+ * const tester = createRouteManagerTester(routeManager);
+ *
+ * await tester.changeRoute('/dashboard');
+ * expect(tester.getCurrentRoute()).toBe('/dashboard');
+ * ```
+ */
+import type { RouteRepository, RouteManager } from '@c.a.f/core';
+/**
+ * Mock RouteRepository implementation for testing.
+ */
+export declare class MockRouteRepository implements RouteRepository {
+    private _currentRoute;
+    get currentRoute(): string;
+    change(route: string): void;
+    /**
+     * Set the current route directly (for testing).
+     */
+    setRoute(route: string): void;
+    /**
+     * Get route change history.
+     */
+    getRouteHistory(): string[];
+}
+/**
+ * Create a mock RouteRepository.
+ */
+export declare function createMockRouteRepository(): MockRouteRepository;
+/**
+ * RouteManager tester utility.
+ */
+export declare class RouteManagerTester {
+    readonly routeManager: RouteManager;
+    private routeHistory;
+    constructor(routeManager: RouteManager);
+    /**
+     * Change route and track it.
+     */
+    changeRoute(route: string): Promise<void>;
+    /**
+     * Get the current route.
+     */
+    getCurrentRoute(): string;
+    /**
+     * Get route change history.
+     */
+    getRouteHistory(): string[];
+    /**
+     * Check if user is logged in (based on RouteManager auth options).
+     */
+    checkForLoginRoute(): void;
+}
+/**
+ * Create a RouteManager tester instance.
+ */
+export declare function createRouteManagerTester(routeManager: RouteManager): RouteManagerTester;

package/.build/src/core/RouteTestHelpers.js

@@ -0,0 +1,94 @@
+/**
+ * Test helpers for RouteManager and RouteRepository.
+ *
+ * Provides mock implementations and utilities for testing routing.
+ *
+ * @example
+ * ```ts
+ * import { createMockRouteRepository, createRouteManagerTester } from '@c.a.f/testing/core';
+ * import { RouteManager } from '@c.a.f/core';
+ *
+ * const mockRepo = createMockRouteRepository();
+ * const routeManager = new RouteManager(mockRepo);
+ * const tester = createRouteManagerTester(routeManager);
+ *
+ * await tester.changeRoute('/dashboard');
+ * expect(tester.getCurrentRoute()).toBe('/dashboard');
+ * ```
+ */
+/**
+ * Mock RouteRepository implementation for testing.
+ */
+export class MockRouteRepository {
+    _currentRoute = '/';
+    get currentRoute() {
+        return this._currentRoute;
+    }
+    change(route) {
+        this._currentRoute = route;
+    }
+    /**
+     * Set the current route directly (for testing).
+     */
+    setRoute(route) {
+        this._currentRoute = route;
+    }
+    /**
+     * Get route change history.
+     */
+    getRouteHistory() {
+        return [this._currentRoute];
+    }
+}
+/**
+ * Create a mock RouteRepository.
+ */
+export function createMockRouteRepository() {
+    return new MockRouteRepository();
+}
+/**
+ * RouteManager tester utility.
+ */
+export class RouteManagerTester {
+    routeManager;
+    routeHistory = [];
+    constructor(routeManager) {
+        this.routeManager = routeManager;
+        // Track route changes if possible
+        const repo = routeManager.routeRepository;
+        if (repo instanceof MockRouteRepository) {
+            this.routeHistory.push(repo.currentRoute);
+        }
+    }
+    /**
+     * Change route and track it.
+     */
+    async changeRoute(route) {
+        this.routeManager.changeRoute(route);
+        this.routeHistory.push(route);
+    }
+    /**
+     * Get the current route.
+     */
+    getCurrentRoute() {
+        return this.routeManager.routeRepository.currentRoute;
+    }
+    /**
+     * Get route change history.
+     */
+    getRouteHistory() {
+        return [...this.routeHistory];
+    }
+    /**
+     * Check if user is logged in (based on RouteManager auth options).
+     */
+    checkForLoginRoute() {
+        this.routeManager.checkForLoginRoute();
+    }
+}
+/**
+ * Create a RouteManager tester instance.
+ */
+export function createRouteManagerTester(routeManager) {
+    return new RouteManagerTester(routeManager);
+}

package/.build/src/core/UseCaseTestHelpers.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Test helpers for UseCase.
+ *
+ * Provides utilities for testing UseCase implementations.
+ *
+ * @example
+ * ```ts
+ * import { createMockUseCase, createUseCaseTester } from '@c.a.f/testing/core';
+ * import { UseCase, RequestResult, pulse } from '@c.a.f/core';
+ *
+ * // Create a mock use case
+ * const mockUseCase = createMockUseCase<User[]>((args) => ({
+ *   loading: pulse(false),
+ *   data: pulse([{ id: '1', name: 'John' }]),
+ *   error: pulse(null! as Error),
+ * }));
+ *
+ * // Test use case
+ * const tester = createUseCaseTester(mockUseCase);
+ * const result = await tester.execute([], { timeout: 1000 });
+ * ```
+ */
+import type { UseCase, RequestResult } from '@c.a.f/core';
+/**
+ * Mock UseCase implementation for testing.
+ */
+export declare class MockUseCase<A extends any[], T> implements UseCase<A, T> {
+    private implementation;
+    constructor(implementation: (...args: A) => Promise<RequestResult<T>> | RequestResult<T>);
+    execute(...args: A): Promise<RequestResult<T>>;
+}
+/**
+ * Create a mock UseCase from an implementation.
+ */
+export declare function createMockUseCase<A extends any[], T>(implementation: (...args: A) => Promise<RequestResult<T>> | RequestResult<T>): UseCase<A, T>;
+/**
+ * Create a mock UseCase that always returns success with the given data.
+ * Useful for unit tests that do not care about loading/error states.
+ *
+ * @example
+ * ```ts
+ * const useCase = createMockUseCaseSuccess([{ id: '1', name: 'John' }]);
+ * const result = await useCase.execute();
+ * expect(result.data.value).toEqual([{ id: '1', name: 'John' }]);
+ * ```
+ */
+export declare function createMockUseCaseSuccess<T>(data: T): UseCase<[], T>;
+/**
+ * Create a mock UseCase that always returns the given error.
+ *
+ * @example
+ * ```ts
+ * const useCase = createMockUseCaseError(new Error('Network failed'));
+ * const result = await useCase.execute();
+ * expect(result.error.value?.message).toBe('Network failed');
+ * ```
+ */
+export declare function createMockUseCaseError<T = unknown>(error: Error): UseCase<[], T>;
+/**
+ * Create a mock UseCase that returns loading then success (async).
+ * Useful for testing loading states.
+ */
+export declare function createMockUseCaseAsync<T>(data: T, delayMs?: number): UseCase<[], T>;
+/**
+ * UseCase tester utility.
+ */
+export declare class UseCaseTester<A extends any[], T> {
+    readonly useCase: UseCase<A, T>;
+    constructor(useCase: UseCase<A, T>);
+    /**
+     * Execute the use case and wait for completion.
+     */
+    execute(args: A, options?: {
+        timeout?: number;
+    }): Promise<RequestResult<T>>;
+    /**
+     * Execute the use case and extract data.
+     */
+    executeAndGetData(args: A): Promise<T>;
+    /**
+     * Execute the use case and check if it succeeds.
+     */
+    executeAndCheckSuccess(args: A): Promise<boolean>;
+}
+/**
+ * Create a UseCase tester instance.
+ */
+export declare function createUseCaseTester<A extends any[], T>(useCase: UseCase<A, T>): UseCaseTester<A, T>;
+/**
+ * Create a successful RequestResult.
+ */
+export declare function createSuccessResult<T>(data: T): RequestResult<T>;
+/**
+ * Create a failed RequestResult.
+ */
+export declare function createErrorResult<T>(error: Error): RequestResult<T>;
+/**
+ * Create a loading RequestResult.
+ */
+export declare function createLoadingResult<T>(): RequestResult<T>;

package/.build/src/core/UseCaseTestHelpers.js

@@ -0,0 +1,161 @@
+/**
+ * Test helpers for UseCase.
+ *
+ * Provides utilities for testing UseCase implementations.
+ *
+ * @example
+ * ```ts
+ * import { createMockUseCase, createUseCaseTester } from '@c.a.f/testing/core';
+ * import { UseCase, RequestResult, pulse } from '@c.a.f/core';
+ *
+ * // Create a mock use case
+ * const mockUseCase = createMockUseCase<User[]>((args) => ({
+ *   loading: pulse(false),
+ *   data: pulse([{ id: '1', name: 'John' }]),
+ *   error: pulse(null! as Error),
+ * }));
+ *
+ * // Test use case
+ * const tester = createUseCaseTester(mockUseCase);
+ * const result = await tester.execute([], { timeout: 1000 });
+ * ```
+ */
+import { pulse } from '@c.a.f/core';
+/**
+ * Mock UseCase implementation for testing.
+ */
+export class MockUseCase {
+    implementation;
+    constructor(implementation) {
+        this.implementation = implementation;
+    }
+    async execute(...args) {
+        return await this.implementation(...args);
+    }
+}
+/**
+ * Create a mock UseCase from an implementation.
+ */
+export function createMockUseCase(implementation) {
+    return new MockUseCase(implementation);
+}
+/**
+ * Create a mock UseCase that always returns success with the given data.
+ * Useful for unit tests that do not care about loading/error states.
+ *
+ * @example
+ * ```ts
+ * const useCase = createMockUseCaseSuccess([{ id: '1', name: 'John' }]);
+ * const result = await useCase.execute();
+ * expect(result.data.value).toEqual([{ id: '1', name: 'John' }]);
+ * ```
+ */
+export function createMockUseCaseSuccess(data) {
+    return new MockUseCase(() => createSuccessResult(data));
+}
+/**
+ * Create a mock UseCase that always returns the given error.
+ *
+ * @example
+ * ```ts
+ * const useCase = createMockUseCaseError(new Error('Network failed'));
+ * const result = await useCase.execute();
+ * expect(result.error.value?.message).toBe('Network failed');
+ * ```
+ */
+export function createMockUseCaseError(error) {
+    return new MockUseCase(() => createErrorResult(error));
+}
+/**
+ * Create a mock UseCase that returns loading then success (async).
+ * Useful for testing loading states.
+ */
+export function createMockUseCaseAsync(data, delayMs = 0) {
+    return new MockUseCase(() => new Promise((resolve) => {
+        if (delayMs <= 0) {
+            resolve(createSuccessResult(data));
+        }
+        else {
+            setTimeout(() => resolve(createSuccessResult(data)), delayMs);
+        }
+    }));
+}
+/**
+ * UseCase tester utility.
+ */
+export class UseCaseTester {
+    useCase;
+    constructor(useCase) {
+        this.useCase = useCase;
+    }
+    /**
+     * Execute the use case and wait for completion.
+     */
+    async execute(args, options) {
+        const timeout = options?.timeout || 5000;
+        return Promise.race([
+            this.useCase.execute(...args),
+            new Promise((_, reject) => {
+                setTimeout(() => reject(new Error(`UseCase execution timeout (${timeout}ms)`)), timeout);
+            }),
+        ]);
+    }
+    /**
+     * Execute the use case and extract data.
+     */
+    async executeAndGetData(args) {
+        const result = await this.execute(args);
+        if (result.error.value) {
+            throw result.error.value;
+        }
+        return result.data.value;
+    }
+    /**
+     * Execute the use case and check if it succeeds.
+     */
+    async executeAndCheckSuccess(args) {
+        try {
+            const result = await this.execute(args);
+            return !result.error.value;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * Create a UseCase tester instance.
+ */
+export function createUseCaseTester(useCase) {
+    return new UseCaseTester(useCase);
+}
+/**
+ * Create a successful RequestResult.
+ */
+export function createSuccessResult(data) {
+    return {
+        loading: pulse(false),
+        data: pulse(data),
+        error: pulse(null),
+    };
+}
+/**
+ * Create a failed RequestResult.
+ */
+export function createErrorResult(error) {
+    return {
+        loading: pulse(false),
+        data: pulse(null),
+        error: pulse(error),
+    };
+}
+/**
+ * Create a loading RequestResult.
+ */
+export function createLoadingResult() {
+    return {
+        loading: pulse(true),
+        data: pulse(null),
+        error: pulse(null),
+    };
+}

package/.build/src/core/index.d.ts

@@ -0,0 +1,6 @@
+export * from './PlocTestHelpers';
+export * from './PulseTestHelpers';
+export * from './UseCaseTestHelpers';
+export * from './RouteTestHelpers';
+export * from './RepositoryTestHelpers';
+export * from './IntegrationTestHelpers';

package/.build/src/core/index.js

@@ -0,0 +1,6 @@
+export * from './PlocTestHelpers';
+export * from './PulseTestHelpers';
+export * from './UseCaseTestHelpers';
+export * from './RouteTestHelpers';
+export * from './RepositoryTestHelpers';
+export * from './IntegrationTestHelpers';