Skip to content

Commit ee7f62d

Browse files
kunwarVivekkunwarVivek
committed
docs(12-01): add comprehensive testing documentation
- Document all test categories (unit, integration, E2E) - Document 20 skipped tests with justifications: - 7 github-project-manager E2E (requires real GitHub API) - 6 resource-management E2E (requires real GitHub API) - 5 metrics-reporting E2E (requires real GitHub API) - 2 GitHubProjectManager integration (conditional on GITHUB_TOKEN) - Add instructions for running tests with real credentials - Add troubleshooting section for common issues - Confirm production release readiness (1474 passing, 0 failed)
1 parent e2e5d8c commit ee7f62d

1 file changed

Lines changed: 183 additions & 0 deletions

File tree

‎docs/TESTING.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Testing Guide
2+
3+
This document provides an overview of the test suite, how to run tests, and documentation of skipped tests with their justifications.
4+
5+
## Test Suite Overview
6+
7+
The test suite contains:
8+
- **1474+ passing tests** across unit, integration, and E2E test categories
9+
- **20 skipped tests** (documented with justifications below)
10+
- **0 failing tests** (required for production release)
11+
12+
### Test Categories
13+
14+
| Category | Description | Location |
15+
|----------|-------------|----------|
16+
| Unit Tests | Test individual components in isolation | `src/__tests__/unit/` |
17+
| Integration Tests | Test service layer interactions | `src/__tests__/integration/` |
18+
| E2E Tests | Test full MCP server and stdio transport | `src/__tests__/e2e/` |
19+
20+
## Running Tests
21+
22+
### Run All Tests
23+
```bash
24+
npm test
25+
```
26+
27+
### Run Specific Test Categories
28+
```bash
29+
# Unit tests only
30+
npm test -- --testPathPattern="unit"
31+
32+
# Integration tests only
33+
npm test -- --testPathPattern="integration"
34+
35+
# E2E tests only
36+
npm test -- --testPathPattern="e2e"
37+
38+
# Specific test file
39+
npm test -- --testPathPattern="stdio-transport"
40+
```
41+
42+
### Watch Mode
43+
```bash
44+
npm run test:watch
45+
```
46+
47+
### Coverage Report
48+
```bash
49+
npm run test:coverage
50+
```
51+
52+
## Skipped Tests
53+
54+
The following tests are intentionally skipped due to their requirements for real external resources.
55+
56+
### E2E Tests Requiring GitHub Credentials
57+
58+
These tests require real GitHub API credentials (`GITHUB_TOKEN`, `GITHUB_OWNER`, `GITHUB_REPO`) because they make actual API calls to create/modify GitHub resources.
59+
60+
| Test Suite | Location | Tests Skipped | Reason |
61+
|------------|----------|---------------|--------|
62+
| GitHub Project Manager E2E | `src/__tests__/e2e/github-project-manager.e2e.ts` | 7 | Creates real roadmaps, milestones, issues, and sprints |
63+
| Resource Management E2E | `src/__tests__/e2e/resource-management.e2e.ts` | 6 | Tests resource lifecycle with real GitHub API |
64+
| Metrics and Reporting E2E | `src/__tests__/e2e/metrics-reporting.e2e.ts` | 5 | Creates real milestones and issues for metrics testing |
65+
66+
### Integration Tests with Conditional Skip
67+
68+
| Test Suite | Location | Tests Skipped | Reason |
69+
|------------|----------|---------------|--------|
70+
| GitHubProjectManager Integration | `src/__tests__/integration/GitHubProjectManager.test.ts` | 2 | Conditionally skipped when `GITHUB_TOKEN` is not set |
71+
72+
## Running Tests with Real Credentials
73+
74+
To run the normally-skipped E2E tests with real GitHub credentials:
75+
76+
### 1. Set Environment Variables
77+
```bash
78+
export GITHUB_TOKEN="your-github-token"
79+
export GITHUB_OWNER="your-github-username-or-org"
80+
export GITHUB_REPO="your-test-repository"
81+
```
82+
83+
### 2. Enable E2E Tests
84+
85+
The E2E test files use `describe.skip` to skip tests by default. To run them:
86+
87+
1. Edit the test file and change `describe.skip` to `describe`
88+
2. Run the tests: `npm test -- --testPathPattern="github-project-manager"`
89+
3. Remember to revert the change after testing
90+
91+
**Warning:** These tests will create real resources in your GitHub repository. Use a dedicated test repository.
92+
93+
### 3. Integration Tests with Credentials
94+
95+
Integration tests automatically run when `GITHUB_TOKEN` is set:
96+
```bash
97+
GITHUB_TOKEN=your-token npm test -- --testPathPattern="GitHubProjectManager"
98+
```
99+
100+
## Test Structure
101+
102+
```
103+
src/__tests__/
104+
├── e2e/ # End-to-end tests
105+
│ ├── github-project-manager.e2e.ts # [SKIPPED] Real GitHub API
106+
│ ├── resource-management.e2e.ts # [SKIPPED] Real GitHub API
107+
│ ├── metrics-reporting.e2e.ts # [SKIPPED] Real GitHub API
108+
│ ├── mcp-protocol-compliance.e2e.ts # Spawns real server process
109+
│ ├── mcp-server-integration.e2e.ts # Spawns real server process
110+
│ └── stdio-transport.e2e.ts # Spawns real server process
111+
├── integration/ # Service integration tests
112+
│ └── GitHubProjectManager.test.ts # [CONDITIONAL] Needs GITHUB_TOKEN
113+
├── unit/ # Unit tests
114+
│ ├── application/ # Application layer tests
115+
│ ├── domain/ # Domain model tests
116+
│ ├── infrastructure/ # Infrastructure tests
117+
│ └── services/ # Service tests
118+
└── test-utils/ # Test utilities and mocks
119+
```
120+
121+
## Test Requirements
122+
123+
### For All Tests
124+
- Node.js 22+
125+
- `npm install` completed
126+
- `npm run build` completed (for E2E tests that spawn server)
127+
128+
### For E2E Tests (stdio transport)
129+
The MCP server E2E tests (`stdio-transport.e2e.ts`, `mcp-protocol-compliance.e2e.ts`) spawn a real server process and communicate via stdio. They require:
130+
- A successful build (`npm run build`)
131+
- No port conflicts
132+
- Sufficient test timeout (15-30 seconds)
133+
134+
### For GitHub API Tests
135+
- Valid `GITHUB_TOKEN` with repo permissions
136+
- `GITHUB_OWNER` set to your username or organization
137+
- `GITHUB_REPO` set to a test repository
138+
139+
## Troubleshooting
140+
141+
### Tests Timeout
142+
E2E tests have extended timeouts (10-30 seconds) because they spawn real processes. If tests still timeout:
143+
```bash
144+
# Increase Jest timeout globally
145+
npm test -- --testTimeout=60000
146+
```
147+
148+
### Server Build Not Found
149+
```
150+
Error: Server build not found. Run `npm run build` first.
151+
```
152+
Solution: Run `npm run build` before running E2E tests.
153+
154+
### Jest Doesn't Exit
155+
```
156+
Jest did not exit one second after the test run has completed.
157+
```
158+
This warning appears with E2E tests that spawn processes. Use `--forceExit` if needed:
159+
```bash
160+
npm test -- --forceExit
161+
```
162+
163+
### Detecting Open Handles
164+
```bash
165+
npm test -- --detectOpenHandles
166+
```
167+
168+
## Related Documentation
169+
170+
- [AI Features Testing Guide](./testing-guide.md) - Detailed testing guide for AI-powered features
171+
- [E2E Testing Guide](./e2e-testing-guide.md) - Comprehensive E2E testing documentation
172+
- [API Reference](./API.md) - API documentation for all tools
173+
174+
## Production Release Verification
175+
176+
Before each production release, verify:
177+
178+
1. **All tests pass**: `npm test` shows 0 failed tests
179+
2. **Build succeeds**: `npm run build` completes without errors
180+
3. **Type check passes**: `npm run type-check` (if available) or build includes type checking
181+
4. **Skipped tests documented**: All skipped tests have documented justification (this file)
182+
183+
Current status: **Ready for release** (1474 passing, 0 failed, 20 skipped with justification)

0 commit comments

Comments
 (0)