suaveplan/docs/old-network-planning/PHASE_0.md

Phase 0: Environment Setup

Overview

This phase focuses on establishing the development and testing infrastructure necessary for implementing the network library. A robust testing environment is critical for a complex system like this, as it will allow for proper verification of functionality, edge case handling, and performance characteristics.

Detailed Requirements

1. Jest Configuration Setup

Base Configuration

Create a Jest configuration that:

• Uses the appropriate preset for the project
• Transforms TypeScript files correctly
• Sets up coverage reporting to track test coverage
• Specifies files to include/exclude from coverage
• Enforces 100% coverage thresholds for all metrics
• Configures any additional plugins or test environments needed

Jest Setup File

Create a setup file that:

• Imports necessary testing libraries
• Sets up custom matchers for network-specific assertions
• Configures global timeout settings appropriate for network tests
• Sets up any mocks that should be present for all tests

2. TypeScript Configuration

Ensure TypeScript configuration supports both the library implementation and testing:

• Library configuration should enable declaration file generation
• Test configuration should support Jest and CommonJS modules
• Both configurations should share base settings for consistency
• Ensure proper exclusion patterns to prevent cross-contamination

3. Testing Utilities

Network Mocks

Create mock implementations of key interfaces:

• MockNetworkNode: A simplified version of NetworkNode for testing

  • Should expose basic properties/methods needed for testing
  • Should simulate basic node behavior
  • Should provide helpers for simulating events/state changes
  • Should expose protected methods/properties for testing

• TestEventEmitter: An implementation of IEventEmitter for testing

  • Should track emitted events
  • Should allow inspection of event history
  • Should support standard event subscription/unsubscription
  • Should provide helper methods for test assertions

Network Testing Harness

Create a comprehensive testing harness that:

• Provides methods to create test networks easily
• Supports creation of various network topologies
• Offers utilities for connection/disconnection simulation
• Includes helpers for message passing verification
• Provides reset functionality for test isolation

Time-Based Testing Helpers

Create utilities for time-dependent tests:

• Methods for controlled delays in async tests
• Utilities for Jest timer manipulation
• Tools for waiting on conditions with timeouts
• Helpers for testing time-sensitive operations

Assertion Helpers

Create specialized assertion utilities:

• Node relationship assertions
• Message validation assertions
• Event emission assertions
• Network state assertions

Testing Strategy Requirements

Test Isolation

Tests must be properly isolated to prevent side effects:

• Each test should start with a fresh environment
• Mocks and spies should be cleared between tests
• Shared state should be reset before each test
• External dependencies should be properly mocked

Asynchronous Testing

Since many network operations are asynchronous, the test framework should support:

• Async/await pattern for test cases
• Proper handling of promises in assertions
• Utilities for controlled timing and synchronization
• Methods for waiting for asynchronous operations to complete

Time-Dependent Testing

For testing time-sensitive behavior:

• Support Jest's fake timer utilities
• Provide helpers for manipulating simulated time
• Include utilities for testing delays and timeouts
• Support both real and simulated time depending on test needs

Directory Structure

Establish a directory structure that supports the development approach:

libs/network/
├── jest.config.ts
├── jest.setup.ts
├── tsconfig.json
├── tsconfig.lib.json
├── tsconfig.spec.json
├── src/
│   ├── testing/
│   │   ├── mocks/
│   │   │   ├── network-node.mock.ts
│   │   │   ├── transport.mock.ts
│   │   │   └── ... other mocks
│   │   ├── network-test-harness.ts
│   │   ├── time-helpers.ts
│   │   ├── assertions.ts
│   │   └── index.ts
│   └── ... other directories

Interface Requirements

The testing utilities should adhere to these interfaces:

Test Harness Interface

The test harness should provide:

• Methods to create individual nodes with specified capabilities
• Methods to create multiple nodes at once
• Methods to establish connections between nodes
• Methods to simulate disconnections
• Methods to retrieve nodes by ID
• Methods to get all nodes in the test network
• Methods to reset the test environment

Mock Node Interface

Mock nodes should implement:

• Core properties of real nodes (id, level, etc.)
• Methods to simulate network events
• Methods to expose normally protected functionality
• Simplified versions of core node behavior

Test Event Emitter Interface

The test event emitter should implement:

• Standard event subscription/unsubscription
• Event emission
• Methods to query event history
• Methods to clear event history
• Methods to check for specific events

Edge Cases and Considerations

1. Test Isolation

Tests must be completely isolated to prevent interference:

• Ensure stateful components are reset between tests
• Verify that events from one test don't affect others
• Make sure asynchronous operations complete properly
• Ensure timers are properly cleaned up

2. Asynchronous Testing

Async tests require special handling:

• Define strategies for testing async message delivery
• Create patterns for verifying eventual consistency
• Establish timeout guidelines for different test types
• Document patterns for avoiding race conditions in tests

3. Mock Limitations

Be clear about mock limitations:

• Document differences between mocks and real implementations
• Establish which behaviors are simulated vs. delegated
• Define which edge cases might not be properly tested with mocks
• Create guidelines for when to use mocks vs. real components

4. Time-Sensitive Testing

Establish approaches for time-sensitive tests:

• Define when to use real timers vs. fake timers
• Create patterns for testing timeout behavior
• Document approaches for testing retry logic
• Establish strategies for testing debounce/throttle behavior

Deliverables

1. Complete Jest configuration files
2. TypeScript configuration files for library and tests
3. Core testing utilities:
   • Network test harness
   • Mock implementations
   • Testing helpers
   • Assertion utilities
4. Documentation on testing approaches and patterns

Success Criteria

Phase 0 is complete when:

• All testing infrastructure is in place
• Test utilities are themselves thoroughly tested
• Example tests demonstrate proper isolation and robustness
• TypeScript compilation works without errors
• Jest coverage reporting is properly configured
• Documentation clearly explains the testing approach

This phase sets up the foundation for all subsequent development phases, ensuring that we can effectively test the complex network components we will build.