@sparkleideas/testing 3.0.0-alpha.10

package/src/helpers/assertions.ts

@@ -0,0 +1,286 @@
+/**
+ * V3 Claude-Flow Custom Assertions
+ *
+ * London School TDD Custom Assertions
+ * - Behavior-focused assertions
+ * - Interaction verification helpers
+ * - Contract testing utilities
+ */
+import { expect, type Mock } from 'vitest';
+
+/**
+ * Assert that a mock was called in a specific sequence
+ *
+ * @example
+ * assertCallSequence([
+ *   [mockRepo.findById, ['123']],
+ *   [mockValidator.validate, [user]],
+ *   [mockRepo.save, [user]],
+ * ]);
+ */
+export function assertCallSequence(
+  sequence: Array<[Mock, unknown[]]>
+): void {
+  const calls: Array<{ mock: Mock; args: unknown[]; order: number }> = [];
+
+  for (const [mock, expectedArgs] of sequence) {
+    const mockCalls = mock.mock.calls;
+    const invocationOrder = mock.mock.invocationCallOrder;
+
+    for (let i = 0; i < mockCalls.length; i++) {
+      if (JSON.stringify(mockCalls[i]) === JSON.stringify(expectedArgs)) {
+        calls.push({
+          mock,
+          args: mockCalls[i],
+          order: invocationOrder[i],
+        });
+        break;
+      }
+    }
+  }
+
+  expect(calls.length).toBe(sequence.length);
+
+  for (let i = 1; i < calls.length; i++) {
+    expect(calls[i].order).toBeGreaterThan(calls[i - 1].order);
+  }
+}
+
+/**
+ * Assert that a mock was NOT called with specific arguments
+ *
+ * @example
+ * assertNotCalledWith(mockRepo.save, [invalidUser]);
+ */
+export function assertNotCalledWith(mock: Mock, args: unknown[]): void {
+  const wasCalledWith = mock.mock.calls.some(
+    (call: unknown[]) => JSON.stringify(call) === JSON.stringify(args)
+  );
+  expect(wasCalledWith).toBe(false);
+}
+
+/**
+ * Assert interaction count for behavior verification
+ *
+ * @example
+ * assertInteractionCount(mockService.process, 3);
+ */
+export function assertInteractionCount(mock: Mock, expectedCount: number): void {
+  expect(mock.mock.calls.length).toBe(expectedCount);
+}
+
+/**
+ * Assert that all mocks in a group were called
+ *
+ * @example
+ * assertAllCalled([mockA.method, mockB.method, mockC.method]);
+ */
+export function assertAllCalled(mocks: Mock[]): void {
+  for (const mock of mocks) {
+    expect(mock).toHaveBeenCalled();
+  }
+}
+
+/**
+ * Assert that none of the mocks were called
+ *
+ * @example
+ * assertNoneCalled([mockA.method, mockB.method]);
+ */
+export function assertNoneCalled(mocks: Mock[]): void {
+  for (const mock of mocks) {
+    expect(mock).not.toHaveBeenCalled();
+  }
+}
+
+/**
+ * Assert contract compliance
+ * Verifies that an object implements expected interface
+ *
+ * @example
+ * assertContractCompliance(userService, UserServiceContract);
+ */
+export function assertContractCompliance<T extends object>(
+  implementation: T,
+  contract: ContractDefinition<T>
+): void {
+  for (const [method, spec] of Object.entries(contract.methods)) {
+    expect(typeof (implementation as Record<string, unknown>)[method]).toBe('function');
+  }
+}
+
+/**
+ * Contract definition for interface compliance
+ */
+export interface ContractDefinition<T> {
+  methods: {
+    [K in keyof T]?: {
+      params: Array<{ name: string; type: string }>;
+      returns: string;
+    };
+  };
+}
+
+/**
+ * Assert async operation timing
+ *
+ * @example
+ * await assertTimingWithin(async () => service.process(), 100);
+ */
+export async function assertTimingWithin(
+  operation: () => Promise<unknown>,
+  maxMs: number
+): Promise<void> {
+  const start = Date.now();
+  await operation();
+  const duration = Date.now() - start;
+  expect(duration).toBeLessThanOrEqual(maxMs);
+}
+
+/**
+ * Assert that an async operation completes within expected time range
+ *
+ * @example
+ * await assertTimingRange(async () => service.process(), 50, 150);
+ */
+export async function assertTimingRange(
+  operation: () => Promise<unknown>,
+  minMs: number,
+  maxMs: number
+): Promise<void> {
+  const start = Date.now();
+  await operation();
+  const duration = Date.now() - start;
+  expect(duration).toBeGreaterThanOrEqual(minMs);
+  expect(duration).toBeLessThanOrEqual(maxMs);
+}
+
+/**
+ * Assert error type and message
+ *
+ * @example
+ * await assertThrowsWithMessage(
+ *   async () => service.validate(invalid),
+ *   ValidationError,
+ *   'Invalid input'
+ * );
+ */
+export async function assertThrowsWithMessage(
+  operation: () => Promise<unknown>,
+  ErrorType: new (...args: unknown[]) => Error,
+  expectedMessage: string | RegExp
+): Promise<void> {
+  let error: Error | null = null;
+
+  try {
+    await operation();
+  } catch (e) {
+    error = e as Error;
+  }
+
+  expect(error).toBeInstanceOf(ErrorType);
+  if (typeof expectedMessage === 'string') {
+    expect(error?.message).toContain(expectedMessage);
+  } else {
+    expect(error?.message).toMatch(expectedMessage);
+  }
+}
+
+/**
+ * Assert domain event was published
+ *
+ * @example
+ * await assertEventPublished(mockEventBus, 'UserCreated', { userId: '123' });
+ */
+export function assertEventPublished(
+  eventBusMock: Mock,
+  eventType: string,
+  expectedPayload?: Record<string, unknown>
+): void {
+  const publishCalls = eventBusMock.mock.calls;
+
+  const matchingEvent = publishCalls.find((call: unknown[]) => {
+    const event = call[0] as { type: string; payload: unknown };
+    return event.type === eventType;
+  });
+
+  expect(matchingEvent).toBeDefined();
+
+  if (expectedPayload && matchingEvent) {
+    const actualPayload = (matchingEvent[0] as { payload: unknown }).payload;
+    expect(actualPayload).toMatchObject(expectedPayload);
+  }
+}
+
+/**
+ * Assert that mock returns expected values in sequence
+ *
+ * @example
+ * assertMockSequence(mockCounter.next, [1, 2, 3]);
+ */
+export async function assertMockSequence(
+  mock: Mock,
+  expectedValues: unknown[]
+): Promise<void> {
+  for (const expected of expectedValues) {
+    const result = await mock();
+    expect(result).toEqual(expected);
+  }
+}
+
+/**
+ * Security assertion - verify sensitive data handling
+ *
+ * @example
+ * assertNoSensitiveDataLogged(mockLogger, ['password', 'token', 'secret']);
+ */
+export function assertNoSensitiveDataLogged(
+  loggerMock: Mock,
+  sensitivePatterns: string[]
+): void {
+  const allCalls = loggerMock.mock.calls;
+
+  for (const call of allCalls) {
+    const logContent = JSON.stringify(call);
+    for (const pattern of sensitivePatterns) {
+      expect(logContent.toLowerCase()).not.toContain(pattern.toLowerCase());
+    }
+  }
+}
+
+/**
+ * Performance assertion - verify operation meets target
+ *
+ * @example
+ * await assertPerformanceTarget(
+ *   async () => await search.execute(query),
+ *   { targetMs: 100, iterations: 10 }
+ * );
+ */
+export async function assertPerformanceTarget(
+  operation: () => Promise<unknown>,
+  config: { targetMs: number; iterations: number; warmupIterations?: number }
+): Promise<{ averageMs: number; minMs: number; maxMs: number }> {
+  const { targetMs, iterations, warmupIterations = 3 } = config;
+
+  // Warmup
+  for (let i = 0; i < warmupIterations; i++) {
+    await operation();
+  }
+
+  const timings: number[] = [];
+
+  for (let i = 0; i < iterations; i++) {
+    const start = performance.now();
+    await operation();
+    timings.push(performance.now() - start);
+  }
+
+  const averageMs = timings.reduce((a, b) => a + b, 0) / timings.length;
+  const minMs = Math.min(...timings);
+  const maxMs = Math.max(...timings);
+
+  expect(averageMs).toBeLessThanOrEqual(targetMs);
+
+  return { averageMs, minMs, maxMs };
+}

