@c.a.f/testing 1.0.0

package/.build/src/i18n/I18nTestHelpers.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Test helpers for I18n.
+ *
+ * Provides utilities for testing translation managers and translators.
+ *
+ * @example
+ * ```ts
+ * import { createMockTranslator, createTranslationTester } from '@c.a.f/testing/i18n';
+ * import { TranslationManager } from '@c.a.f/i18n';
+ *
+ * const mockTranslator = createMockTranslator({
+ *   en: { 'greeting': 'Hello', 'welcome': 'Welcome {{name}}' },
+ *   fa: { 'greeting': 'سلام', 'welcome': 'خوش آمدید {{name}}' },
+ * });
+ * const manager = new TranslationManager(mockTranslator);
+ * const tester = createTranslationTester(manager);
+ *
+ * expect(tester.t('greeting')).toBe('Hello');
+ * ```
+ */
+import type { ITranslator, TranslationManager } from '@c.a.f/i18n';
+/**
+ * Mock Translator implementation for testing.
+ */
+export declare class MockTranslator implements ITranslator {
+    private translations;
+    private currentLanguage;
+    constructor(translations?: Record<string, Record<string, string>>, currentLanguage?: string);
+    translate(key: string, options?: Record<string, unknown>): string;
+    getCurrentLanguage(): string;
+    changeLanguage(language: string): Promise<void>;
+    exists(key: string): boolean;
+    /**
+     * Add translations (for testing).
+     */
+    addTranslations(language: string, translations: Record<string, string>): void;
+}
+/**
+ * Create a mock Translator.
+ */
+export declare function createMockTranslator(translations?: Record<string, Record<string, string>>, initialLanguage?: string): MockTranslator;
+/**
+ * Translation tester utility.
+ */
+export declare class TranslationTester {
+    readonly manager: TranslationManager;
+    constructor(manager: TranslationManager);
+    /**
+     * Translate a key.
+     */
+    t(key: string, options?: Record<string, unknown>): string;
+    /**
+     * Translate with values.
+     */
+    translateWithValues(key: string, values: Record<string, unknown>): string;
+    /**
+     * Translate plural.
+     */
+    translatePlural(key: string, count: number, options?: Record<string, unknown>): string;
+    /**
+     * Get current language.
+     */
+    getCurrentLanguage(): string;
+    /**
+     * Change language.
+     */
+    changeLanguage(language: string): Promise<void>;
+    /**
+     * Check if key exists.
+     */
+    hasKey(key: string): boolean;
+}
+/**
+ * Create a Translation tester instance.
+ */
+export declare function createTranslationTester(manager: TranslationManager): TranslationTester;

package/.build/src/i18n/I18nTestHelpers.js

