groundswell 0.0.1 → 0.0.2

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/docs/P1M2T2S2/research/01-testing-aggregated-errors.md

@@ -0,0 +1,1103 @@
+# Testing Aggregated Errors in TypeScript/JavaScript Workflow Engines
+
+**Research Date:** 2026-01-12
+**Task:** P1.M2.T2.S2 - Research testing patterns for error aggregation
+**Focus:** Testing aggregated errors, Promise.allSettled scenarios, error event emissions
+
+## Table of Contents
+1. [Overview](#overview)
+2. [Testing Aggregated Errors](#testing-aggregated-errors)
+3. [Promise.allSettled Error Patterns](#promiseallsettled-error-patterns)
+4. [Error Event Emission Testing](#error-event-emission-testing)
+5. [Mock Patterns for Error Scenarios](#mock-patterns-for-error-scenarios)
+6. [Assertion Patterns for Complex Error Objects](#assertion-patterns-for-complex-error-objects)
+7. [Testing Library Recommendations](#testing-library-recommendations)
+8. [Best Practices](#best-practices)
+
+---
+
+## Overview
+
+Error aggregation in workflow engines requires comprehensive testing strategies to ensure:
+- All concurrent errors are collected and preserved
+- Error context is maintained across workflow hierarchies
+- Error events are properly emitted for observability
+- Complex error objects are correctly structured
+- No workflows are orphaned or left in hanging states
+
+### Key Testing Concepts
+
+1. **Error Collection:** Verify that all errors from concurrent operations are gathered
+2. **Error Preservation:** Ensure error details (stack traces, logs, state) are intact
+3. **Event Emission:** Confirm error events are emitted with correct structure
+4. **Orphan Prevention:** Validate all workflows complete, even when errors occur
+5. **Error Merging:** Test custom and default error aggregation strategies
+
+---
+
+## Testing Aggregated Errors
+
+### Basic Error Aggregation Test Pattern
+
+```typescript
+import { describe, it, expect } from 'vitest';
+
+describe('Error Aggregation', () => {
+  it('should aggregate errors from multiple concurrent workflows', async () => {
+    // ARRANGE: Create workflows that will fail
+    const errors: Error[] = [];
+    const expectedErrors = 3;
+
+    class ParentWorkflow extends Workflow {
+      @Task({ concurrent: true, errorMergeStrategy: { enabled: true } })
+      async spawnFailingChildren() {
+        return [
+          createFailingWorkflow(this, 'Child-1', 'Error 1'),
+          createFailingWorkflow(this, 'Child-2', 'Error 2'),
+          createFailingWorkflow(this, 'Child-3', 'Error 3'),
+        ];
+      }
+
+      async run() {
+        try {
+          await this.spawnFailingChildren();
+        } catch (err) {
+          errors.push(err as Error);
+        }
+      }
+    }
+
+    const parent = new ParentWorkflow('Parent');
+
+    // ACT: Run the workflow
+    await parent.run();
+
+    // ASSERT: Verify error aggregation
+    expect(errors.length).toBe(1);
+    const aggregatedError = errors[0];
+
+    // Verify error contains aggregated information
+    expect(aggregatedError.message).toContain(`${expectedErrors} errors`);
+    expect(aggregatedError.message).toContain('Error 1');
+    expect(aggregatedError.message).toContain('Error 2');
+    expect(aggregatedError.message).toContain('Error 3');
+  });
+});
+```
+
+### Error Aggregation with Custom Merger
+
+```typescript
+describe('Custom Error Aggregation', () => {
+  it('should use custom error merge function when provided', async () => {
+    // ARRANGE: Define custom merge strategy
+    const customMerger = (errors: WorkflowError[]): WorkflowError => ({
+      message: `Custom merge: ${errors.length} failures`,
+      original: errors,
+      workflowId: 'merged',
+      state: {} as any,
+      logs: errors.flatMap(e => e.logs),
+    });
+
+    class ParentWorkflow extends Workflow {
+      @Task({
+        concurrent: true,
+        errorMergeStrategy: {
+          enabled: true,
+          combine: customMerger
+        }
+      })
+      async spawnChildren() {
+        return [
+          createFailingWorkflow(this, 'A', 'Fail A'),
+          createFailingWorkflow(this, 'B', 'Fail B'),
+        ];
+      }
+
+      async run() {
+        try {
+          await this.spawnChildren();
+        } catch (err) {
+          return err;
+        }
+      }
+    }
+
+    const parent = new ParentWorkflow('Parent');
+
+    // ACT
+    const result = await parent.run();
+
+    // ASSERT: Custom merger was used
+    expect(result).toBeDefined();
+    expect((result as any).message).toBe('Custom merge: 2 failures');
+    expect((result as any).workflowId).toBe('merged');
+  });
+});
+```
+
+### Testing Error Depth Limits
+
+```typescript
+describe('Error Aggregation Depth Limits', () => {
+  it('should respect maxMergeDepth configuration', async () => {
+    // ARRANGE: Create nested workflow failures
+    class DeeplyNestedWorkflow extends Workflow {
+      @Task({
+        concurrent: true,
+        errorMergeStrategy: {
+          enabled: true,
+          maxMergeDepth: 2  // Only merge 2 levels deep
+        }
+      })
+      async spawnNested() {
+        return [
+          createFailingWorkflow(this, 'Level1-A', 'Error A'),
+          createFailingWorkflow(this, 'Level1-B', 'Error B'),
+        ];
+      }
+
+      async run() {
+        try {
+          await this.spawnNested();
+        } catch (err) {
+          return err;
+        }
+      }
+    }
+
+    const root = new DeeplyNestedWorkflow('Root');
+
+    // ACT
+    const result = await root.run();
+
+    // ASSERT: Depth limit enforced
+    expect(result).toBeDefined();
+    // Verify nested errors are flattened but not infinitely nested
+    const hasProperDepth = validateErrorDepth(result, 2);
+    expect(hasProperDepth).toBe(true);
+  });
+
+  function validateErrorDepth(error: any, maxDepth: number): boolean {
+    // Implementation checks error nesting depth
+    return true;
+  }
+});
+```
+
+---
+
+## Promise.allSettled Error Patterns
+
+### Basic Promise.allSettled Error Collection
+
+```typescript
+describe('Promise.allSettled Error Collection', () => {
+  it('should collect all errors from allSettled promises', async () => {
+    // ARRANGE: Create promises with mixed results
+    const promises = [
+      Promise.reject(new Error('Error 1')),
+      Promise.reject(new Error('Error 2')),
+      Promise.resolve('success'),
+      Promise.reject(new Error('Error 3')),
+    ];
+
+    // ACT: Use Promise.allSettled
+    const results = await Promise.allSettled(promises);
+
+    // ASSERT: Filter and verify errors
+    const rejected = results.filter(
+      (r): r is PromiseRejectedResult => r.status === 'rejected'
+    );
+
+    expect(rejected.length).toBe(3);
+    expect(rejected[0].reason.message).toBe('Error 1');
+    expect(rejected[1].reason.message).toBe('Error 2');
+    expect(rejected[2].reason.message).toBe('Error 3');
+
+    // ASSERT: Verify fulfilled promises
+    const fulfilled = results.filter(
+      (r): r is PromiseFulfilledResult<unknown> => r.status === 'fulfilled'
+    );
+
+    expect(fulfilled.length).toBe(1);
+    expect(fulfilled[0].value).toBe('success');
+  });
+});
+```
+
+### Concurrent Workflow Execution with allSettled
+
+```typescript
+describe('Concurrent Workflow allSettled', () => {
+  it('should complete all workflows even when some fail', async () => {
+    // ARRANGE: Track all completions
+    const completedWorkflows = new Set<string>();
+    const failedWorkflows = new Set<string>();
+
+    class ParentWorkflow extends Workflow {
+      @Task({ concurrent: true })
+      async spawnChildren() {
+        const children = [
+          createChildWorkflow(this, 'Success-1', false),
+          createChildWorkflow(this, 'Fail-1', true),
+          createChildWorkflow(this, 'Success-2', false),
+          createChildWorkflow(this, 'Fail-2', true),
+        ];
+
+        // Track all completions
+        children.forEach(child => {
+          child.run().then(
+            () => completedWorkflows.add(child.id),
+            () => {
+              failedWorkflows.add(child.id);
+              completedWorkflows.add(child.id);
+            }
+          );
+        });
+
+        return children;
+      }
+
+      async run() {
+        try {
+          await this.spawnChildren();
+        } catch (err) {
+          // Expected
+        }
+      }
+    }
+
+    const parent = new ParentWorkflow('Parent');
+
+    // ACT
+    await parent.run();
+
+    // ASSERT: All workflows completed
+    expect(completedWorkflows.size).toBe(4);
+    expect(failedWorkflows.size).toBe(2);
+
+    // ASSERT: All children attached
+    expect(parent.children.length).toBe(4);
+  });
+});
+```
+
+### Testing Error Order Preservation
+
+```typescript
+describe('Error Order Preservation', () => {
+  it('should preserve error order from concurrent execution', async () => {
+    // ARRANGE: Create workflows with deterministic failure order
+    class OrderedFailureWorkflow extends Workflow {
+      @Task({ concurrent: true, errorMergeStrategy: { enabled: true } })
+      async spawnChildren() {
+        return [
+          createChildWorkflow(this, 'First', true),
+          createChildWorkflow(this, 'Second', true),
+          createChildWorkflow(this, 'Third', true),
+        ];
+      }
+
+      async run() {
+        try {
+          await this.spawnChildren();
+        } catch (err) {
+          return err;
+        }
+      }
+    }
+
+    const parent = new OrderedFailureWorkflow('Parent');
+
+    // ACT
+    const result = await parent.run();
+
+    // ASSERT: Errors collected in predictable order
+    const errorMessages = extractErrorMessages(result);
+    expect(errorMessages).toContain('First failed');
+    expect(errorMessages).toContain('Second failed');
+    expect(errorMessages).toContain('Third failed');
+  });
+
+  function extractErrorMessages(error: any): string[] {
+    // Extract all error messages from aggregated error
+    return [];
+  }
+});
+```
+
+---
+
+## Error Event Emission Testing
+
+### Setting Up Event Observers
+
+```typescript
+describe('Error Event Emission', () => {
+  /**
+   * Helper to setup event observer for event collection
+   * Pattern from: src/__tests__/adversarial/observer-propagation.test.ts
+   */
+  function setupEventObserver(workflow: Workflow): WorkflowEvent[] {
+    const events: WorkflowEvent[] = [];
+
+    workflow.addObserver({
+      onLog: () => {},
+      onEvent: (e) => events.push(e),
+      onStateUpdated: () => {},
+      onTreeChanged: () => {},
+    });
+
+    return events;
+  }
+
+  it('should emit error events for all failing workflows', async () => {
+    // ARRANGE: Setup event collection
+    class ParentWorkflow extends Workflow {
+      @Task({ concurrent: true })
+      async spawnChildren() {
+        return [
+          createChildWorkflow(this, 'Good', false),
+          createChildWorkflow(this, 'Bad1', true),
+          createChildWorkflow(this, 'Bad2', true),
+        ];
+      }
+
+      async run() {
+        try {
+          await this.spawnChildren();
+        } catch (err) {
+          // Expected
+        }
+      }
+    }
+
+    const parent = new ParentWorkflow('Parent');
+    const events = setupEventObserver(parent);
+
+    // ACT
+    await parent.run();
+
+    // ASSERT: Error events emitted for both failures
+    const errorEvents = events.filter(e => e.type === 'error');
+    expect(errorEvents.length).toBeGreaterThanOrEqual(2);
+
+    // ASSERT: Each error event has correct structure
+    errorEvents.forEach(event => {
+      expect(event.type).toBe('error');
+      if (event.type === 'error') {
+        expect(event.error).toBeDefined();
+        expect(event.error.workflowId).toBeDefined();
+        expect(event.error.message).toBeDefined();
+        expect(Array.isArray(event.error.logs)).toBe(true);
+      }
+    });
+  });
+});
+```
+
+### Verifying Event Propagation
+
+```typescript
+describe('Error Event Propagation', () => {
+  it('should propagate error events to parent observers', async () => {
+    // ARRANGE: Create workflow hierarchy
+    class ChildWorkflow extends Workflow {
+      async run() {
+        throw new Error('Child error');
+      }
+    }
+
+    class ParentWorkflow extends Workflow {
+      @Task({ concurrent: true })
+      async spawnChild() {
+        return [new ChildWorkflow('Child', this)];
+      }
+
+      async run() {
+        try {
+          await this.spawnChild();
+        } catch (err) {
+          // Expected
+        }
+      }
+    }
+
+    const parent = new ParentWorkflow('Parent');
+    const events: WorkflowEvent[] = [];
+
+    // CRITICAL: Add observer to root workflow
+    parent.addObserver({
+      onLog: () => {},
+      onEvent: (e) => events.push(e),
+      onStateUpdated: () => {},
+      onTreeChanged: () => {},
+    });
+
+    // ACT
+    await parent.run();
+
+    // ASSERT: Child error events visible to parent observer
+    const childErrorEvents = events.filter(
+      e => e.type === 'error' && e.error.workflowId === 'Child'
+    );
+
+    expect(childErrorEvents.length).toBeGreaterThan(0);
+    expect(childErrorEvents[0]).toMatchObject({
+      type: 'error',
+      error: expect.objectContaining({
+        workflowId: 'Child',
+        message: expect.stringContaining('Child error')
+      })
+    });
+  });
+});
+```
+
+### Testing Event Order
+
+```typescript
+describe('Error Event Order', () => {
+  it('should emit events in correct chronological order', async () => {
+    // ARRANGE
+    const eventTimestamps: number[] = [];
+
+    class TimestampTrackingWorkflow extends Workflow {
+      @Task({ concurrent: true })
+      async spawnChildren() {
+        return [
+          createChildWorkflow(this, 'Child-1', true),
+          createChildWorkflow(this, 'Child-2', true),
+        ];
+      }
+
+      async run() {
+        try {
+          await this.spawnChildren();
+        } catch (err) {
+          // Expected
+        }
+      }
+    }
+
+    const parent = new TimestampTrackingWorkflow('Parent');
+
+    parent.addObserver({
+      onLog: () => {},
+      onEvent: (e) => {
+        eventTimestamps.push(Date.now());
+      },
+      onStateUpdated: () => {},
+      onTreeChanged: () => {},
+    });
+
+    // ACT
+    await parent.run();
+
+    // ASSERT: Events are in chronological order
+    for (let i = 1; i < eventTimestamps.length; i++) {
+      expect(eventTimestamps[i]).toBeGreaterThanOrEqual(eventTimestamps[i - 1]);
+    }
+  });
+});
+```
+
+---
+
+## Mock Patterns for Error Scenarios
+
+### Error Factory Pattern
+
+```typescript
+describe('Mock Error Patterns', () => {
+  /**
+   * Factory function to create consistent mock errors
+   */
+  function createMockError(overrides?: Partial<WorkflowError>): WorkflowError {
+    return {
+      message: 'Mock workflow error',
+      original: new Error('Original error'),
+      workflowId: 'mock-workflow-id',
+      stack: 'Error: Original error\n    at mock.js:10:15',
+      state: {} as any,
+      logs: [
+        { id: '1', workflowId: 'mock', timestamp: Date.now(), level: 'error', message: 'Error occurred' }
+      ],
+      ...overrides
+    };
+  }
+
+  it('should create consistent mock errors for testing', async () => {
+    // ARRANGE: Create mock errors with variations
+    const mockErrors = [
+      createMockError({ message: 'Error 1', workflowId: 'workflow-1' }),
+      createMockError({ message: 'Error 2', workflowId: 'workflow-2' }),
+      createMockError({ message: 'Error 3', workflowId: 'workflow-3' }),
+    ];
+
+    // ACT: Test error merge with mocks
+    const merged = mergeErrors(mockErrors);
+
+    // ASSERT: Verify merge behavior
+    expect(merged.message).toContain('3 errors');
+    expect(merged.message).toContain('Error 1');
+    expect(merged.message).toContain('Error 2');
+    expect(merged.message).toContain('Error 3');
+  });
+
+  function mergeErrors(errors: WorkflowError[]): WorkflowError {
+    return {
+      message: `${errors.length} errors: ${errors.map(e => e.message).join(', ')}`,
+      original: errors,
+      workflowId: 'merged',
+      state: {} as any,
+      logs: errors.flatMap(e => e.logs),
+    };
+  }
+});
+```
+
+### Scenario-Based Error Mocking
+
+```typescript
+describe('Scenario-Based Error Mocking', () => {
+  /**
+   * Enum of common error scenarios
+   */
+  enum ErrorScenario {
+    NETWORK_FAILURE = 'NETWORK_FAILURE',
+    VALIDATION_ERROR = 'VALIDATION_ERROR',
+    TIMEOUT = 'TIMEOUT',
+    PERMISSION_DENIED = 'PERMISSION_DENIED',
+  }
+
+  /**
+   * Map of scenarios to mock errors
+   */
+  const errorScenarios: Record<ErrorScenario, WorkflowError> = {
+    [ErrorScenario.NETWORK_FAILURE]: createMockError({
+      message: 'Network connection failed',
+      workflowId: 'network-task',
+    }),
+    [ErrorScenario.VALIDATION_ERROR]: createMockError({
+      message: 'Validation failed: invalid input',
+      workflowId: 'validation-task',
+    }),
+    [ErrorScenario.TIMEOUT]: createMockError({
+      message: 'Operation timed out after 30000ms',
+      workflowId: 'timeout-task',
+    }),
+    [ErrorScenario.PERMISSION_DENIED]: createMockError({
+      message: 'Permission denied: insufficient privileges',
+      workflowId: 'auth-task',
+    }),
+  };
+
+  it('should handle different error scenarios correctly', async () => {
+    // Test each scenario
+    for (const [scenario, error] of Object.entries(errorScenarios)) {
+      // ARRANGE: Setup workflow with scenario
+      class ScenarioWorkflow extends Workflow {
+        async run() {
+          throw error;
+        }
+      }
+
+      const workflow = new ScenarioWorkflow(scenario);
+
+      // ACT & ASSERT: Verify error handling
+      await expect(workflow.run()).rejects.toMatchObject({
+        message: error.message,
+        workflowId: error.workflowId,
+      });
+    }
+  });
+});
+```
+
+### Spying on Error Handling
+
+```typescript
+describe('Error Handling Spies', () => {
+  it('should track error handling with spies', async () => {
+    // ARRANGE: Setup spies
+    const errorHandler = vi.fn();
+    const errorMerger = vi.fn((errors: WorkflowError[]) => ({
+      message: `Merged: ${errors.length} errors`,
+      original: errors,
+      workflowId: 'merged',
+      state: {} as any,
+      logs: [],
+    }));
+
+    class SpiedWorkflow extends Workflow {
+      @Task({
+        concurrent: true,
+        errorMergeStrategy: {
+          enabled: true,
+          combine: errorMerger,
+        }
+      })
+      async spawnChildren() {
+        return [
+          createFailingWorkflow(this, 'A', 'Error A'),
+          createFailingWorkflow(this, 'B', 'Error B'),
+        ];
+      }
+
+      async run() {
+        try {
+          await this.spawnChildren();
+        } catch (err) {
+          errorHandler(err);
+          throw err;
+        }
+      }
+    }
+
+    const workflow = new SpiedWorkflow('Spied');
+
+    // ACT
+    await expect(workflow.run()).rejects.toThrow();
+
+    // ASSERT: Verify spies called correctly
+    expect(errorHandler).toHaveBeenCalledTimes(1);
+    expect(errorMerger).toHaveBeenCalledTimes(1);
+    expect(errorMerger).toHaveBeenCalledWith(
+      expect.arrayContaining([
+        expect.objectContaining({ message: expect.any(String) })
+      ])
+    );
+  });
+});
+```
+
+---
+
+## Assertion Patterns for Complex Error Objects
+
+### Type Guard Assertions
+
+```typescript
+describe('Complex Error Object Assertions', () => {
+  /**
+   * Type guard for WorkflowError
+   */
+  function isWorkflowError(error: unknown): error is WorkflowError {
+    return (
+      typeof error === 'object' &&
+      error !== null &&
+      'message' in error &&
+      'workflowId' in error &&
+      'logs' in error
+    );
+  }
+
+  it('should use type guards for error assertions', async () => {
+    // ARRANGE
+    class ComplexWorkflow extends Workflow {
+      async run() {
+        throw new Error('Complex error');
+      }
+    }
+
+    const workflow = new ComplexWorkflow('Complex');
+
+    // ACT
+    try {
+      await workflow.run();
+      fail('Expected error to be thrown');
+    } catch (error) {
+      // ASSERT: Use type guard
+      if (isWorkflowError(error)) {
+        expect(error.message).toBeDefined();
+        expect(error.workflowId).toBeDefined();
+        expect(Array.isArray(error.logs)).toBe(true);
+      } else {
+        fail('Error is not a WorkflowError');
+      }
+    }
+  });
+});
+```
+
+### Partial Object Matching
+
+```typescript
+describe('Partial Object Matching', () => {
+  it('should match error object properties', async () => {
+    // ARRANGE
+    class PartialWorkflow extends Workflow {
+      @Task({ concurrent: true, errorMergeStrategy: { enabled: true } })
+      async spawnChildren() {
+        return [
+          createFailingWorkflow(this, 'Child-1', 'Error 1'),
+          createFailingWorkflow(this, 'Child-2', 'Error 2'),
+        ];
+      }
+
+      async run() {
+        try {
+          await this.spawnChildren();
+        } catch (err) {
+          return err;
+        }
+      }
+    }
+
+    const workflow = new PartialWorkflow('Partial');
+
+    // ACT
+    const result = await workflow.run();
+
+    // ASSERT: Use matchObject for partial matching
+    expect(result).toMatchObject({
+      message: expect.stringContaining('2 errors'),
+      workflowId: expect.any(String),
+      logs: expect.any(Array),
+    });
+
+    // ASSERT: Nested object matching
+    if (isWorkflowError(result)) {
+      expect(result.logs).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            workflowId: expect.any(String),
+            level: expect.any(String),
+          })
+        ])
+      );
+    }
+  });
+});
+```
+
+### Custom Async Matchers
+
+```typescript
+describe('Custom Async Matchers', () => {
+  it('should use custom matchers for async error validation', async () => {
+    // ARRANGE: Define custom matcher
+    const toBeAggregatedError = async (received: any) => {
+      const pass = received &&
+        typeof received.message === 'string' &&
+        received.message.includes('errors') &&
+        Array.isArray(received.logs);
+
+      return {
+        pass,
+        message: () => pass
+          ? `Expected ${received} not to be an aggregated error`
+          : `Expected ${received} to be an aggregated error with message containing 'errors' and logs array`,
+      };
+    };
+
+    // Add custom matcher to expect
+    expect.extend({ toBeAggregatedError });
+
+    class AggregatedWorkflow extends Workflow {
+      @Task({ concurrent: true, errorMergeStrategy: { enabled: true } })
+      async spawnChildren() {
+        return [
+          createFailingWorkflow(this, 'A', 'Error A'),
+          createFailingWorkflow(this, 'B', 'Error B'),
+        ];
+      }
+
+      async run() {
+        try {
+          await this.spawnChildren();
+        } catch (err) {
+          return err;
+        }
+      }
+    }
+
+    const workflow = new AggregatedWorkflow('Aggregated');
+
+    // ACT
+    const result = await workflow.run();
+
+    // ASSERT: Use custom matcher
+    await expect(result).toBeAggregatedError();
+  });
+});
+```
+
+---
+
+## Testing Library Recommendations
+
+### Vitest (Recommended for This Project)
+
+**Pros:**
+- Native ESM support
+- Fast execution with worker threads
+- Jest-compatible API
+- Built-in TypeScript support
+- Watch mode with intelligent re-running
+
+**Installation:**
+```bash
+npm install -D vitest
+```
+
+**Configuration:** See `vitest.config.ts` in project root
+
+**Usage:**
+```bash
+vitest run                    # Run tests once
+vitest                        # Watch mode
+vitest --coverage             # With coverage
+```
+
+### Jest (Alternative)
+
+**Pros:**
+- Largest ecosystem of plugins
+- Extensive documentation
+- Wide community adoption
+- Rich mocking capabilities
+
+**Installation:**
+```bash
+npm install -D jest @types/jest ts-jest
+```
+
+**Configuration:**
+```javascript
+// jest.config.js
+module.exports = {
+  preset: 'ts-jest/presets/default-esm',
+  testEnvironment: 'node',
+  extensionsToTreatAsEsm: ['.ts'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  transform: {},
+};
+```
+
+### Library Comparison
+
+| Feature | Vitest | Jest |
+|---------|--------|------|
+| ESM Support | Native | Requires config |
+| Speed | Faster | Slower |
+| Watch Mode | Excellent | Good |
+| TypeScript | Built-in | Requires ts-jest |
+| API | Jest-compatible | Jest API |
+| Ecosystem | Growing | Mature |
+
+**Recommendation:** Use Vitest for this project (already configured)
+
+---
+
+## Best Practices
+
+### 1. Test Organization
+
+```typescript
+describe('Feature Name', () => {
+  describe('Specific Scenario', () => {
+    it('should do something specific', async () => {
+      // ARRANGE: Setup test data and conditions
+      // ACT: Execute the code being tested
+      // ASSERT: Verify expected outcomes
+    });
+  });
+});
+```
+
+### 2. Descriptive Test Names
+
+```typescript
+// Good: Descriptive and clear
+it('should aggregate all errors when multiple concurrent workflows fail', async () => {});
+
+// Bad: Vague
+it('should work', async () => {});
+```
+
+### 3. Isolated Tests
+
+Each test should be independent and not rely on other tests:
+
+```typescript
+describe('Isolated Tests', () => {
+  it('test 1', async () => {
+    const workflow = new Workflow('Test1');  // Fresh instance
+    // Test logic
+  });
+
+  it('test 2', async () => {
+    const workflow = new Workflow('Test2');  // Fresh instance
+    // Test logic - doesn't depend on test 1
+  });
+});
+```
+
+### 4. Explicit Assertions
+
+```typescript
+// Good: Explicit expectations
+expect(result).toBeDefined();
+expect(result.errors).toHaveLength(3);
+expect(result.errors[0].message).toBe('Error 1');
+
+// Bad: Implicit
+expect(result).toBeTruthy();  // Doesn't tell us what's true
+```
+
+### 5. Error Testing Patterns
+
+```typescript
+// Pattern 1: Try-catch with assertions
+try {
+  await workflow.run();
+  fail('Expected error to be thrown');
+} catch (error) {
+  expect(error).toMatchObject({ message: 'Expected error' });
+}
+
+// Pattern 2: async/await with rejects
+await expect(workflow.run()).rejects.toThrow('Expected error');
+
+// Pattern 3: Return error from try-catch
+const error = await workflow.run().catch(err => err);
+expect(error).toBeDefined();
+```
+
+### 6. Cleanup in Tests
+
+```typescript
+describe('Cleanup', () => {
+  it('should clean up resources', async () => {
+    const workflow = new Workflow('Test');
+    const observers = setupObservers(workflow);
+
+    try {
+      await workflow.run();
+    } finally {
+      // Cleanup: Remove observers
+      observers.forEach(obs => workflow.removeObserver(obs));
+    }
+  });
+});
+```
+
+### 7. Testing Edge Cases
+
+```typescript
+describe('Edge Cases', () => {
+  it('should handle empty error array', async () => {
+    const result = mergeErrors([]);
+    expect(result).toMatchObject({ message: '0 errors' });
+  });
+
+  it('should handle single error', async () => {
+    const result = mergeErrors([singleError]);
+    expect(result.message).toContain('1 error');
+  });
+
+  it('should handle all workflows failing', async () => {
+    // Test when 100% of workflows fail
+  });
+
+  it('should handle 50% failure rate', async () => {
+    // Test mixed success/failure
+  });
+});
+```
+
+### 8. Performance Testing
+
+```typescript
+describe('Performance', () => {
+  it('should complete error aggregation within timeout', async () => {
+    const startTime = performance.now();
+
+    await workflowWithManyErrors.run();
+
+    const duration = performance.now() - startTime;
+    expect(duration).toBeLessThan(1000);  // 1 second max
+  });
+});
+```
+
+### 9. Deterministic Tests
+
+```typescript
+// Good: Deterministic
+it('should handle errors in predictable order', async () => {
+  const errors = await workflow.run().catch(err => err);
+  expect(errors[0].workflowId).toBe('workflow-1');
+});
+
+// Bad: Relies on timing/setTimeout
+it('should eventually handle errors', async () => {
+  // Don't use arbitrary timeouts
+  await new Promise(resolve => setTimeout(resolve, 1000));
+});
+```
+
+### 10. Comprehensive Coverage
+
+```typescript
+describe('Comprehensive Error Testing', () => {
+  describe('Single error scenarios', () => {
+    it('should handle single workflow failure');
+    it('should handle single workflow timeout');
+    it('should handle single workflow rejection');
+  });
+
+  describe('Multiple error scenarios', () => {
+    it('should handle 2 concurrent failures');
+    it('should handle 5 concurrent failures');
+    it('should handle 10+ concurrent failures');
+  });
+
+  describe('Mixed scenarios', () => {
+    it('should handle 1 failure + 1 success');
+    it('should handle 2 failures + 3 successes');
+    it('should handle 50% failure rate');
+  });
+
+  describe('Edge cases', () => {
+    it('should handle 0 errors');
+    it('should handle all errors');
+    it('should handle deeply nested errors');
+  });
+});
+```
+
+---
+
+## Additional Resources
+
+### Project-Specific Patterns
+- **Concurrent Task Failures Test:** `/home/dustin/projects/groundswell/src/__tests__/adversarial/concurrent-task-failures.test.ts`
+- **Observer Propagation Test:** `/home/dustin/projects/groundswell/src/__tests__/adversarial/observer-propagation.test.ts`
+- **Task Decorator Implementation:** `/home/dustin/projects/groundswell/src/decorators/task.ts`
+
+### External Documentation
+- **Vitest Documentation:** https://vitest.dev/guide/
+- **Jest Documentation:** https://jestjs.io/docs/getting-started
+- **Promise.allSettled MDN:** https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled
+
+---
+
+## Summary
+
+This research document provides comprehensive patterns for testing error aggregation in TypeScript/JavaScript workflow engines, focusing on:
+
+1. **Aggregated Error Testing:** Multiple patterns for testing error collection and merging
+2. **Promise.allSettled Patterns:** Ensuring all workflows complete despite failures
+3. **Event Emission Testing:** Verifying error events are properly emitted and propagated
+4. **Mock Patterns:** Factory functions, scenario-based mocking, and spying
+5. **Assertion Patterns:** Type guards, partial matching, and custom matchers
+6. **Library Recommendations:** Vitest (recommended) vs Jest comparison
+7. **Best Practices:** Organization, naming, isolation, cleanup, and edge cases
+
+These patterns can be directly applied to implementing tests for the ErrorMergeStrategy functionality (P1.M2.T2) in the groundswell project.