package/src/helpers/create-mock.ts

@@ -0,0 +1,200 @@
+/**
+ * V3 Claude-Flow Mock Factory
+ *
+ * London School TDD Mock Creation Utilities
+ * - Creates type-safe mocks for behavior verification
+ * - Supports deep mocking for complex objects
+ * - Enables interaction tracking for behavior testing
+ */
+import { vi, type Mock } from 'vitest';
+
+/**
+ * Type for a fully mocked interface
+ */
+export type MockedInterface<T> = {
+  [K in keyof T]: T[K] extends (...args: infer A) => infer R
+    ? Mock<(...args: A) => R>
+    : T[K];
+};
+
+/**
+ * Create a shallow mock of an interface
+ * Each method becomes a vi.fn() for behavior verification
+ *
+ * @example
+ * const mockRepo = createMock<UserRepository>();
+ * mockRepo.findById.mockResolvedValue(user);
+ * expect(mockRepo.save).toHaveBeenCalledWith(user);
+ */
+export function createMock<T extends object>(): MockedInterface<T> {
+  return new Proxy({} as MockedInterface<T>, {
+    get: (target, prop: string | symbol) => {
+      if (typeof prop === 'string' && !(prop in target)) {
+        (target as Record<string | symbol, unknown>)[prop] = vi.fn();
+      }
+      return (target as Record<string | symbol, unknown>)[prop];
+    },
+  });
+}
+
+/**
+ * Create a deep mock that handles nested objects
+ * Useful for complex interfaces with nested dependencies
+ *
+ * @example
+ * const mockService = createDeepMock<ComplexService>();
+ * mockService.nested.method.mockReturnValue(result);
+ */
+export function createDeepMock<T extends object>(): MockedInterface<T> {
+  const cache = new Map<string | symbol, unknown>();
+
+  return new Proxy({} as MockedInterface<T>, {
+    get: (target, prop: string | symbol) => {
+      if (!cache.has(prop)) {
+        const mock = vi.fn();
+        // Allow chaining for nested access
+        (mock as unknown as Record<string, unknown>).mockReturnValue =
+          mock.mockReturnValue.bind(mock);
+        cache.set(prop, mock);
+      }
+      return cache.get(prop);
+    },
+  });
+}
+
+/**
+ * Create a spy mock that wraps an existing object
+ * Preserves original behavior while enabling verification
+ *
+ * @example
+ * const spied = createSpyMock(realService);
+ * await spied.process();
+ * expect(spied.process).toHaveBeenCalled();
+ */
+export function createSpyMock<T extends object>(target: T): MockedInterface<T> {
+  const spied = { ...target } as MockedInterface<T>;
+
+  for (const key of Object.keys(target) as Array<keyof T>) {
+    const value = target[key];
+    if (typeof value === 'function') {
+      (spied as Record<keyof T, unknown>)[key] = vi.fn(value.bind(target));
+    }
+  }
+
+  return spied;
+}
+
+/**
+ * Create a mock with predefined behavior
+ * Useful for common test scenarios
+ *
+ * @example
+ * const mockRepo = createMockWithBehavior<UserRepository>({
+ *   findById: async (id) => ({ id, name: 'Test' }),
+ *   save: async (user) => user,
+ * });
+ */
+export function createMockWithBehavior<T extends object>(
+  implementations: Partial<{ [K in keyof T]: T[K] }>
+): MockedInterface<T> {
+  const mock = createMock<T>();
+
+  for (const [key, impl] of Object.entries(implementations)) {
+    if (typeof impl === 'function') {
+      (mock as Record<string, Mock>)[key].mockImplementation(impl as (...args: unknown[]) => unknown);
+    }
+  }
+
+  return mock;
+}
+
+/**
+ * Create a mock that fails on first call, succeeds on retry
+ * Useful for testing retry logic and error handling
+ *
+ * @example
+ * const mockApi = createRetryMock<ApiClient>('fetch', new Error('Network'), data);
+ */
+export function createRetryMock<T extends object>(
+  methodName: keyof T,
+  firstError: Error,
+  successValue: unknown
+): MockedInterface<T> {
+  const mock = createMock<T>();
+
+  (mock as Record<string, Mock>)[methodName as string]
+    .mockRejectedValueOnce(firstError)
+    .mockResolvedValue(successValue);
+
+  return mock;
+}
+
+/**
+ * Create a sequence mock that returns different values per call
+ * Useful for testing stateful interactions
+ *
+ * @example
+ * const mockCounter = createSequenceMock<Counter>('next', [1, 2, 3, 4, 5]);
+ */
+export function createSequenceMock<T extends object>(
+  methodName: keyof T,
+  values: unknown[]
+): MockedInterface<T> {
+  const mock = createMock<T>();
+  const fn = (mock as Record<string, Mock>)[methodName as string];
+
+  values.forEach((value, index) => {
+    if (index === values.length - 1) {
+      fn.mockReturnValue(value);
+    } else {
+      fn.mockReturnValueOnce(value);
+    }
+  });
+
+  return mock;
+}
+
+/**
+ * Interaction recorder for complex behavior verification
+ * Tracks all calls across multiple mocks
+ *
+ * @example
+ * const recorder = new InteractionRecorder();
+ * recorder.track('repo', mockRepo);
+ * recorder.track('notifier', mockNotifier);
+ * await service.process();
+ * expect(recorder.getInteractionOrder()).toEqual(['repo.save', 'notifier.notify']);
+ */
+export class InteractionRecorder {
+  private interactions: Array<{ name: string; method: string; args: unknown[]; timestamp: number }> = [];
+
+  track<T extends object>(name: string, mock: MockedInterface<T>): void {
+    for (const key of Object.keys(mock)) {
+      const method = (mock as Record<string, Mock>)[key];
+      if (typeof method?.mockImplementation === 'function') {
+        const original = method.getMockImplementation();
+        method.mockImplementation((...args: unknown[]) => {
+          this.interactions.push({
+            name,
+            method: key,
+            args,
+            timestamp: Date.now(),
+          });
+          return original?.(...args);
+        });
+      }
+    }
+  }
+
+  getInteractions(): Array<{ name: string; method: string; args: unknown[] }> {
+    return this.interactions.map(({ name, method, args }) => ({ name, method, args }));
+  }
+
+  getInteractionOrder(): string[] {
+    return this.interactions.map(({ name, method }) => `${name}.${method}`);
+  }
+
+  clear(): void {
+    this.interactions = [];
+  }
+}

