@c.a.f/testing 1.0.0

package/.build/__tests__/react/renderWithCAF.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/.build/__tests__/react/renderWithCAF.spec.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { describe, it, expect } from 'vitest';
+import { createSuccessResult } from '../../src/core/UseCaseTestHelpers';
+import { renderWithCAF, createTestPloc, waitForPlocState, mockUseCase } from '../../src/react';
+// Full render tests require a single React instance (no duplicate react in node_modules).
+// Use renderWithCAF in your app tests; see README for examples.
+describe('renderWithCAF', () => {
+    it.skip('returns render result when given ui and options (run in app to avoid duplicate React)', () => {
+        const ploc = createTestPloc({ count: 0 });
+        const result = renderWithCAF(_jsx("div", { "data-testid": "root", children: "Hello" }), { plocs: { counter: ploc } });
+        expect(result).toBeDefined();
+        expect(result.getByTestId('root')).toHaveTextContent('Hello');
+    });
+});
+describe('createTestPloc', () => {
+    it('creates ploc with initial state', () => {
+        const ploc = createTestPloc({ count: 0 });
+        expect(ploc.state).toEqual({ count: 0 });
+    });
+    it('allows changing state', () => {
+        const ploc = createTestPloc({ count: 0 });
+        ploc.changeState({ count: 1 });
+        expect(ploc.state.count).toBe(1);
+    });
+});
+describe('waitForPlocState', () => {
+    it('resolves when predicate matches', async () => {
+        const ploc = createTestPloc({ count: 0 });
+        const promise = waitForPlocState(ploc, (s) => s.count === 2);
+        ploc.changeState({ count: 1 });
+        ploc.changeState({ count: 2 });
+        const state = await promise;
+        expect(state).toEqual({ count: 2 });
+    });
+});
+describe('mockUseCase', () => {
+    it('success returns data', async () => {
+        const uc = mockUseCase.success({ id: '1' });
+        const result = await uc.execute();
+        expect(result.data.value).toEqual({ id: '1' });
+    });
+    it('error returns error', async () => {
+        const err = new Error('Fail');
+        const uc = mockUseCase.error(err);
+        const result = await uc.execute();
+        expect(result.error.value).toBe(err);
+    });
+    it('fn uses custom implementation', async () => {
+        const uc = mockUseCase.fn((n) => Promise.resolve(createSuccessResult(n * 2)));
+        const result = await uc.execute(21);
+        expect(result.data.value).toBe(42);
+    });
+});

package/.build/index.d.ts

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

package/.build/index.js

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

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

@@ -0,0 +1,77 @@
+/**
+ * Integration test helpers for CAF.
+ *
+ * Utilities to run Ploc + UseCase together, flush async work, and small
+ * helpers for integration-style tests.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createPlocWithUseCase,
+ *   flushPromises,
+ *   runWithFakeTimers,
+ * } from '@c.a.f/testing/core';
+ * import { Ploc } from '@c.a.f/core';
+ *
+ * const ploc = createPlocWithUseCase(InitialState, (state, useCase) => ({ ... }));
+ * await flushPromises();
+ * ```
+ */
+import type { Ploc } from '@c.a.f/core';
+import type { UseCase } from '@c.a.f/core';
+/**
+ * Resolve all pending promises (microtasks).
+ * Call after triggering async code to wait for Promise resolution in tests.
+ *
+ * @example
+ * ```ts
+ * ploc.load();
+ * await flushPromises();
+ * expect(ploc.state.items.length).toBe(1);
+ * ```
+ */
+export declare function flushPromises(): Promise<void>;
+/**
+ * Run a callback with fake timers (if the test environment supports it).
+ * Returns the result of the callback. Does not install/uninstall timers;
+ * use your test framework's fake timers (e.g. vi.useFakeTimers()) and this
+ * to run a tick or advance time.
+ *
+ * This helper is a no-op that just runs the callback; use it as a placeholder
+ * for "run this in a fake timer context" when you pair it with vi.useFakeTimers()
+ * or jest.useFakeTimers() in the test.
+ *
+ * @example
+ * ```ts
+ * vi.useFakeTimers();
+ * const p = doSomethingAsync();
+ * await runWithFakeTimers(async () => {
+ *   vi.advanceTimersByTime(1000);
+ *   await flushPromises();
+ * });
+ * vi.useRealTimers();
+ * ```
+ */
+export declare function runWithFakeTimers<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * Minimal context for integration tests: a Ploc and a UseCase.
+ * Use when your test needs to wire a Ploc to a UseCase without a full app.
+ */
+export interface PlocUseCaseTestContext<S, A extends any[], T> {
+    ploc: Ploc<S>;
+    useCase: UseCase<A, T>;
+}
+/**
+ * Create a minimal integration context with a mock Ploc and a success-returning UseCase.
+ * Useful when testing a component or flow that expects both a Ploc and a UseCase from context.
+ *
+ * @example
+ * ```ts
+ * const { ploc, useCase } = createPlocUseCaseContext(
+ *   { items: [], loading: false },
+ *   []
+ * );
+ * // Inject into CAFProvider or pass as props
+ * ```
+ */
+export declare function createPlocUseCaseContext<S, T>(initialState: S, useCaseResult: T): PlocUseCaseTestContext<S, [], T>;