@@ -0,0 +1,122 @@
+/**
+ * Test helpers for I18n.
+ *
+ * Provides utilities for testing translation managers and translators.
+ *
+ * @example
+ * ```ts
+ * import { createMockTranslator, createTranslationTester } from '@c.a.f/testing/i18n';
+ * import { TranslationManager } from '@c.a.f/i18n';
+ *
+ * const mockTranslator = createMockTranslator({
+ *   en: { 'greeting': 'Hello', 'welcome': 'Welcome {{name}}' },
+ *   fa: { 'greeting': 'سلام', 'welcome': 'خوش آمدید {{name}}' },
+ * });
+ * const manager = new TranslationManager(mockTranslator);
+ * const tester = createTranslationTester(manager);
+ *
+ * expect(tester.t('greeting')).toBe('Hello');
+ * ```
+ */
+/**
+ * Mock Translator implementation for testing.
+ */
+export class MockTranslator {
+    translations;
+    currentLanguage;
+    constructor(translations = {}, currentLanguage = 'en') {
+        this.translations = translations;
+        this.currentLanguage = currentLanguage;
+    }
+    translate(key, options) {
+        const langTranslations = this.translations[this.currentLanguage] || {};
+        let text = langTranslations[key] || key;
+        // Simple interpolation
+        if (options) {
+            Object.keys(options).forEach((k) => {
+                if (k !== 'ns' && k !== 'defaultValue' && k !== 'count' && k !== 'returnObjects') {
+                    const value = String(options[k]);
+                    text = text.replace(new RegExp(`{{${k}}}`, 'g'), value);
+                    text = text.replace(new RegExp(`\\{${k}\\}`, 'g'), value);
+                }
+            });
+        }
+        return text;
+    }
+    getCurrentLanguage() {
+        return this.currentLanguage;
+    }
+    async changeLanguage(language) {
+        this.currentLanguage = language;
+    }
+    exists(key) {
+        const langTranslations = this.translations[this.currentLanguage] || {};
+        return key in langTranslations;
+    }
+    /**
+     * Add translations (for testing).
+     */
+    addTranslations(language, translations) {
+        if (!this.translations[language]) {
+            this.translations[language] = {};
+        }
+        this.translations[language] = { ...this.translations[language], ...translations };
+    }
+}
+/**
+ * Create a mock Translator.
+ */
+export function createMockTranslator(translations = {}, initialLanguage = 'en') {
+    return new MockTranslator(translations, initialLanguage);
+}
+/**
+ * Translation tester utility.
+ */
+export class TranslationTester {
+    manager;
+    constructor(manager) {
+        this.manager = manager;
+    }
+    /**
+     * Translate a key.
+     */
+    t(key, options) {
+        return this.manager.t(key, options);
+    }
+    /**
+     * Translate with values.
+     */
+    translateWithValues(key, values) {
+        return this.manager.translateWithValues(key, values);
+    }
+    /**
+     * Translate plural.
+     */
+    translatePlural(key, count, options) {
+        return this.manager.translatePlural(key, count, options);
+    }
+    /**
+     * Get current language.
+     */
+    getCurrentLanguage() {
+        return this.manager.getCurrentLanguage();
+    }
+    /**
+     * Change language.
+     */
+    async changeLanguage(language) {
+        await this.manager.changeLanguage(language);
+    }
+    /**
+     * Check if key exists.
+     */
+    hasKey(key) {
+        return this.manager.hasKey(key);
+    }
+}
+/**
+ * Create a Translation tester instance.
+ */
+export function createTranslationTester(manager) {
+    return new TranslationTester(manager);
+}

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

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

package/.build/src/i18n/index.js

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

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

@@ -0,0 +1,5 @@
+export * from './core';
+export * from './workflow';
+export * from './permission';
+export * from './i18n';
+export * from './validation';

package/.build/src/index.js

@@ -0,0 +1,10 @@
+// Core testing utilities
+export * from './core';
+// Workflow testing utilities
+export * from './workflow';
+// Permission testing utilities
+export * from './permission';
+// I18n testing utilities
+export * from './i18n';
+// Validation testing utilities
+export * from './validation';

package/.build/src/permission/PermissionTestHelpers.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Test helpers for Permission.
+ *
+ * Provides utilities for testing permission checkers and managers.
+ *
+ * @example
+ * ```ts
+ * import { createMockPermissionChecker, createPermissionTester } from '@c.a.f/testing/permission';
+ * import { PermissionManager } from '@c.a.f/permission';
+ *
+ * const mockChecker = createMockPermissionChecker(['user.edit', 'post.create']);
+ * const manager = new PermissionManager(mockChecker);
+ * const tester = createPermissionTester(manager);
+ *
+ * expect(await tester.hasPermission('user.edit')).toBe(true);
+ * ```
+ */
+import type { IPermissionChecker, PermissionResult, PermissionManager } from '@c.a.f/permission';
+/**
+ * Mock PermissionChecker implementation for testing.
+ */
+export declare class MockPermissionChecker implements IPermissionChecker {
+    private allowedPermissions;
+    constructor(allowedPermissions?: string[]);
+    check(permission: string): PermissionResult;
+    checkAny(permissions: string[]): PermissionResult;
+    checkAll(permissions: string[]): PermissionResult;
+    /**
+     * Add a permission (for testing).
+     */
+    addPermission(permission: string): void;
+    /**
+     * Remove a permission (for testing).
+     */
+    removePermission(permission: string): void;
+}
+/**
+ * Create a mock PermissionChecker.
+ */
+export declare function createMockPermissionChecker(allowedPermissions?: string[]): MockPermissionChecker;
+/**
+ * Permission tester utility.
+ */
+export declare class PermissionTester {
+    readonly manager: PermissionManager;
+    constructor(manager: PermissionManager);
+    /**
+     * Check if permission is granted.
+     */
+    hasPermission(permission: string): Promise<boolean>;
+    /**
+     * Check if any permission is granted.
+     */
+    hasAnyPermission(permissions: string[]): Promise<boolean>;
+    /**
+     * Check if all permissions are granted.
+     */
+    hasAllPermissions(permissions: string[]): Promise<boolean>;
+    /**
+     * Require permission (throws if denied).
+     */
+    requirePermission(permission: string): Promise<void>;
+    /**
+     * Require any permission (throws if all denied).
+     */
+    requireAnyPermission(permissions: string[]): Promise<void>;
+    /**
+     * Require all permissions (throws if any denied).
+     */
+    requireAllPermissions(permissions: string[]): Promise<void>;
+}
+/**
+ * Create a Permission tester instance.
+ */
+export declare function createPermissionTester(manager: PermissionManager): PermissionTester;

