# Test Suite Quick Start Guide
## Installation
```bash
npm install
```
## Run Tests
```bash
# Run all tests
npm test
# Watch mode (auto-rerun)
npm run test:watch
# With coverage
npm run test:coverage
# Interactive UI
npm run test:ui
```
## Test File Structure
```
tests/
├── setup.ts # Global setup (runs first)
├── helpers/ # Reusable test utilities
│ ├── mock-fetch.ts # HTTP mocking helpers
│ └── test-data.ts # Test data factories
├── utils/ # Utility function tests
│ └── hmac.test.ts
├── client/ # HTTP client tests
│ └── KomodoClient.test.ts
├── auth/ # Authentication tests
│ └── AuthManager.test.ts
├── modules/ # MCP tool tests
│ ├── auth.test.ts
│ └── user.test.ts
└── integration/ # End-to-end tests
└── server.test.ts
```
## Writing Your First Test
```typescript
import { describe, it, expect } from 'vitest';
import { mockFetchSuccess } from '../helpers/mock-fetch';
describe('My Feature', () => {
it('should work correctly', async () => {
// Arrange
const mockFetch = mockFetchSuccess({ data: 'test' });
global.fetch = mockFetch as any;
// Act
const response = await fetch('/api/test');
const data = await response.json();
// Assert
expect(data).toEqual({ data: 'test' });
});
});
```
## Common Patterns
### Mock Successful Response
```typescript
const mock = mockFetchSuccess({ result: 'success' });
```
### Mock Error Response
```typescript
const mock = mockFetchError('Error message', { status: 404 });
```
### Create Test Data
```typescript
import { createTestUser } from '../helpers/test-data';
const user = createTestUser({ admin: true });
```
### Test Async Functions
```typescript
it('should complete async operation', async () => {
const result = await asyncFunction();
expect(result).toBeDefined();
});
```
## Debugging Tests
### Run Single Test File
```bash
npx vitest run tests/client/KomodoClient.test.ts
```
### Run Tests Matching Pattern
```bash
npx vitest run --grep "authentication"
```
### Verbose Output
```bash
npx vitest run --reporter=verbose
```
## Test Checklist
When writing tests, ensure you:
- [ ] Test success cases
- [ ] Test error cases
- [ ] Test edge cases (empty, null, invalid)
- [ ] Mock external dependencies
- [ ] Use descriptive test names
- [ ] Follow AAA pattern (Arrange, Act, Assert)
- [ ] Clean up after tests
- [ ] Run tests before committing
## Coverage Report
```bash
npm run test:coverage
# Open coverage/index.html to view report
```
## Common Issues
### Mock Not Working
```typescript
// ❌ Wrong
fetch('/api/test');
// ✅ Correct
global.fetch = mockFetch as any;
await fetch('/api/test');
```
### Async Test Not Waiting
```typescript
// ❌ Wrong
it('test', () => {
asyncFunction(); // Not awaited!
});
// ✅ Correct
it('test', async () => {
await asyncFunction();
});
```
### Environment Variables Not Set
```typescript
// Check tests/setup.ts - variables are set there
expect(process.env.KOMODO_URL).toBeDefined();
```
## Next Steps
1. Read `tests/README.md` for detailed documentation
2. Review `docs/TESTING.md` for comprehensive guide
3. Explore existing test files as examples
4. Start writing tests for new features!
## Need Help?
- Check test output errors
- Review existing test files
- Read Vitest docs: https://vitest.dev/
- Ask team members
Happy Testing! 🧪