package/.build/src/core/IntegrationTestHelpers.js

@@ -0,0 +1,78 @@
+/**
+ * Integration test helpers for CAF.
+ *
+ * Utilities to run Ploc + UseCase together, flush async work, and small
+ * helpers for integration-style tests.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createPlocWithUseCase,
+ *   flushPromises,
+ *   runWithFakeTimers,
+ * } from '@c.a.f/testing/core';
+ * import { Ploc } from '@c.a.f/core';
+ *
+ * const ploc = createPlocWithUseCase(InitialState, (state, useCase) => ({ ... }));
+ * await flushPromises();
+ * ```
+ */
+import { createMockPloc } from './PlocTestHelpers';
+import { createMockUseCaseSuccess } from './UseCaseTestHelpers';
+/**
+ * Resolve all pending promises (microtasks).
+ * Call after triggering async code to wait for Promise resolution in tests.
+ *
+ * @example
+ * ```ts
+ * ploc.load();
+ * await flushPromises();
+ * expect(ploc.state.items.length).toBe(1);
+ * ```
+ */
+export function flushPromises() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+/**
+ * Run a callback with fake timers (if the test environment supports it).
+ * Returns the result of the callback. Does not install/uninstall timers;
+ * use your test framework's fake timers (e.g. vi.useFakeTimers()) and this
+ * to run a tick or advance time.
+ *
+ * This helper is a no-op that just runs the callback; use it as a placeholder
+ * for "run this in a fake timer context" when you pair it with vi.useFakeTimers()
+ * or jest.useFakeTimers() in the test.
+ *
+ * @example
+ * ```ts
+ * vi.useFakeTimers();
+ * const p = doSomethingAsync();
+ * await runWithFakeTimers(async () => {
+ *   vi.advanceTimersByTime(1000);
+ *   await flushPromises();
+ * });
+ * vi.useRealTimers();
+ * ```
+ */
+export async function runWithFakeTimers(fn) {
+    return fn();
+}
+/**
+ * Create a minimal integration context with a mock Ploc and a success-returning UseCase.
+ * Useful when testing a component or flow that expects both a Ploc and a UseCase from context.
+ *
+ * @example
+ * ```ts
+ * const { ploc, useCase } = createPlocUseCaseContext(
+ *   { items: [], loading: false },
+ *   []
+ * );
+ * // Inject into CAFProvider or pass as props
+ * ```
+ */
+export function createPlocUseCaseContext(initialState, useCaseResult) {
+    return {
+        ploc: createMockPloc(initialState),
+        useCase: createMockUseCaseSuccess(useCaseResult),
+    };
+}

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

@@ -0,0 +1,133 @@
+/**
+ * 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';
+type PlocInstance<T> = {
+    state: T;
+    changeState(state: T): void;
+    subscribe(listener: (state: T) => void): void;
+    unsubscribe(listener: (state: T) => void): void;
+};
+/**
+ * Concrete Ploc implementation for testing.
+ * Provides a Ploc with controllable state and no business logic.
+ */
+export declare class MockPloc<S> extends Ploc<S> {
+    constructor(initialState: S);
+}
+/**
+ * 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 declare function createMockPloc<S>(initialState: S): Ploc<S>;
+/**
+ * Ploc tester utility.
+ * Tracks state changes and provides testing utilities.
+ */
+export declare class PlocTester<T> {
+    readonly ploc: PlocInstance<T>;
+    private stateHistory;
+    private listener;
+    constructor(ploc: PlocInstance<T>);
+    /**
+     * Get the current state.
+     */
+    getState(): T;
+    /**
+     * Get the state history.
+     */
+    getStateHistory(): T[];
+    /**
+     * Get the initial state.
+     */
+    getInitialState(): T;
+    /**
+     * Get the last state change.
+     */
+    getLastStateChange(): T | undefined;
+    /**
+     * Get the number of state changes.
+     */
+    getStateChangeCount(): number;
+    /**
+     * Cleanup: unsubscribe from state changes.
+     */
+    cleanup(): void;
+}
+/**
+ * Create a Ploc tester instance.
+ */
+export declare function createPlocTester<T>(ploc: PlocInstance<T>): PlocTester<T>;
+/**
+ * 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 declare function waitForStateChange<T>(ploc: PlocInstance<T>, predicate: (state: T) => boolean, timeout?: number): Promise<T>;
+/**
+ * Wait for a specific number of state changes.
+ */
+export declare function waitForStateChanges<T>(ploc: PlocInstance<T>, count: number, timeout?: number): Promise<T[]>;
+/**
+ * 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 declare function assertStateHistory<T>(tester: PlocTester<T>, expected: T[]): void;
+/**
+ * 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 declare function getStateHistorySnapshot<T>(tester: PlocTester<T>): T[];
+/**
+ * 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 declare function getStateHistorySnapshotJson<T>(tester: PlocTester<T>): string;
+export {};

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 {};