package/.build/src/permission/PermissionTestHelpers.js

@@ -0,0 +1,121 @@
+/**
+ * Test helpers for Permission.
+ *
+ * Provides utilities for testing permission checkers and managers.
+ *
+ * @example
+ * ```ts
+ * import { createMockPermissionChecker, createPermissionTester } from '@c.a.f/testing/permission';
+ * import { PermissionManager } from '@c.a.f/permission';
+ *
+ * const mockChecker = createMockPermissionChecker(['user.edit', 'post.create']);
+ * const manager = new PermissionManager(mockChecker);
+ * const tester = createPermissionTester(manager);
+ *
+ * expect(await tester.hasPermission('user.edit')).toBe(true);
+ * ```
+ */
+/**
+ * Mock PermissionChecker implementation for testing.
+ */
+export class MockPermissionChecker {
+    allowedPermissions;
+    constructor(allowedPermissions = []) {
+        this.allowedPermissions = allowedPermissions;
+    }
+    check(permission) {
+        const granted = this.allowedPermissions.includes(permission);
+        return {
+            granted,
+            reason: granted ? undefined : `Permission '${permission}' not granted`,
+        };
+    }
+    checkAny(permissions) {
+        const granted = permissions.some(p => this.allowedPermissions.includes(p));
+        return {
+            granted,
+            reason: granted ? undefined : 'None of the permissions are granted',
+        };
+    }
+    checkAll(permissions) {
+        const missing = permissions.filter(p => !this.allowedPermissions.includes(p));
+        return {
+            granted: missing.length === 0,
+            reason: missing.length > 0 ? `Missing permissions: ${missing.join(', ')}` : undefined,
+        };
+    }
+    /**
+     * Add a permission (for testing).
+     */
+    addPermission(permission) {
+        if (!this.allowedPermissions.includes(permission)) {
+            this.allowedPermissions.push(permission);
+        }
+    }
+    /**
+     * Remove a permission (for testing).
+     */
+    removePermission(permission) {
+        const index = this.allowedPermissions.indexOf(permission);
+        if (index > -1) {
+            this.allowedPermissions.splice(index, 1);
+        }
+    }
+}
+/**
+ * Create a mock PermissionChecker.
+ */
+export function createMockPermissionChecker(allowedPermissions = []) {
+    return new MockPermissionChecker(allowedPermissions);
+}
+/**
+ * Permission tester utility.
+ */
+export class PermissionTester {
+    manager;
+    constructor(manager) {
+        this.manager = manager;
+    }
+    /**
+     * Check if permission is granted.
+     */
+    async hasPermission(permission) {
+        return await this.manager.hasPermission(permission);
+    }
+    /**
+     * Check if any permission is granted.
+     */
+    async hasAnyPermission(permissions) {
+        return await this.manager.hasAnyPermission(permissions);
+    }
+    /**
+     * Check if all permissions are granted.
+     */
+    async hasAllPermissions(permissions) {
+        return await this.manager.hasAllPermissions(permissions);
+    }
+    /**
+     * Require permission (throws if denied).
+     */
+    async requirePermission(permission) {
+        await this.manager.requirePermission(permission);
+    }
+    /**
+     * Require any permission (throws if all denied).
+     */
+    async requireAnyPermission(permissions) {
+        await this.manager.requireAnyPermission(permissions);
+    }
+    /**
+     * Require all permissions (throws if any denied).
+     */
+    async requireAllPermissions(permissions) {
+        await this.manager.requireAllPermissions(permissions);
+    }
+}
+/**
+ * Create a Permission tester instance.
+ */
+export function createPermissionTester(manager) {
+    return new PermissionTester(manager);
+}

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

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