package/src/helpers/index.ts

@@ -0,0 +1,182 @@
+/**
+ * V3 Claude-Flow Test Helpers Index
+ *
+ * Central export for all test helpers
+ */
+
+// Mock factory utilities
+export {
+  createMock,
+  createDeepMock,
+  createSpyMock,
+  createMockWithBehavior,
+  createRetryMock,
+  createSequenceMock,
+  InteractionRecorder,
+  type MockedInterface,
+} from './create-mock.js';
+
+// Test application builder
+export {
+  createTestApplication,
+  type TestApplication,
+  type IEventBus,
+  type ITaskManager,
+  type IAgentLifecycle,
+  type IMemoryService,
+  type ISecurityService,
+  type ISwarmCoordinator,
+} from './test-application.js';
+
+// Swarm test instance
+export {
+  createSwarmTestInstance,
+  SwarmTestInstance,
+  type V3AgentType,
+  type SwarmTopology,
+  type SwarmAgent,
+  type SwarmMessage,
+  type SwarmTask,
+  type SwarmTaskResult,
+} from './swarm-instance.js';
+
+// Custom assertions (legacy)
+export {
+  assertCallSequence,
+  assertNotCalledWith,
+  assertInteractionCount,
+  assertAllCalled,
+  assertNoneCalled,
+  assertContractCompliance,
+  assertTimingWithin,
+  assertTimingRange,
+  assertThrowsWithMessage,
+  assertEventPublished,
+  assertMockSequence,
+  assertNoSensitiveDataLogged,
+  assertPerformanceTarget,
+  type ContractDefinition,
+} from './assertions.js';
+
+// Test utilities (waitFor, retry, timeout, etc.)
+export {
+  waitFor,
+  waitUntilChanged,
+  retry,
+  withTimeout,
+  sleep,
+  createDeferred,
+  parallelLimit,
+  measureTime,
+  createMockClock,
+  createTestEmitter,
+  createCallSpy,
+  createMockStream,
+  collectStream,
+  generateTestId,
+  createTestContext,
+  expectToReject,
+  createTrackedMock,
+  TimeoutError,
+  type WaitForOptions,
+  type WaitUntilChangedOptions,
+  type RetryOptions,
+  type Deferred,
+  type MockClock,
+  type TestEmitter,
+  type CallSpy,
+  type MockStreamOptions,
+  type TestContext,
+  type TrackedMock,
+} from './test-utils.js';
+
+// Mock factory (comprehensive service mocks)
+export {
+  createMockEventBus,
+  createMockTaskManager,
+  createMockAgentLifecycle,
+  createMockMemoryService,
+  createMockSecurityService,
+  createMockSwarmCoordinator,
+  createMockMCPClient,
+  createMockLogger,
+  createMockApplication,
+  resetMockApplication,
+  type MockApplication,
+  type ILogger,
+  type IMCPClient,
+  type DomainEvent,
+  type EventHandler,
+  type Task,
+  type TaskDefinition,
+  type TaskResult,
+  type TaskStatus,
+  type TaskFilters,
+  type AgentConfig,
+  type AgentSpawnResult,
+  type TerminateOptions,
+  type AgentFilters,
+  type AgentHealthCheck,
+  type MemoryStats,
+  type IndexConfig,
+  type InputValidationOptions,
+  type ExecuteOptions,
+  type ExecuteResult,
+} from './mock-factory.js';
+
+// Assertion helpers (enhanced)
+export {
+  assertCalledWithPattern,
+  assertEventOrder,
+  assertEventNotPublished,
+  assertMocksCalledInOrder,
+  assertCalledNTimesWith,
+  assertCompletesWithin,
+  assertThrowsError,
+  assertNoSensitiveData,
+  assertMatchesSnapshot,
+  assertV3PerformanceTargets,
+  assertValidDomainObject,
+  assertOnlyCalledWithAllowed,
+  assertPartialOrder,
+  assertAllPass,
+  assertNonePass,
+  assertSameElements,
+  assertMockReturnsSequence,
+  assertValidStateTransition,
+  assertRetryPattern,
+  assertDependencyInjected,
+  registerCustomMatchers,
+  type SnapshotOptions,
+  type V3PerformanceMetrics,
+  type RetryPatternOptions,
+} from './assertion-helpers.js';
+
+// Setup and teardown helpers
+export {
+  createSetupContext,
+  getGlobalContext,
+  resetGlobalContext,
+  configureTestEnvironment,
+  createTestSuite,
+  createTestScope,
+  createInMemoryDatabaseHelper,
+  createNetworkTestHelper,
+  createInMemoryFileSystemHelper,
+  createPerformanceTestHelper,
+  setupV3Tests,
+  flushPromises,
+  withTestTimeout,
+  type SetupContext,
+  type CleanupFunction,
+  type Disposable,
+  type TestEnvironmentConfig,
+  type TestSuiteHelpers,
+  type TestScope,
+  type DatabaseTestHelper,
+  type NetworkTestHelper,
+  type MockFetchResponse,
+  type FileSystemTestHelper,
+  type PerformanceTestHelper,
+  type V3TestConfig,
+} from './setup-teardown.js';