@c.a.f/testing 1.0.0

package/README.md

@@ -0,0 +1,503 @@
+# @c.a.f/testing
+
+Testing utilities and helpers for CAF applications. Provides mocks, test helpers, and utilities for testing UseCase, Ploc, Pulse, Workflow, Permission, I18n, and Validation.
+
+## Installation
+
+```bash
+npm install @c.a.f/testing --save-dev
+```
+
+## Usage
+
+### Core Testing Utilities
+
+#### Testing Ploc
+
+```typescript
+import { createPlocTester, waitForStateChange } from '@c.a.f/testing/core';
+import { Ploc } from '@c.a.f/core';
+
+class CounterPloc extends Ploc<number> {
+  constructor() {
+    super(0);
+  }
+  increment() {
+    this.changeState(this.state + 1);
+  }
+}
+
+describe('CounterPloc', () => {
+  it('tracks state changes', () => {
+    const ploc = new CounterPloc();
+    const tester = createPlocTester(ploc);
+
+    ploc.increment();
+    ploc.increment();
+
+    expect(tester.getStateChangeCount()).toBe(2);
+    expect(tester.getStateHistory()).toEqual([0, 1, 2]);
+    expect(tester.getLastStateChange()).toBe(2);
+
+    tester.cleanup();
+  });
+
+  it('waits for state change', async () => {
+    const ploc = new CounterPloc();
+    
+    setTimeout(() => ploc.increment(), 100);
+    const finalState = await waitForStateChange(ploc, (state) => state === 1);
+
+    expect(finalState).toBe(1);
+  });
+});
+```
+
+#### Testing Pulse
+
+```typescript
+import { createPulseTester, waitForPulseValue } from '@c.a.f/testing/core';
+import { pulse } from '@c.a.f/core';
+
+describe('Pulse', () => {
+  it('tracks value changes', () => {
+    const count = pulse(0);
+    const tester = createPulseTester(count);
+
+    count.value = 5;
+    count.value = 10;
+
+    expect(tester.getValueChangeCount()).toBe(2);
+    expect(tester.getValueHistory()).toEqual([0, 5, 10]);
+    expect(tester.getLastValueChange()).toBe(10);
+
+    tester.cleanup();
+  });
+
+  it('waits for pulse value', async () => {
+    const count = pulse(0);
+    
+    setTimeout(() => { count.value = 5; }, 100);
+    const finalValue = await waitForPulseValue(count, (value) => value === 5);
+
+    expect(finalValue).toBe(5);
+  });
+});
+```
+
+#### Testing UseCase
+
+```typescript
+import {
+  createMockUseCase,
+  createMockUseCaseSuccess,
+  createMockUseCaseError,
+  createUseCaseTester,
+  createSuccessResult,
+} from '@c.a.f/testing/core';
+import { UseCase } from '@c.a.f/core';
+
+describe('UseCase', () => {
+  it('creates and tests mock use case', async () => {
+    const mockUseCase = createMockUseCase<[], string>(() =>
+      createSuccessResult('result')
+    );
+    const tester = createUseCaseTester(mockUseCase);
+
+    const result = await tester.execute([]);
+    expect(result.data.value).toBe('result');
+    expect(result.error.value).toBeNull();
+  });
+
+  it('uses success shortcut', async () => {
+    const useCase = createMockUseCaseSuccess([{ id: '1', name: 'John' }]);
+    const result = await useCase.execute();
+    expect(result.data.value).toEqual([{ id: '1', name: 'John' }]);
+  });
+
+  it('uses error shortcut', async () => {
+    const useCase = createMockUseCaseError(new Error('Failed'));
+    const result = await useCase.execute();
+    expect(result.error.value?.message).toBe('Failed');
+  });
+
+  it('executes and gets data', async () => {
+    const mockUseCase = createMockUseCase<[number], number>((count) =>
+      createSuccessResult(count * 2)
+    );
+    const tester = createUseCaseTester(mockUseCase);
+
+    const data = await tester.executeAndGetData([5]);
+    expect(data).toBe(10);
+  });
+});
+```
+
+#### Mock Ploc and state history (snapshot)
+
+```typescript
+import {
+  createMockPloc,
+  createPlocTester,
+  assertStateHistory,
+  getStateHistorySnapshot,
+} from '@c.a.f/testing/core';
+
+it('mock Ploc and state history', () => {
+  const ploc = createMockPloc({ count: 0 });
+  const tester = createPlocTester(ploc);
+
+  ploc.changeState({ count: 1 });
+  ploc.changeState({ count: 2 });
+
+  assertStateHistory(tester, [{ count: 0 }, { count: 1 }, { count: 2 }]);
+  expect(getStateHistorySnapshot(tester)).toMatchSnapshot();
+  tester.cleanup();
+});
+```
+
+#### Mock Repository (domain I*Repository)
+
+```typescript
+import { createMockRepository, createMockRepositoryStub } from '@c.a.f/testing/core';
+import type { IUserRepository } from '../domain';
+
+it('mocks repository', async () => {
+  const repo = createMockRepository<IUserRepository>({
+    getUsers: async () => [{ id: '1', name: 'John' }],
+    getUserById: async (id) => ({ id, name: 'User ' + id }),
+  });
+
+  expect(await repo.getUsers()).toHaveLength(1);
+  expect((await repo.getUserById('2'))?.name).toBe('User 2');
+});
+
+it('stub and spy', async () => {
+  const stub = createMockRepositoryStub<IUserRepository>();
+  stub.getUsers = vi.fn().mockResolvedValue([]);
+  await stub.getUsers();
+  expect(stub.getUsers).toHaveBeenCalledTimes(1);
+});
+```
+
+#### Integration test helpers
+
+```typescript
+import {
+  createPlocUseCaseContext,
+  flushPromises,
+} from '@c.a.f/testing/core';
+
+it('integration context', async () => {
+  const { ploc, useCase } = createPlocUseCaseContext(
+    { items: [], loading: false },
+    [{ id: '1', name: 'Item' }]
+  );
+  // Use with CAFProvider or pass as props
+  expect(ploc.state.loading).toBe(false);
+  const result = await useCase.execute();
+  expect(result.data.value).toHaveLength(1);
+  await flushPromises();
+});
+```
+
+### React Testing Utilities (`@c.a.f/testing/react`)
+
+Use these when testing React components that use `usePlocFromContext`, `useUseCaseFromContext`, or `usePloc` / `useUseCase` with context-provided instances.
+
+**Requirements:** `react` and `@testing-library/react` (peer dependencies). Install in your app:
+
+```bash
+npm install react @testing-library/react
+```
+
+#### renderWithCAF
+
+Render a component wrapped in `CAFProvider` so Ploc/UseCase context is available:
+
+```tsx
+import React from 'react';
+import { screen } from '@testing-library/react';
+import { renderWithCAF, createTestPloc, mockUseCase } from '@c.a.f/testing/react';
+import { usePlocFromContext, usePloc } from '@c.a.f/infrastructure-react';
+
+const Counter = () => {
+  const ploc = usePlocFromContext('counter');
+  if (!ploc) return null;
+  const [state] = usePloc(ploc);
+  return <span data-testid="count">{state.count}</span>;
+};
+
+it('renders with CAF context', () => {
+  const ploc = createTestPloc({ count: 5 });
+  renderWithCAF(<Counter />, { plocs: { counter: ploc } });
+  expect(screen.getByTestId('count')).toHaveTextContent('5');
+});
+```
+
+#### createTestPloc
+
+Create a Ploc with controllable state (no business logic). Same idea as `createMockPloc` from core, for use in React tests:
+
+```tsx
+const ploc = createTestPloc({ count: 0 });
+renderWithCAF(<Counter />, { plocs: { counter: ploc } });
+ploc.changeState({ count: 1 });
+expect(screen.getByTestId('count')).toHaveTextContent('1');
+```
+
+#### waitForPlocState
+
+Wait for a Ploc to reach a state matching a predicate (e.g. after an async update):
+
+```tsx
+const ploc = createTestPloc({ loading: true, items: [] });
+renderWithCAF(<List />, { plocs: { list: ploc } });
+ploc.changeState({ loading: false, items: [{ id: '1' }] });
+await waitForPlocState(ploc, (state) => !state.loading && state.items.length > 0);
+expect(screen.getByText('1')).toBeInTheDocument();
+```
+
+#### mockUseCase
+
+Create mock UseCases for context:
+
+```tsx
+const submit = mockUseCase.success({ id: '1' });
+const load = mockUseCase.error(new Error('Network error'));
+const search = mockUseCase.async([{ id: '1' }], 50); // resolves after 50ms
+
+renderWithCAF(<Form />, { useCases: { submit, load, search } });
+```
+
+- `mockUseCase.success(data)` — always returns success with `data`
+- `mockUseCase.error(error)` — always returns `error`
+- `mockUseCase.async(data, delayMs?)` — resolves with `data` after optional delay
+- `mockUseCase.fn(implementation)` — custom implementation (same as `createMockUseCase` from core)
+
+#### Testing RouteManager
+
+```typescript
+import { createMockRouteRepository, createRouteManagerTester } from '@c.a.f/testing/core';
+import { RouteManager } from '@c.a.f/core';
+
+describe('RouteManager', () => {
+  it('tracks route changes', async () => {
+    const mockRepo = createMockRouteRepository();
+    const routeManager = new RouteManager(mockRepo);
+    const tester = createRouteManagerTester(routeManager);
+
+    await tester.changeRoute('/dashboard');
+    expect(tester.getCurrentRoute()).toBe('/dashboard');
+    expect(tester.getRouteHistory()).toContain('/dashboard');
+  });
+});
+```
+
+### Workflow Testing Utilities
+
+```typescript
+import { createWorkflowTester, waitForWorkflowState } from '@c.a.f/testing/workflow';
+import { WorkflowManager, WorkflowDefinition } from '@c.a.f/workflow';
+
+describe('Workflow', () => {
+  it('tracks workflow state changes', async () => {
+    const workflow = new WorkflowManager(definition);
+    const tester = createWorkflowTester(workflow);
+
+    await tester.dispatch('approve');
+    await waitForWorkflowState(workflow, 'approved');
+
+    expect(tester.getCurrentState()).toBe('approved');
+    expect(tester.getStateHistory().length).toBeGreaterThan(1);
+
+    tester.cleanup();
+  });
+
+  it('waits for final state', async () => {
+    const workflow = new WorkflowManager(definition);
+    
+    await workflow.dispatch('complete');
+    const finalState = await waitForFinalState(workflow);
+
+    expect(finalState.isFinal).toBe(true);
+  });
+});
+```
+
+### Permission Testing Utilities
+
+```typescript
+import { createMockPermissionChecker, createPermissionTester } from '@c.a.f/testing/permission';
+import { PermissionManager } from '@c.a.f/permission';
+
+describe('Permission', () => {
+  it('tests permission checking', async () => {
+    const mockChecker = createMockPermissionChecker(['user.edit', 'post.create']);
+    const manager = new PermissionManager(mockChecker);
+    const tester = createPermissionTester(manager);
+
+    expect(await tester.hasPermission('user.edit')).toBe(true);
+    expect(await tester.hasPermission('user.delete')).toBe(false);
+    expect(await tester.hasAnyPermission(['user.edit', 'user.delete'])).toBe(true);
+  });
+
+  it('modifies permissions dynamically', () => {
+    const mockChecker = createMockPermissionChecker(['user.view']);
+    
+    mockChecker.addPermission('user.edit');
+    expect(mockChecker.check('user.edit').granted).toBe(true);
+
+    mockChecker.removePermission('user.view');
+    expect(mockChecker.check('user.view').granted).toBe(false);
+  });
+});
+```
+
+### I18n Testing Utilities
+
+```typescript
+import { createMockTranslator, createTranslationTester } from '@c.a.f/testing/i18n';
+import { TranslationManager } from '@c.a.f/i18n';
+
+describe('I18n', () => {
+  it('tests translation', () => {
+    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');
+    expect(tester.translateWithValues('welcome', { name: 'John' })).toBe('Welcome John');
+  });
+
+  it('tests language switching', async () => {
+    const mockTranslator = createMockTranslator({
+      en: { greeting: 'Hello' },
+      fa: { greeting: 'سلام' },
+    });
+    const manager = new TranslationManager(mockTranslator);
+    const tester = createTranslationTester(manager);
+
+    expect(tester.getCurrentLanguage()).toBe('en');
+    await tester.changeLanguage('fa');
+    expect(tester.getCurrentLanguage()).toBe('fa');
+    expect(tester.t('greeting')).toBe('سلام');
+  });
+});
+```
+
+### Validation Testing Utilities
+
+```typescript
+import { createMockValidator, createValidationTester } from '@c.a.f/testing/validation';
+
+describe('Validation', () => {
+  it('tests validation', async () => {
+    const mockValidator = createMockValidator((data: any) => {
+      return data.email && data.email.includes('@');
+    });
+    const tester = createValidationTester(mockValidator);
+
+    const successResult = await tester.expectSuccess({ email: 'test@example.com' });
+    expect(successResult.email).toBe('test@example.com');
+
+    const errors = await tester.expectFailure({ email: 'invalid' });
+    expect(errors.length).toBeGreaterThan(0);
+  });
+});
+```
+
+## Exports
+
+### Core Testing (`@c.a.f/testing/core`)
+
+- `PlocTester` — Tester for Ploc instances
+- `createPlocTester` — Create a Ploc tester
+- `createMockPloc` — Create a Ploc with controllable state (no logic)
+- `MockPloc` — Concrete Ploc class for tests
+- `waitForStateChange` — Wait for state change matching predicate
+- `waitForStateChanges` — Wait for specific number of state changes
+- `assertStateHistory` — Assert state history matches expected (snapshot-style)
+- `getStateHistorySnapshot` / `getStateHistorySnapshotJson` — Snapshot state history
+- `PulseTester` — Tester for Pulse instances
+- `createPulseTester` — Create a Pulse tester
+- `waitForPulseValue` — Wait for pulse value matching predicate
+- `MockUseCase` — Mock UseCase implementation
+- `createMockUseCase` — Create a mock UseCase
+- `createMockUseCaseSuccess` — Mock UseCase that returns success with data
+- `createMockUseCaseError` — Mock UseCase that returns an error
+- `createMockUseCaseAsync` — Mock UseCase that resolves after optional delay
+- `UseCaseTester` — Tester for UseCase instances
+- `createUseCaseTester` — Create a UseCase tester
+- `createSuccessResult` — Create successful RequestResult
+- `createErrorResult` — Create failed RequestResult
+- `createLoadingResult` — Create loading RequestResult
+- `createMockRepository` — Generic stub for domain I*Repository interfaces
+- `createMockRepositoryStub` — Empty repository stub (assign or spy methods)
+- `flushPromises` — Resolve pending microtasks in integration tests
+- `runWithFakeTimers` — Placeholder for running code with fake timers
+- `createPlocUseCaseContext` — Minimal Ploc + UseCase context for integration tests
+- `MockRouteRepository` — Mock RouteRepository implementation
+- `createMockRouteRepository` — Create a mock RouteRepository
+- `RouteManagerTester` — Tester for RouteManager instances
+- `createRouteManagerTester` — Create a RouteManager tester
+
+### Workflow Testing (`@c.a.f/testing/workflow`)
+
+- `WorkflowTester` — Tester for WorkflowManager instances
+- `createWorkflowTester` — Create a Workflow tester
+- `waitForWorkflowState` — Wait for workflow to reach specific state
+- `waitForFinalState` — Wait for workflow to reach final state
+
+### Permission Testing (`@c.a.f/testing/permission`)
+
+- `MockPermissionChecker` — Mock PermissionChecker implementation
+- `createMockPermissionChecker` — Create a mock PermissionChecker
+- `PermissionTester` — Tester for PermissionManager instances
+- `createPermissionTester` — Create a Permission tester
+
+### I18n Testing (`@c.a.f/testing/i18n`)
+
+- `MockTranslator` — Mock Translator implementation
+- `createMockTranslator` — Create a mock Translator
+- `TranslationTester` — Tester for TranslationManager instances
+- `createTranslationTester` — Create a Translation tester
+
+### Validation Testing (`@c.a.f/testing/validation`)
+
+- `MockValidator` — Mock Validator implementation
+- `createMockValidator` — Create a mock Validator
+- `ValidationTester` — Tester for Validator instances
+- `createValidationTester` — Create a Validation tester
+- `expectSuccess` — Validate and expect success
+- `expectFailure` — Validate and expect failure
+
+### React Testing (`@c.a.f/testing/react`)
+
+- `renderWithCAF` — Render with CAFProvider (Ploc/UseCase context)
+- `RenderWithCAFOptions` — Options for renderWithCAF (plocs, useCases, and RTL options)
+- `createTestPloc` — Create a test Ploc with controllable state
+- `waitForPlocState` — Wait for Ploc state to match a predicate
+- `mockUseCase` — Mock UseCase helpers: `success`, `error`, `async`, `fn`
+
+## Dependencies
+
+- `@c.a.f/core` — Core primitives
+- `@c.a.f/infrastructure-react` — React provider (for `@c.a.f/testing/react`)
+- `@c.a.f/workflow` — Workflow package (for workflow testing utilities)
+- `@c.a.f/permission` — Permission package (for permission testing utilities)
+- `@c.a.f/i18n` — I18n package (for i18n testing utilities)
+- `@c.a.f/validation` — Validation package (for validation testing utilities)
+
+**React testing (`@c.a.f/testing/react`):** Peer dependencies `react` and `@testing-library/react` (optional; required only when using the react entry point).
+
+## Dev Dependencies
+
+- `vitest` — Testing framework (optional, works with any testing framework)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@c.a.f/testing",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Testing utilities and helpers for CAF applications. Provides mocks, test helpers, and utilities for testing UseCase, Ploc, Pulse, Workflow, Permission, I18n, and Validation.",
+  "keywords": ["clean-architecture-frontend", "clean-architecture", "caf", "testing", "test-utils", "mocks", "test-helpers"],
+  "author": "ali aslani <aliaslani.mm@gmail.com>",
+  "license": "MIT",
+  "repository": "https://github.com/ialiaslani/caf.git",
+  "main": "./.build/index.js",
+  "module": "./.build/index.js",
+  "types": "./.build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./.build/index.d.ts",
+      "import": "./.build/index.js",
+      "node": "./.build/index.js",
+      "default": "./.build/index.js"
+    },
+    "./core": {
+      "types": "./.build/core/index.d.ts",
+      "import": "./.build/core/index.js",
+      "node": "./.build/core/index.js",
+      "default": "./.build/core/index.js"
+    },
+    "./workflow": {
+      "types": "./.build/workflow/index.d.ts",
+      "import": "./.build/workflow/index.js",
+      "node": "./.build/workflow/index.js",
+      "default": "./.build/workflow/index.js"
+    },
+    "./permission": {
+      "types": "./.build/permission/index.d.ts",
+      "import": "./.build/permission/index.js",
+      "node": "./.build/permission/index.js",
+      "default": "./.build/permission/index.js"
+    },
+    "./i18n": {
+      "types": "./.build/i18n/index.d.ts",
+      "import": "./.build/i18n/index.js",
+      "node": "./.build/i18n/index.js",
+      "default": "./.build/i18n/index.js"
+    },
+    "./validation": {
+      "types": "./.build/validation/index.d.ts",
+      "import": "./.build/validation/index.js",
+      "node": "./.build/validation/index.js",
+      "default": "./.build/validation/index.js"
+    },
+    "./react": {
+      "types": "./.build/react/index.d.ts",
+      "import": "./.build/react/index.js",
+      "node": "./.build/react/index.js",
+      "default": "./.build/react/index.js"
+    }
+  },
+  "files": [".build"],
+  "scripts": {
+    "build": "tsc --build",
+    "start": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@c.a.f/core": "1.0.3",
+    "@c.a.f/infrastructure-react": "^1.0.4",
+    "@c.a.f/workflow": "1.0.1",
+    "@c.a.f/permission": "1.0.0",
+    "@c.a.f/i18n": "1.0.0",
+    "@c.a.f/validation": "1.0.3"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "@testing-library/react": ">=14.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "@testing-library/react": { "optional": true }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.0.0",
+    "happy-dom": "^15.11.7",
+    "react": "^18.2.0",
+    "vitest": "^2.1.0"
+  }
+}