package/.build/src/permission/index.js

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

package/.build/src/react/createTestPloc.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Create a Ploc instance for React component tests. Same as createMockPloc from core:
+ * a Ploc with controllable state and no business logic. Use with renderWithCAF.
+ *
+ * @example
+ * ```tsx
+ * import { createTestPloc, renderWithCAF } from '@c.a.f/testing/react';
+ *
+ * const ploc = createTestPloc({ count: 0 });
+ * const { getByRole } = renderWithCAF(<Counter />, { plocs: { counter: ploc } });
+ * ploc.changeState({ count: 1 });
+ * expect(screen.getByText('1')).toBeInTheDocument();
+ * ```
+ */
+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/react/createTestPloc.js

@@ -0,0 +1,21 @@
+/**
+ * Create a Ploc instance for React component tests. Same as createMockPloc from core:
+ * a Ploc with controllable state and no business logic. Use with renderWithCAF.
+ *
+ * @example
+ * ```tsx
+ * import { createTestPloc, renderWithCAF } from '@c.a.f/testing/react';
+ *
+ * const ploc = createTestPloc({ count: 0 });
+ * const { getByRole } = renderWithCAF(<Counter />, { plocs: { counter: ploc } });
+ * ploc.changeState({ count: 1 });
+ * expect(screen.getByText('1')).toBeInTheDocument();
+ * ```
+ */
+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/react/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * React testing utilities for CAF.
+ *
+ * - renderWithCAF: render with CAFProvider (Ploc/UseCase context)
+ * - 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 { renderWithCAF, type RenderWithCAFOptions } from './renderWithCAF';
+export { createTestPloc } from './createTestPloc';
+export { waitForPlocState } from './waitForPlocState';
+export { mockUseCase } from './mockUseCase';

package/.build/src/react/index.js

@@ -0,0 +1,12 @@
+/**
+ * React testing utilities for CAF.
+ *
+ * - renderWithCAF: render with CAFProvider (Ploc/UseCase context)
+ * - 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 { renderWithCAF } from './renderWithCAF';
+export { createTestPloc } from './createTestPloc';
+export { waitForPlocState } from './waitForPlocState';
+export { mockUseCase } from './mockUseCase';

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

@@ -0,0 +1,36 @@
+/**
+ * Helpers to create mock UseCases for React component tests. Use with renderWithCAF.
+ *
+ * @example
+ * ```tsx
+ * import { renderWithCAF, mockUseCase } from '@c.a.f/testing/react';
+ *
+ * const submit = mockUseCase.success({ id: '1' });
+ * renderWithCAF(<Form />, { useCases: { submit } });
+ *
+ * // Or error
+ * const load = mockUseCase.error(new Error('Network error'));
+ *
+ * // Or custom implementation
+ * const search = mockUseCase.fn((query: string) => createSuccessResult([{ id: '1', title: query }]));
+ * ```
+ */
+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/react/mockUseCase.js

