# Test Suite for Searchcraft MCP Server
This directory contains the test suite for the Searchcraft MCP Server, built with Vitest.
## Test Structure
```
test/
├── setup.ts # Global test setup and MSW configuration
├── mocks/
│ ├── fixtures.ts # Test data fixtures
│ └── searchcraft-api.ts # MSW handlers for mocking Searchcraft API
├── unit/
│ ├── helpers.test.ts # Tests for helper functions
│ ├── create-mcp-server.test.ts # Tests for MCP server creation
│ ├── json-analyzer.test.ts # Tests for JSON analysis logic
│ └── tools/ # Tests for tool handlers
│ ├── index-tools.test.ts
│ ├── document-tools.test.ts
│ └── authentication-tools.test.ts
└── integration/
└── http-server.test.ts # Tests for Express HTTP endpoints
```
## Running Tests
### Run all tests
```bash
npm test
# or
npm run test:run
```
### Run tests in watch mode
```bash
npm run test:watch
```
### Run tests with coverage
```bash
npm run test:coverage
```
### Run tests with UI
```bash
npm run test:ui
```
## Test Coverage
Current coverage focuses on:
### High Coverage (>80%)
- ✅ **helpers.ts** (84.61%) - Core utility functions
- ✅ **json-analyzer.ts** (93.82%) - JSON structure analysis
- ✅ **create-mcp-server.ts** (100%) - Server creation
### Integration Tests
- ✅ **HTTP Server** - Express endpoints (/health, /mcp)
- ✅ **API Mocking** - MSW for Searchcraft API calls
### Unit Tests
- ✅ **Configuration** - Environment variable validation
- ✅ **Logging** - Debug logging with levels
- ✅ **Document Preparation** - f64 field conversion
- ✅ **JSON Analysis** - Schema generation from JSON
- ✅ **Array Extraction** - Finding content arrays in nested objects
- ✅ **Document Flattening** - Preparing documents for Searchcraft
## Testing Strategy
### 1. Unit Tests
Test individual functions in isolation:
- Helper functions (config, logging, document preparation)
- JSON analysis and schema generation
- Type detection and field configuration
### 2. Integration Tests
Test components working together:
- HTTP endpoints with mocked Searchcraft API
- Server creation and initialization
- Error handling and edge cases
### 3. Mocking Strategy
- **MSW (Mock Service Worker)** - Mock Searchcraft API calls
- **Environment Variables** - Mock config for tests
- **Global Variables** - Mock `__PACKAGE_VERSION__` for tests
## Writing New Tests
### Example Unit Test
```typescript
import { describe, it, expect } from 'vitest';
import { myFunction } from '../../src/my-module';
describe('myFunction', () => {
it('should do something', () => {
const result = myFunction('input');
expect(result).toBe('expected');
});
});
```
### Example with API Mocking
```typescript
import { describe, it, expect } from 'vitest';
import { http, HttpResponse } from 'msw';
import { server } from '../setup';
describe('API Test', () => {
it('should handle API response', async () => {
server.use(
http.get('http://localhost:8000/endpoint', () => {
return HttpResponse.json({ data: 'test' });
})
);
// Your test code here
});
});
```
## Coverage Goals
- **Core Utilities**: 80%+ (helpers, analyzers)
- **Tool Handlers**: 60%+ (business logic)
- **Integration**: 70%+ (HTTP endpoints)
## CI/CD Integration
Tests are designed to run in CI/CD pipelines:
- Fast execution (~400ms for 89 tests)
- No external dependencies required
- All API calls mocked with MSW
- Environment variables mocked in setup
## Troubleshooting
### Tests failing with "ReferenceError: __PACKAGE_VERSION__ is not defined"
This global is mocked in `test/setup.ts`. Make sure the setup file is being loaded.
### MSW handlers not working
Check that the MSW server is properly initialized in `test/setup.ts` and handlers are defined in `test/mocks/searchcraft-api.ts`.
### Environment variables not set
Environment variables are mocked in `test/setup.ts`. Add any new required variables there.
## Future Improvements
- [ ] Add E2E tests with real MCP client
- [ ] Add performance benchmarks
- [ ] Add snapshot testing for schema generation
- [ ] Increase tool handler coverage with better MCP SDK mocking
- [ ] Add mutation testing
