@c-a-f/testing 1.0.1

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/angular/createTestPloc.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Create a Ploc instance for Angular component tests. Same as createMockPloc from core:
+ * a Ploc with controllable state and no business logic. Use with provideTestingCAF.
+ *
+ * @example
+ * ```ts
+ * import { provideTestingCAF, createTestPloc } from '@c-a-f/testing/angular';
+ *
+ * const ploc = createTestPloc({ count: 0 });
+ * TestBed.configureTestingModule({
+ *   providers: [provideTestingCAF({ plocs: { counter: ploc } })],
+ * });
+ * ```
+ */
+import type { Ploc } from '@c-a-f/core';
+/**
+ * Create a test Ploc with initial state. Use changeState() to drive state in tests.
+ */
+export declare function createTestPloc<S>(initialState: S): Ploc<S>;

package/.build/src/angular/createTestPloc.js

@@ -0,0 +1,21 @@
+/**
+ * Create a Ploc instance for Angular component tests. Same as createMockPloc from core:
+ * a Ploc with controllable state and no business logic. Use with provideTestingCAF.
+ *
+ * @example
+ * ```ts
+ * import { provideTestingCAF, createTestPloc } from '@c-a-f/testing/angular';
+ *
+ * const ploc = createTestPloc({ count: 0 });
+ * TestBed.configureTestingModule({
+ *   providers: [provideTestingCAF({ plocs: { counter: ploc } })],
+ * });
+ * ```
+ */
+import { createMockPloc } from '../core/PlocTestHelpers';
+/**
+ * Create a test Ploc with initial state. Use changeState() to drive state in tests.
+ */
+export function createTestPloc(initialState) {
+    return createMockPloc(initialState);
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Angular testing utilities for CAF.
+ *
+ * - provideTestingCAF: provide CAF context in TestBed (plocs, useCases)
+ * - createTestPloc: create a test Ploc with controllable state
+ * - waitForPlocState: wait for Ploc state to match a predicate
+ * - mockUseCase: mock UseCase (success, error, async, fn)
+ */
+export { provideTestingCAF, type ProvideTestingCAFConfig } from './provideTestingCAF';
+export { createTestPloc } from './createTestPloc';
+export { waitForPlocState } from './waitForPlocState';
+export { mockUseCase } from './mockUseCase';

package/.build/src/angular/index.js

@@ -0,0 +1,12 @@
+/**
+ * Angular testing utilities for CAF.
+ *
+ * - provideTestingCAF: provide CAF context in TestBed (plocs, useCases)
+ * - createTestPloc: create a test Ploc with controllable state
+ * - waitForPlocState: wait for Ploc state to match a predicate
+ * - mockUseCase: mock UseCase (success, error, async, fn)
+ */
+export { provideTestingCAF } from './provideTestingCAF';
+export { createTestPloc } from './createTestPloc';
+export { waitForPlocState } from './waitForPlocState';
+export { mockUseCase } from './mockUseCase';

package/.build/src/angular/mockUseCase.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Helpers to create mock UseCases for Angular component tests. Use with provideTestingCAF.
+ *
+ * @example
+ * ```ts
+ * import { provideTestingCAF, mockUseCase } from '@c-a-f/testing/angular';
+ *
+ * const submit = mockUseCase.success({ id: '1' });
+ * TestBed.configureTestingModule({
+ *   providers: [provideTestingCAF({ useCases: { submit } })],
+ * });
+ * ```
+ */
+import type { UseCase, RequestResult } from '@c-a-f/core';
+export declare const mockUseCase: {
+    /**
+     * UseCase that always returns success with the given data.
+     */
+    success<T>(data: T): UseCase<[], T>;
+    /**
+     * UseCase that always returns the given error.
+     */
+    error<T_1 = unknown>(error: Error): UseCase<[], T_1>;
+    /**
+     * UseCase that resolves with data after an optional delay (for loading-state tests).
+     */
+    async<T_2>(data: T_2, delayMs?: number): UseCase<[], T_2>;
+    /**
+     * UseCase with a custom implementation (same as createMockUseCase).
+     */
+    fn<A extends any[], T_3>(implementation: (...args: A) => RequestResult<T_3> | Promise<RequestResult<T_3>>): UseCase<A, T_3>;
+};

package/.build/src/angular/mockUseCase.js

@@ -0,0 +1,40 @@
+/**
+ * Helpers to create mock UseCases for Angular component tests. Use with provideTestingCAF.
+ *
+ * @example
+ * ```ts
+ * import { provideTestingCAF, mockUseCase } from '@c-a-f/testing/angular';
+ *
+ * const submit = mockUseCase.success({ id: '1' });
+ * TestBed.configureTestingModule({
+ *   providers: [provideTestingCAF({ useCases: { submit } })],
+ * });
+ * ```
+ */
+import { createMockUseCase, createMockUseCaseSuccess, createMockUseCaseError, createMockUseCaseAsync, } from '../core/UseCaseTestHelpers';
+export const mockUseCase = {
+    /**
+     * UseCase that always returns success with the given data.
+     */
+    success(data) {
+        return createMockUseCaseSuccess(data);
+    },
+    /**
+     * UseCase that always returns the given error.
+     */
+    error(error) {
+        return createMockUseCaseError(error);
+    },
+    /**
+     * UseCase that resolves with data after an optional delay (for loading-state tests).
+     */
+    async(data, delayMs = 0) {
+        return createMockUseCaseAsync(data, delayMs);
+    },
+    /**
+     * UseCase with a custom implementation (same as createMockUseCase).
+     */
+    fn(implementation) {
+        return createMockUseCase(implementation);
+    },
+};

package/.build/src/angular/provideTestingCAF.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Provide CAF context (Plocs/UseCases) in Angular tests. Use with TestBed:
+ *
+ * @example
+ * ```ts
+ * import { TestBed } from '@angular/core/testing';
+ * import { provideTestingCAF, createTestPloc, mockUseCase } from '@c-a-f/testing/angular';
+ *
+ * const ploc = createTestPloc({ count: 0 });
+ * await TestBed.configureTestingModule({
+ *   imports: [MyComponent],
+ *   providers: [provideTestingCAF({ plocs: { counter: ploc }, useCases: { submit: mockUseCase.success({ id: '1' }) })],
+ * }).compileComponents();
+ *
+ * const fixture = TestBed.createComponent(MyComponent);
+ * ```
+ */
+import type { Provider } from '@angular/core';
+import type { Ploc, UseCase } from '@c-a-f/core';
+export interface ProvideTestingCAFConfig {
+    plocs?: Record<string, Ploc<unknown>>;
+    useCases?: Record<string, UseCase<any[], any>>;
+}
+/**
+ * Returns Angular providers for CAF context. Use in TestBed.configureTestingModule providers.
+ * Same as provideCAF from @c-a-f/infrastructure-angular; re-exported here so tests
+ * can use a single import from @c-a-f/testing/angular.
+ */
+export declare function provideTestingCAF(config: ProvideTestingCAFConfig): Provider;

package/.build/src/angular/provideTestingCAF.js

@@ -0,0 +1,26 @@
+/**
+ * Provide CAF context (Plocs/UseCases) in Angular tests. Use with TestBed:
+ *
+ * @example
+ * ```ts
+ * import { TestBed } from '@angular/core/testing';
+ * import { provideTestingCAF, createTestPloc, mockUseCase } from '@c-a-f/testing/angular';
+ *
+ * const ploc = createTestPloc({ count: 0 });
+ * await TestBed.configureTestingModule({
+ *   imports: [MyComponent],
+ *   providers: [provideTestingCAF({ plocs: { counter: ploc }, useCases: { submit: mockUseCase.success({ id: '1' }) })],
+ * }).compileComponents();
+ *
+ * const fixture = TestBed.createComponent(MyComponent);
+ * ```
+ */
+import { provideCAF as provideCAFFromInfra } from '@c-a-f/infrastructure-angular';
+/**
+ * Returns Angular providers for CAF context. Use in TestBed.configureTestingModule providers.
+ * Same as provideCAF from @c-a-f/infrastructure-angular; re-exported here so tests
+ * can use a single import from @c-a-f/testing/angular.
+ */
+export function provideTestingCAF(config) {
+    return provideCAFFromInfra(config);
+}

package/.build/src/angular/waitForPlocState.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Wait for a Ploc to reach a state that matches a predicate. Useful in Angular tests
+ * after triggering an action that updates the Ploc asynchronously.
+ *
+ * @example
+ * ```ts
+ * import { createTestPloc, waitForPlocState } from '@c-a-f/testing/angular';
+ *
+ * const ploc = createTestPloc({ loading: true, items: [] });
+ * ploc.changeState({ loading: false, items: [{ id: '1' }] });
+ * await waitForPlocState(ploc, (state) => !state.loading && state.items.length > 0);
+ * ```
+ */
+import type { Ploc } from '@c-a-f/core';
+/**
+ * Wait until the Ploc's state satisfies the predicate (or timeout).
+ */
+export declare function waitForPlocState<S>(ploc: Ploc<S>, predicate: (state: S) => boolean, timeoutMs?: number): Promise<S>;

package/.build/src/angular/waitForPlocState.js

@@ -0,0 +1,20 @@
+/**
+ * Wait for a Ploc to reach a state that matches a predicate. Useful in Angular tests
+ * after triggering an action that updates the Ploc asynchronously.
+ *
+ * @example
+ * ```ts
+ * import { createTestPloc, waitForPlocState } from '@c-a-f/testing/angular';
+ *
+ * const ploc = createTestPloc({ loading: true, items: [] });
+ * ploc.changeState({ loading: false, items: [{ id: '1' }] });
+ * await waitForPlocState(ploc, (state) => !state.loading && state.items.length > 0);
+ * ```
+ */
+import { waitForStateChange } from '../core/PlocTestHelpers';
+/**
+ * Wait until the Ploc's state satisfies the predicate (or timeout).
+ */
+export function waitForPlocState(ploc, predicate, timeoutMs = 5000) {
+    return waitForStateChange(ploc, predicate, timeoutMs);
+}

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