@@ -0,0 +1,44 @@
+/**
+ * Helpers to create mock UseCases for React component tests. Use with renderWithCAF.
+ *
+ * @example
+ * ```tsx
+ * import { renderWithCAF, mockUseCase } from '@c.a.f/testing/react';
+ *
+ * const submit = mockUseCase.success({ id: '1' });
+ * renderWithCAF(<Form />, { useCases: { submit } });
+ *
+ * // Or error
+ * const load = mockUseCase.error(new Error('Network error'));
+ *
+ * // Or custom implementation
+ * const search = mockUseCase.fn((query: string) => createSuccessResult([{ id: '1', title: query }]));
+ * ```
+ */
+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/react/renderWithCAF.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Render a React component with CAFProvider so that usePlocFromContext and
+ * useUseCaseFromContext work. Use this instead of raw render() when testing
+ * components that depend on CAF context.
+ *
+ * @example
+ * ```tsx
+ * import { renderWithCAF, createTestPloc, mockUseCase } from '@c.a.f/testing/react';
+ *
+ * const ploc = createTestPloc({ count: 0 });
+ * const { getByRole } = renderWithCAF(<Counter />, {
+ *   plocs: { counter: ploc },
+ *   useCases: { submit: mockUseCase.success({ id: '1' }) },
+ * });
+ * ```
+ */
+import { type ReactElement } from 'react';
+import { type RenderOptions, type RenderResult } from '@testing-library/react';
+import type { Ploc } from '@c.a.f/core';
+import type { UseCase } from '@c.a.f/core';
+export interface RenderWithCAFOptions extends Omit<RenderOptions, 'wrapper'> {
+    /** Plocs to provide (keyed by string). */
+    plocs?: Record<string, Ploc<unknown>>;
+    /** UseCases to provide (keyed by string). */
+    useCases?: Record<string, UseCase<any[], any>>;
+}
+/**
+ * Render a component with CAFProvider so Ploc/UseCase context is available.
+ * Returns the same result as React Testing Library's render().
+ */
+export declare function renderWithCAF(ui: ReactElement, options?: RenderWithCAFOptions): RenderResult;

package/.build/src/react/renderWithCAF.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from '@testing-library/react';
+import { CAFProvider } from '@c.a.f/infrastructure-react';
+/**
+ * Wrapper that provides CAFProvider around the component tree.
+ */
+function createCAFWrapper(plocs, useCases) {
+    return function Wrapper({ children }) {
+        return (_jsx(CAFProvider, { plocs: plocs ?? {}, useCases: useCases ?? {}, children: children }));
+    };
+}
+/**
+ * Render a component with CAFProvider so Ploc/UseCase context is available.
+ * Returns the same result as React Testing Library's render().
+ */
+export function renderWithCAF(ui, options = {}) {
+    const { plocs, useCases, ...renderOptions } = options;
+    const Wrapper = createCAFWrapper(plocs, useCases);
+    return render(ui, {
+        ...renderOptions,
+        wrapper: Wrapper,
+    });
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Wait for a Ploc to reach a state that matches a predicate. Useful in React tests
+ * after triggering an action that updates the Ploc asynchronously.
+ *
+ * @example
+ * ```tsx
+ * import { renderWithCAF, createTestPloc, waitForPlocState } from '@c.a.f/testing/react';
+ *
+ * const ploc = createTestPloc({ loading: true, items: [] });
+ * renderWithCAF(<List />, { plocs: { list: ploc } });
+ *
+ * // Simulate load complete
+ * ploc.changeState({ loading: false, items: [{ id: '1' }] });
+ * await waitForPlocState(ploc, (state) => !state.loading && state.items.length > 0);
+ * expect(screen.getByText('1')).toBeInTheDocument();
+ * ```
+ */
+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/react/waitForPlocState.js

@@ -0,0 +1,24 @@
+/**
+ * Wait for a Ploc to reach a state that matches a predicate. Useful in React tests
+ * after triggering an action that updates the Ploc asynchronously.
+ *
+ * @example
+ * ```tsx
+ * import { renderWithCAF, createTestPloc, waitForPlocState } from '@c.a.f/testing/react';
+ *
+ * const ploc = createTestPloc({ loading: true, items: [] });
+ * renderWithCAF(<List />, { plocs: { list: ploc } });
+ *
+ * // Simulate load complete
+ * ploc.changeState({ loading: false, items: [{ id: '1' }] });
+ * await waitForPlocState(ploc, (state) => !state.loading && state.items.length > 0);
+ * expect(screen.getByText('1')).toBeInTheDocument();
+ * ```
+ */
+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);
+}