`DW-Agents/README.test.md`

356 lines
# DW-Agents Testing Suite

Comprehensive automated testing for the DW-Agents system.

## Overview

This testing suite provides automated tests for:
- Health check endpoints
- API integration
- Agent startup and coordination
- Performance and load testing
- End-to-end workflows

## Test Structure

```
__tests__/
├── setup.ts                    # Global test configuration
├── health/                     # Health check tests
│   └── health-check.test.ts
├── integration/                # API integration tests
│   └── api-endpoints.test.ts
├── unit/                       # Unit tests
│   └── test-utils.test.ts
├── e2e/                        # End-to-end tests
│   └── agent-startup.test.ts
├── performance/                # Performance tests
│   └── load-test.test.ts
└── helpers/                    # Test utilities
    ├── test-server.ts
    └── test-data.ts
```

## Installation

```bash
# Install dependencies
npm install

# Or using yarn
yarn install
```

## Running Tests

### Run All Tests
```bash
npm test
```

### Run Specific Test Suites
```bash
# Unit tests only
npm run test:unit

# Integration tests only
npm run test:integration

# E2E tests only
npm run test:e2e

# Health check tests only
npm run test:health
```

### Run with Coverage
```bash
npm test -- --coverage
```

### Watch Mode
```bash
npm run test:watch
```

### CI Mode
```bash
npm run test:ci
```

## Test Categories

### Health Check Tests (`__tests__/health/`)
Tests for the `/api/health` endpoint:
- Response status and format
- Response time requirements
- Concurrent request handling
- Reliability and consistency
- Performance under load

**Key Tests:**
- Should return 200 status code
- Should respond within 1 second
- Should handle concurrent requests
- Should not expose sensitive information

### Integration Tests (`__tests__/integration/`)
Tests for API endpoints and integration:
- Core endpoint functionality
- Error handling
- CORS configuration
- Rate limiting
- Data validation

**Key Tests:**
- Should serve robots.txt
- Should handle 404 for non-existent routes
- Should set appropriate security headers
- Should handle malformed requests

### Unit Tests (`__tests__/unit/`)
Tests for individual components and utilities:
- Test utility functions
- Helper functions
- Mock and stub utilities
- Configuration validation

**Key Tests:**
- waitFor utility tests
- retry utility tests
- Global configuration tests

### E2E Tests (`__tests__/e2e/`)
Tests for complete user workflows:
- Agent startup and initialization
- Agent communication
- Critical user journeys
- System coordination

**Key Tests:**
- Agent bootstrap sequence
- Dashboard access workflow
- Agent monitoring workflow
- System resilience

### Performance Tests (`__tests__/performance/`)
Tests for system performance:
- Response time analysis
- Throughput testing
- Concurrency testing
- Stress testing
- Resource utilization

**Key Tests:**
- Response time under normal load
- Handling 100 requests per second
- 50 concurrent connections
- Recovery from overload
- Latency distribution (P50, P95, P99)

## Configuration

### Environment Variables
Set these in `.env.test`:

```env
BASE_URL=http://localhost
MASTER_HUB_PORT=9800
TEST_TIMEOUT=10000
API_TIMEOUT=5000
API_RETRIES=3
```

### Coverage Thresholds
Configured in `jest.config.js`:

```javascript
coverageThreshold: {
  global: {
    branches: 70,
    functions: 70,
    lines: 70,
    statements: 70
  }
}
```

## Test Utilities

### TestServer Helper
```typescript
import { createTestServer } from './__tests__/helpers/test-server';

const server = createTestServer();
await server.waitUntilReady();
const response = await server.get('/api/health');
```

### Test Data Generators
```typescript
import { createMockAgent, createMockHealthResponse } from './__tests__/helpers/test-data';

const agent = createMockAgent({ name: 'Test Agent', port: 9801 });
const healthResponse = createMockHealthResponse({ status: 'healthy' });
```

### Global Test Utilities
```typescript
// Wait for condition
await global.testUtils.waitFor(() => someCondition(), 5000);

// Retry operation
const result = await global.testUtils.retry(async () => {
  return await someAsyncOperation();
}, 3, 1000);
```

## Performance Benchmarks

Expected performance characteristics:

| Metric | Target | Measurement |
|--------|--------|-------------|
| Health Check Response | < 100ms | P95 |
| API Response | < 200ms | P95 |
| Throughput | > 100 req/s | Sustained |
| Concurrent Connections | 50+ | Stable |
| Uptime | > 99% | 24h period |

## Writing New Tests

### Basic Test Structure
```typescript
describe('Feature Name', () => {
  describe('Specific Functionality', () => {
    it('should do something specific', async () => {
      // Arrange
      const testData = setupTestData();

      // Act
      const result = await performAction(testData);

      // Assert
      expect(result).toBe(expectedValue);
    });
  });
});
```

### Using Test Server
```typescript
import { createTestServer } from './__tests__/helpers/test-server';

describe('API Tests', () => {
  let server: TestServer;

  beforeAll(async () => {
    server = createTestServer();
    await server.waitUntilReady();
  });

  it('should test endpoint', async () => {
    const response = await server.get('/api/endpoint');
    expect(response.status).toBe(200);
  });
});
```

### Performance Testing
```typescript
it('should meet performance requirements', async () => {
  const metrics = await server.measureResponseTime('/api/health', 100);

  expect(metrics.avg).toBeLessThan(100);
  expect(metrics.p95).toBeLessThan(200);
});
```

## Continuous Integration

Tests are automatically run on:
- Pull requests
- Commits to main branch
- Scheduled nightly runs

### CI Configuration
```yaml
# .github/workflows/test.yml
- name: Run Tests
  run: npm run test:ci

- name: Upload Coverage
  uses: codecov/codecov-action@v3
```

## Troubleshooting

### Tests Timeout
- Increase `TEST_TIMEOUT` in `.env.test`
- Check if services are running
- Verify network connectivity

### Coverage Below Threshold
- Add more test cases
- Test edge cases
- Cover error paths

### Flaky Tests
- Add retry logic
- Increase wait times
- Use `waitFor` utility

### Performance Tests Fail
- Check system resources
- Reduce concurrent load
- Adjust timeout values

## Best Practices

1. **Test Independence**: Each test should be independent and not rely on others
2. **Clear Assertions**: Use descriptive expect statements
3. **Setup/Teardown**: Clean up resources after tests
4. **Meaningful Names**: Use descriptive test names
5. **AAA Pattern**: Arrange, Act, Assert structure
6. **Mock External Dependencies**: Isolate unit tests
7. **Test Edge Cases**: Cover error conditions
8. **Performance Testing**: Include in CI pipeline
9. **Regular Updates**: Keep tests current with code changes
10. **Documentation**: Comment complex test logic

## Metrics and Reporting

### Coverage Report
After running tests with coverage:
```bash
npm test -- --coverage
open coverage/lcov-report/index.html
```

### Test Results
View detailed test results in console or CI logs.

### Performance Metrics
Performance tests output metrics to console:
```
Performance baseline:
  Average: 45.23ms
  Min: 12ms
  Max: 156ms
```

## Contributing

When adding new features:
1. Write tests first (TDD)
2. Ensure coverage meets threshold
3. Update this README if needed
4. Run full test suite before committing

## Support

For issues or questions:
- Check existing tests for examples
- Review test utilities documentation
- Consult Jest documentation: https://jestjs.io/