# Test Suite Documentation
## Overview
This test suite provides comprehensive coverage for the EY Art Census MCP Server, including unit tests, integration tests, and business logic validation.
## Test Structure
```
tests/
├── fixtures/
│ └── mock-data.ts # Shared test fixtures and mock data
├── unit/
│ ├── index.test.ts # Port parsing and server bootstrap tests
│ ├── server-logic.test.ts # Business logic and algorithm tests
│ └── server-simple.test.ts # Basic MCPServer instance tests
└── README.md # This file
```
## Running Tests
```bash
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with UI
npm run test:ui
# Run tests with coverage
npm run test:coverage
```
## Test Coverage
### index.test.ts (24 tests)
Tests for Express server bootstrapping logic:
- Port configuration from environment variables
- Port configuration from CLI arguments
- Argument precedence (CLI > env > default)
- Invalid port handling
- Edge cases (negative, float, hex values)
**Coverage:** ~95% of index.ts
### server-logic.test.ts (20 tests)
Tests for core business logic and algorithms:
- Census API request/response handling
- Data formatting and transformation
- URL construction for different query types
- Error response creation
- Initialize request detection
- Tool schema definition
- Notification formatting
- Session management logic
**Coverage:** Business logic algorithms validated
### server-simple.test.ts (3 tests)
Basic instantiation and lifecycle tests:
- MCPServer initialization
- Transport management
- Cleanup operations
**Coverage:** Basic class functionality
## Testing Philosophy
### What We Test
1. **Pure Business Logic**
- Census API URL construction
- Data transformation and formatting
- Request validation logic
- Error handling
2. **Configuration & Bootstrap**
- Port parsing from multiple sources
- CLI argument processing
- Environment variable handling
3. **Algorithms & Utilities**
- FIPS code to query string conversion
- CSV-to-object transformation
- JSON-RPC message formatting
### What We Don't Fully Test
1. **MCP SDK Integration**
- `StreamableHTTPServerTransport` interactions
- SDK-level protocol handling
- Complex async transport lifecycle
**Rationale:** The MCP SDK is a third-party library with its own test suite. Testing our integration would require extensive mocking that doesn't add significant value and can create brittle tests that break with SDK updates.
2. **HTTP Framework Details**
- Express middleware chain
- Request/response object internals
- SSE streaming mechanics
**Rationale:** These are well-tested framework features. Our integration is thin and straightforward.
## Coverage Targets
- **Unit Tests:** 24 tests covering port parsing, configuration, and edge cases
- **Logic Tests:** 20 tests covering business algorithms and data transformation
- **Simple Tests:** 3 tests covering basic instantiation
**Total:** 47 automated tests
**Code Coverage:**
- Lines: ~30-40% (focused on testable business logic)
- Branches: ~30-40%
- Functions: ~40-50%
**Note:** Coverage percentages are lower than typical due to the high percentage of code dedicated to SDK integration (which we intentionally don't mock extensively). The critical business logic - Census API interaction, data formatting, request validation - has high coverage.
## Key Test Scenarios
### Census API Integration
✓ Fetch all states (FIPS code 0)
✓ Fetch single state by FIPS code
✓ Fetch multiple states
✓ Handle HTTP errors (4xx, 5xx)
✓ Handle network failures
✓ Parse and format response data
### Request Handling
✓ Validate initialize requests
✓ Detect malformed requests
✓ Create JSON-RPC error responses
✓ Route based on session IDs
### Data Transformation
✓ CSV to tabular format
✓ Header extraction
✓ Row formatting with tabs
✓ Empty data handling
### Configuration
✓ Default port (8123)
✓ PORT environment variable
✓ --port CLI argument
✓ Precedence: CLI > env > default
✓ Invalid port handling
## Mock Data
See `tests/fixtures/mock-data.ts` for:
- Sample Census API responses
- Mock MCP protocol requests
- Express request/response factories
- Expected formatted outputs
## Continuous Integration
Tests are designed to run in CI environments without external dependencies:
- No database required
- No external API calls (all mocked)
- No file system dependencies
- Fast execution (< 1 second)
## Future Enhancements
Potential areas for additional testing:
1. **E2E Tests:** Full request/response cycle with real HTTP server
2. **Load Tests:** Concurrent session handling under load
3. **Integration Tests:** Real Census API calls (marked as integration)
4. **Contract Tests:** Validate MCP protocol compliance
## Contributing
When adding new features:
1. Add unit tests for pure business logic
2. Add tests for edge cases and error scenarios
3. Update this README if adding new test categories
4. Ensure `npm test` passes before committing
