@c-a-f/testing 1.0.1

package/.build/src/core/PlocTestHelpers.js

@@ -0,0 +1,205 @@
+/**
+ * Test helpers for Ploc (Presentation Logic Component).
+ *
+ * Provides utilities for testing Ploc instances.
+ *
+ * @example
+ * ```ts
+ * import { createPlocTester, waitForStateChange, createMockPloc } from '@c-a-f/testing/core';
+ * import { MyPloc } from './MyPloc';
+ *
+ * const tester = createPlocTester(new MyPloc());
+ *
+ * // Wait for state change
+ * await waitForStateChange(tester.ploc, (state) => state.count === 5);
+ *
+ * // Get state history
+ * const history = tester.getStateHistory();
+ *
+ * // Or use a mock Ploc with controllable state
+ * const mockPloc = createMockPloc({ count: 0 });
+ * mockPloc.changeState({ count: 1 });
+ * ```
+ */
+import { Ploc } from '@c-a-f/core';
+/**
+ * Concrete Ploc implementation for testing.
+ * Provides a Ploc with controllable state and no business logic.
+ */
+export class MockPloc extends Ploc {
+    constructor(initialState) {
+        super(initialState);
+    }
+}
+/**
+ * Create a mock Ploc with controllable state for unit tests.
+ * The returned Ploc has no logic; use changeState() to drive state in tests.
+ *
+ * @example
+ * ```ts
+ * const ploc = createMockPloc({ count: 0, loading: false });
+ * expect(ploc.state.count).toBe(0);
+ * ploc.changeState({ count: 1, loading: true });
+ * expect(ploc.state.count).toBe(1);
+ * ```
+ */
+export function createMockPloc(initialState) {
+    return new MockPloc(initialState);
+}
+/**
+ * Ploc tester utility.
+ * Tracks state changes and provides testing utilities.
+ */
+export class PlocTester {
+    ploc;
+    stateHistory = [];
+    listener = null;
+    constructor(ploc) {
+        this.ploc = ploc;
+        this.stateHistory.push(ploc.state);
+        this.listener = (state) => {
+            this.stateHistory.push(state);
+        };
+        ploc.subscribe(this.listener);
+    }
+    /**
+     * Get the current state.
+     */
+    getState() {
+        return this.ploc.state;
+    }
+    /**
+     * Get the state history.
+     */
+    getStateHistory() {
+        return [...this.stateHistory];
+    }
+    /**
+     * Get the initial state.
+     */
+    getInitialState() {
+        return this.stateHistory[0];
+    }
+    /**
+     * Get the last state change.
+     */
+    getLastStateChange() {
+        return this.stateHistory.length > 1
+            ? this.stateHistory[this.stateHistory.length - 1]
+            : undefined;
+    }
+    /**
+     * Get the number of state changes.
+     */
+    getStateChangeCount() {
+        return Math.max(0, this.stateHistory.length - 1);
+    }
+    /**
+     * Cleanup: unsubscribe from state changes.
+     */
+    cleanup() {
+        if (this.listener) {
+            this.ploc.unsubscribe(this.listener);
+            this.listener = null;
+        }
+    }
+}
+/**
+ * Create a Ploc tester instance.
+ */
+export function createPlocTester(ploc) {
+    return new PlocTester(ploc);
+}
+/**
+ * Wait for a state change that matches a predicate.
+ *
+ * @param ploc The Ploc instance to watch
+ * @param predicate Function that returns true when the desired state is reached
+ * @param timeout Maximum time to wait in milliseconds (default: 5000)
+ * @returns Promise that resolves when the predicate returns true
+ */
+export function waitForStateChange(ploc, predicate, timeout = 5000) {
+    return new Promise((resolve, reject) => {
+        // Check current state first
+        if (predicate(ploc.state)) {
+            resolve(ploc.state);
+            return;
+        }
+        const listener = (state) => {
+            if (predicate(state)) {
+                clearTimeout(timer);
+                ploc.unsubscribe(listener);
+                resolve(state);
+            }
+        };
+        const timer = setTimeout(() => {
+            ploc.unsubscribe(listener);
+            reject(new Error(`Timeout waiting for state change (${timeout}ms)`));
+        }, timeout);
+        ploc.subscribe(listener);
+    });
+}
+/**
+ * Wait for a specific number of state changes.
+ */
+export function waitForStateChanges(ploc, count, timeout = 5000) {
+    return new Promise((resolve, reject) => {
+        const states = [];
+        const listener = (state) => {
+            states.push(state);
+            if (states.length >= count) {
+                clearTimeout(timer);
+                ploc.unsubscribe(listener);
+                resolve(states);
+            }
+        };
+        const timer = setTimeout(() => {
+            ploc.unsubscribe(listener);
+            reject(new Error(`Timeout waiting for ${count} state changes (${timeout}ms)`));
+        }, timeout);
+        ploc.subscribe(listener);
+    });
+}
+// --- Snapshot testing utilities ---
+/**
+ * Assert that the Ploc tester's state history matches the expected states.
+ * Uses JSON comparison so objects are compared by value.
+ * Use with your test framework's expect (e.g. expect().toEqual).
+ *
+ * @example
+ * ```ts
+ * const tester = createPlocTester(ploc);
+ * ploc.changeState({ step: 1 });
+ * ploc.changeState({ step: 2 });
+ * assertStateHistory(tester, [initialState, { step: 1 }, { step: 2 }]);
+ * ```
+ */
+export function assertStateHistory(tester, expected) {
+    const actual = tester.getStateHistory();
+    const actualJson = JSON.stringify(actual);
+    const expectedJson = JSON.stringify(expected);
+    if (actualJson !== expectedJson) {
+        throw new Error(`State history mismatch.\nExpected: ${expectedJson}\nActual: ${actualJson}`);
+    }
+}
+/**
+ * Return a serializable snapshot of the state history for snapshot testing.
+ * Use with your test framework's toMatchSnapshot() or similar.
+ *
+ * @example
+ * ```ts
+ * const tester = createPlocTester(ploc);
+ * // ... trigger state changes ...
+ * expect(getStateHistorySnapshot(tester)).toMatchSnapshot();
+ * ```
+ */
+export function getStateHistorySnapshot(tester) {
+    return tester.getStateHistory();
+}
+/**
+ * Return a serialized (JSON) snapshot of the state history for snapshot testing.
+ * Useful when state is plain data and you want a string snapshot.
+ */
+export function getStateHistorySnapshotJson(tester) {
+    return JSON.stringify(tester.getStateHistory(), null, 2);
+}

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

