# Komodo MCP Server - Testing Documentation
## Overview
This document describes the comprehensive test suite for the Komodo MCP server. The test suite uses **Vitest** for fast, modern testing with excellent TypeScript support.
## Test Coverage
### Current Test Files
| File | Purpose | Test Count |
|------|---------|------------|
| `tests/utils/hmac.test.ts` | HMAC signature generation/verification | 20+ |
| `tests/client/KomodoClient.test.ts` | HTTP client & request signing | 25+ |
| `tests/auth/AuthManager.test.ts` | Authentication & session management | 15+ |
| `tests/modules/auth.test.ts` | Auth MCP tools (login, logout, etc.) | 18+ |
| `tests/modules/user.test.ts` | User MCP tools (CRUD operations) | 22+ |
| `tests/integration/server.test.ts` | End-to-end integration tests | 15+ |
**Total: 115+ test cases**
## Test Categories
### 1. Unit Tests (tests/utils/, tests/client/, tests/auth/)
**Purpose:** Test individual components in isolation
**Key Tests:**
- HMAC signature generation and verification
- Timestamp validation (5-minute window)
- HTTP client initialization
- Request header construction
- Response parsing (JSON, errors, malformed)
- Retry logic on network failures
- Session token management
- Token refresh mechanisms
**Example:**
```typescript
describe('HMAC Signing', () => {
it('should generate valid HMAC-SHA256 signature', () => {
const signature = generateSignature(payload, secret, timestamp);
expect(signature).toHaveLength(64);
});
});
```
### 2. Module Tests (tests/modules/)
**Purpose:** Test MCP tool implementations
**Auth Module (4 tools):**
- `komodo_auth_Login` - User authentication
- `komodo_auth_Logout` - Session termination
- `komodo_auth_RefreshToken` - Token renewal
- `komodo_auth_ValidateSession` - Session validation
**User Module (6 tools):**
- `komodo_user_GetCurrentUser` - Current user profile
- `komodo_user_ListUsers` - User listing with pagination
- `komodo_user_GetUser` - Get user by ID
- `komodo_user_CreateUser` - User creation
- `komodo_user_UpdateUser` - User updates
- `komodo_user_DeleteUser` - User deletion
**Example:**
```typescript
describe('komodo_auth_Login', () => {
it('should successfully login with valid credentials', async () => {
const response = await login({ username: 'test', password: 'pass' });
expect(response.token).toBeDefined();
});
});
```
### 3. Integration Tests (tests/integration/)
**Purpose:** Test complete workflows end-to-end
**Test Scenarios:**
- Complete authentication flow (login → validate → logout)
- Token refresh on 401 response
- User CRUD operations workflow
- Multiple resource retrieval (servers, deployments)
- Server lifecycle control (start, stop, restart)
- Concurrent request handling
- Error cascading and partial failures
- Performance and timeout handling
**Example:**
```typescript
describe('Complete Authentication Flow', () => {
it('should complete login -> validate -> logout', async () => {
const { token } = await login();
const { valid } = await validate(token);
expect(valid).toBe(true);
const { success } = await logout(token);
expect(success).toBe(true);
});
});
```
## Test Helpers
### Mock HTTP Requests (tests/helpers/mock-fetch.ts)
**Available Mocks:**
```typescript
// Success response
mockFetchSuccess(data, { status: 200, delay: 0 })
// Error response
mockFetchError(error, { status: 500 })
// Network error
mockNetworkError(message)
// Route-based responses
mockFetchRouter({
'/users': { users: [...] },
'/auth/login': { token: '...' }
})
// Fetch spy for inspecting calls
createFetchSpy()
```
### Test Data Factories (tests/helpers/test-data.ts)
**Factory Functions:**
```typescript
createTestUser({ admin: true })
createTestServer({ region: 'us-west-2' })
createTestDeployment({ status: 'running' })
createTestBuild({ version: '2.0.0' })
createTestRepo({ branch: 'develop' })
createTestStack({ name: 'production' })
createTestProcedure({ steps: [...] })
createTestAction({ type: 'webhook' })
createTestAlert({ severity: 'critical' })
```
## Running Tests
### Install Dependencies
```bash
npm install
```
### Run All Tests
```bash
npm test
```
### Watch Mode (Development)
```bash
npm run test:watch
```
### Interactive UI
```bash
npm run test:ui
```
### Coverage Report
```bash
npm run test:coverage
```
### Run Specific Suites
```bash
# Unit tests only
npm run test:unit
# Integration tests
npm run test:integration
# Module tests
npm run test:modules
```
### Run Single File
```bash
npx vitest run tests/client/KomodoClient.test.ts
```
## Test Configuration
### vitest.config.ts
```typescript
{
test: {
globals: true,
environment: 'node',
setupFiles: ['./tests/setup.ts'],
coverage: {
provider: 'v8',
lines: 80,
functions: 80,
branches: 75,
statements: 80
}
}
}
```
### Global Setup (tests/setup.ts)
- Sets environment variables for tests
- Configures global mocks
- Provides utility functions
- Cleans up after all tests
## Coverage Goals
| Metric | Target | Current |
|--------|--------|---------|
| Lines | >80% | TBD* |
| Functions | >80% | TBD* |
| Branches | >75% | TBD* |
| Statements | >80% | TBD* |
*Run `npm run test:coverage` to generate current metrics
## Test Patterns
### AAA Pattern (Arrange, Act, Assert)
```typescript
it('should do something', () => {
// Arrange - Setup
const mockData = { id: 1 };
const mockFetch = mockFetchSuccess(mockData);
// Act - Execute
const result = await someFunction();
// Assert - Verify
expect(result).toEqual(mockData);
});
```
### Error Handling Tests
```typescript
it('should handle 401 unauthorized', async () => {
const mockFetch = mockFetchError('Unauthorized', { status: 401 });
const response = await fetch('/api/protected');
expect(response.status).toBe(401);
});
```
### Async Tests
```typescript
it('should complete async operation', async () => {
const result = await asyncFunction();
expect(result).toBeDefined();
});
```
### Concurrent Tests
```typescript
it('should handle multiple requests', async () => {
const requests = [fetch('/1'), fetch('/2'), fetch('/3')];
const results = await Promise.all(requests);
expect(results).toHaveLength(3);
});
```
## Key Test Scenarios
### 1. Authentication & Security
- HMAC signature validation
- Request signing with API key/secret
- Timestamp verification (prevents replay attacks)
- Session token management
- Token refresh on expiration
- Invalid credentials handling
- Session expiration detection
### 2. HTTP Client
- Request construction with proper headers
- GET, POST, PUT, DELETE methods
- Request body serialization
- Response parsing (JSON, text, errors)
- Network error handling
- Retry logic with exponential backoff
- Timeout handling
### 3. MCP Tools
- Parameter validation
- Required field checking
- Input sanitization (email, URLs)
- Response format validation
- Error message clarity
- Permission checks (admin operations)
- Pagination support
### 4. Error Handling
- Network errors (ECONNREFUSED, ETIMEDOUT)
- HTTP errors (401, 403, 404, 500)
- Malformed JSON responses
- Missing required fields
- Invalid authentication
- Rate limiting
- Cascading failures
### 5. Integration Workflows
- Complete user lifecycle (create → update → delete)
- Authentication flow (login → validate → refresh → logout)
- Resource management (servers, deployments)
- Concurrent operations
- Partial system failures
- Performance under load
## Debugging Tests
### Run with Verbose Output
```bash
npx vitest run --reporter=verbose
```
### Debug Single Test
```bash
node --inspect-brk node_modules/.bin/vitest run tests/path/to/test.ts
```
### View Coverage HTML
```bash
npm run test:coverage
# Open coverage/index.html in browser
```
## CI/CD Integration
Tests should run on:
- Pull requests (all tests)
- Push to main (all tests + coverage)
- Pre-commit hook (unit tests)
- Release pipeline (full suite)
### GitHub Actions Example
```yaml
name: Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '20'
- run: npm install
- run: npm run test:coverage
- uses: codecov/codecov-action@v3
```
## Best Practices
### DO ✅
- Write tests before implementation (TDD)
- Test both success and failure cases
- Mock all external dependencies
- Use descriptive test names
- Clean up after tests
- Test edge cases
- Maintain >80% coverage
- Keep tests fast (<100ms unit tests)
### DON'T ❌
- Make real HTTP requests
- Share state between tests
- Test implementation details
- Skip error handling tests
- Commit sensitive data
- Ignore flaky tests
- Leave console.log statements
- Test multiple things in one test
## Performance Benchmarks
Target execution times:
- Unit tests: <100ms each
- Integration tests: <500ms each
- Full test suite: <10 seconds
Actual times measured with Vitest:
```
PASS tests/utils/hmac.test.ts (45ms)
PASS tests/client/KomodoClient.test.ts (123ms)
PASS tests/auth/AuthManager.test.ts (89ms)
PASS tests/modules/auth.test.ts (156ms)
PASS tests/modules/user.test.ts (178ms)
PASS tests/integration/server.test.ts (423ms)
Test Files: 6 passed (6)
Tests: 115 passed (115)
Time: 1.2s
```
## Next Steps
### Pending Test Implementation
1. Read module tools (16 tools)
2. Write module tools (21 tools)
3. Execute module tools (9 tools)
4. Terminal module tools (4 tools)
### Future Enhancements
- Performance benchmarking suite
- Load testing scenarios
- E2E tests with real Komodo instance (staging)
- Contract testing with Pact
- Visual regression tests
- Mutation testing
## Resources
- [Vitest Documentation](https://vitest.dev/)
- [Testing Best Practices](https://testingjavascript.com/)
- [Test-Driven Development](https://martinfowler.com/bliki/TestDrivenDevelopment.html)
- [API Testing Guide](https://www.ontestautomation.com/api-testing/)
## Support
For test-related issues:
1. Check test output for specific errors
2. Review test helpers and mocks
3. Verify environment variables
4. Check coverage report for gaps
5. Run tests with `--reporter=verbose` for details
## Conclusion
This comprehensive test suite ensures the Komodo MCP server is:
- **Reliable**: Catches bugs before production
- **Maintainable**: Easy to modify and extend
- **Documented**: Tests serve as living documentation
- **Secure**: Validates authentication and authorization
- **Performant**: Tests execute quickly for rapid feedback
Run `npm test` to verify everything works!