@@ -0,0 +1,71 @@
+/**
+ * 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);
+ * ```
+ */
+import type { Pulse } from '@c-a-f/core';
+/**
+ * Pulse tester utility.
+ * Tracks value changes and provides testing utilities.
+ */
+type PulseLike<T> = Pulse<T> & {
+    value: T;
+    subscribe(listener: (value: T) => void): void;
+    unsubscribe(listener: (value: T) => void): void;
+};
+export declare class PulseTester<T> {
+    readonly pulse: PulseLike<T>;
+    private valueHistory;
+    private listener;
+    constructor(pulse: PulseLike<T>);
+    /**
+     * Get the current value.
+     */
+    getValue(): T;
+    /**
+     * Get the value history.
+     */
+    getValueHistory(): T[];
+    /**
+     * Get the initial value.
+     */
+    getInitialValue(): T;
+    /**
+     * Get the last value change.
+     */
+    getLastValueChange(): T | undefined;
+    /**
+     * Get the number of value changes.
+     */
+    getValueChangeCount(): number;
+    /**
+     * Cleanup: unsubscribe from value changes.
+     */
+    cleanup(): void;
+}
+/**
+ * Create a Pulse tester instance.
+ */
+export declare function createPulseTester<T>(pulse: PulseLike<T>): PulseTester<T>;
+/**
+ * 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 declare function waitForPulseValue<T>(pulse: PulseLike<T>, predicate: (value: T) => boolean, timeout?: number): Promise<T>;
+export {};

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);
+}