Skip to content

Commit e073d76

Browse files
author
Jose Luis Moreno
committed
refactor of test documentation
1 parent 0fd7518 commit e073d76

File tree

2 files changed

+138
-123
lines changed

2 files changed

+138
-123
lines changed

‎tests/README.md‎

Lines changed: 9 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,15 @@ tests/
2424
├── integration/ # Integration tests with real APIs
2525
│ ├── test_mcp_application.py # Comprehensive MCP functionality tests
2626
│ ├── test_real_api.py # Direct API client integration tests
27-
│ └── test_real_api_tool_validation.py # FastMCP tool validation tests
27+
│ ├── test_real_api_tool_validation.py # FastMCP tool validation tests
28+
│ ├── test_authentication.py # Authentication flow integration tests
29+
│ ├── test_cross_service.py # Jira-Confluence cross-service tests
30+
│ ├── test_mcp_protocol.py # FastMCP server protocol tests
31+
│ ├── test_content_processing.py # HTML/Markdown conversion tests
32+
│ ├── test_ssl_verification.py # SSL certificate handling tests
33+
│ ├── test_proxy.py # HTTP/HTTPS/SOCKS proxy tests
34+
│ ├── test_transport_lifecycle.py # Transport lifecycle tests
35+
│ └── test_stdin_monitoring_fix.py # STDIN monitoring fix tests
2836
├── utils/ # Test utilities framework
2937
│ ├── factories.py # Data factories
3038
│ ├── mocks.py # Mock utilities
@@ -35,111 +43,6 @@ tests/
3543
└── confluence_mocks.py # Static Confluence mock data
3644
```
3745

38-
## Integration Tests
39-
40-
### MCP Application Tests (`test_mcp_application.py`)
41-
42-
Comprehensive integration tests that validate MCP Atlassian functionality using real API calls. These tests validate the complete user workflow from a business perspective.
43-
44-
**Test Coverage**: 19 comprehensive integration tests covering all major functionality
45-
**Environments**: Both Cloud and Server/Data Center deployments
46-
**Execution**: Requires `--integration` flag and proper environment configuration
47-
48-
#### Running Integration Tests
49-
50-
```bash
51-
# Run all integration tests (Server/DC)
52-
uv run --env-file .env.test pytest tests/integration/test_mcp_application.py --integration -v
53-
54-
# Run all integration tests (Cloud)
55-
uv run --env-file .env.realcloud pytest tests/integration/test_mcp_application.py --integration -v
56-
57-
# Run specific test
58-
uv run --env-file .env.test pytest tests/integration/test_mcp_application.py::TestMCPApplication::test_search_functionality --integration -v
59-
```
60-
61-
### Real API Client Tests (`test_real_api.py`)
62-
63-
Direct API client integration tests that validate core API functionality with real Atlassian instances. These tests focus on API client behavior, lifecycle operations, and data handling.
64-
65-
**Test Coverage**: Direct API client testing (create, read, update, delete operations)
66-
**Environments**: Both Cloud and Server/Data Center deployments
67-
**Execution**: Requires `--integration` flag and proper environment configuration
68-
69-
#### Running Real API Client Tests
70-
71-
```bash
72-
# Run all real API client tests (Server/DC)
73-
uv run --env-file .env.test pytest tests/integration/test_real_api.py --integration -v
74-
75-
# Run all real API client tests (Cloud)
76-
uv run --env-file .env.realcloud pytest tests/integration/test_real_api.py --integration -v
77-
78-
# Run specific test
79-
uv run --env-file .env.test pytest tests/integration/test_real_api.py::TestRealJiraAPI::test_complete_issue_lifecycle --integration -v
80-
```
81-
82-
### FastMCP Tool Validation Tests (`test_real_api_tool_validation.py`)
83-
84-
FastMCP tool validation tests that verify MCP tool functionality with real API data. These tests focus on the MCP tool layer and validate that tools return proper data structures.
85-
86-
**Test Coverage**: FastMCP tool validation (jira_get_issue, jira_search, confluence_get_page, etc.)
87-
**Environments**: Both Cloud and Server/Data Center deployments
88-
**Execution**: Requires `--use-real-data` flag and proper environment configuration
89-
90-
#### Running FastMCP Tool Validation Tests
91-
92-
```bash
93-
# Run all FastMCP tool validation tests (Server/DC)
94-
uv run --env-file .env.test pytest tests/integration/test_real_api_tool_validation.py --use-real-data -v
95-
96-
# Run all FastMCP tool validation tests (Cloud)
97-
uv run --env-file .env.realcloud pytest tests/integration/test_real_api_tool_validation.py --use-real-data -v
98-
99-
# Run specific test
100-
uv run --env-file .env.test pytest tests/integration/test_real_api_tool_validation.py::TestRealJiraToolValidation::test_jira_search_with_start_at --use-real-data -v
101-
```
102-
103-
#### Test Results Summary
104-
105-
**Server/DC (.env.test)**: 6 failed, 18 passed, 23 skipped, 10 errors
106-
**Cloud (.env.realcloud)**: 24 passed, 23 skipped, 10 errors
107-
108-
**Note**: Some tests fail on Server/DC due to Epic functionality differences, but pass on Cloud. The errors are due to fixture scope mismatches and can be ignored.
109-
110-
#### Environment Variables Required
111-
112-
**Server/Data Center (.env.test)**:
113-
```bash
114-
JIRA_CLOUD=false
115-
JIRA_URL=https://jira.your-company.com
116-
JIRA_PERSONAL_TOKEN=your_personal_access_token
117-
JIRA_TEST_PROJECT_KEY=YOUR_PROJECT
118-
JIRA_TEST_ISSUE_KEY=YOUR_PROJECT-123
119-
```
120-
121-
**Cloud (.env.realcloud)**:
122-
```bash
123-
JIRA_CLOUD=true
124-
JIRA_URL=https://your-company.atlassian.net
125-
[email protected]
126-
JIRA_API_TOKEN=your_api_token
127-
JIRA_TEST_PROJECT_KEY=YOUR_PROJECT
128-
JIRA_TEST_ISSUE_KEY=YOUR_PROJECT-123
129-
```
130-
131-
#### Key Test Scenarios
132-
133-
- **Core Search & Retrieval**: Validates JQL search and issue retrieval
134-
- **Comment Functionality**: Tests comment addition and verification with exact content matching
135-
- **Epic Management**: Validates agile Epic functionality and linking
136-
- **Content Processing**: Tests ADF parsing for Cloud environments
137-
- **Environment Consistency**: Ensures consistent behavior across Cloud and Server/DC
138-
- **Project Management**: Validates project discovery and access
139-
- **Field Operations**: Tests custom field discovery and usage
140-
- **Agile Operations**: Validates board and sprint functionality
141-
- **Batch Operations**: Tests bulk issue creation and changelog retrieval
142-
- **Error Handling**: Validates robust error handling across environments
14346

14447
## Key Features
14548

‎tests/integration/README.md‎

Lines changed: 129 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,108 @@ This directory contains integration tests for the MCP Atlassian project. These t
44

55
## Test Categories
66

7-
### 1. Authentication Integration (`test_authentication.py`)
7+
### 1. MCP Application Tests (`test_mcp_application.py`)
8+
9+
Comprehensive integration tests that validate MCP Atlassian functionality using real API calls. These tests validate the complete user workflow from a business perspective.
10+
11+
**Test Coverage**: 19 comprehensive integration tests covering all major functionality
12+
**Environments**: Both Cloud and Server/Data Center deployments
13+
**Execution**: Requires `--integration` flag and proper environment configuration
14+
15+
#### Key Test Scenarios
16+
17+
- **Core Search & Retrieval**: Validates JQL search and issue retrieval
18+
- **Comment Functionality**: Tests comment addition and verification with exact content matching
19+
- **Epic Management**: Validates agile Epic functionality and linking
20+
- **Content Processing**: Tests ADF parsing for Cloud environments
21+
- **Environment Consistency**: Ensures consistent behavior across Cloud and Server/DC
22+
- **Project Management**: Validates project discovery and access
23+
- **Field Operations**: Tests custom field discovery and usage
24+
- **Agile Operations**: Validates board and sprint functionality
25+
- **Batch Operations**: Tests bulk issue creation and changelog retrieval
26+
- **Error Handling**: Validates robust error handling across environments
27+
28+
#### Running MCP Application Tests
29+
30+
```bash
31+
# Run all MCP application tests (Server/DC)
32+
uv run --env-file .env.test pytest tests/integration/test_mcp_application.py --integration -v
33+
34+
# Run all MCP application tests (Cloud)
35+
uv run --env-file .env.realcloud pytest tests/integration/test_mcp_application.py --integration -v
36+
37+
# Run specific test
38+
uv run --env-file .env.test pytest tests/integration/test_mcp_application.py::TestMCPApplication::test_search_functionality --integration -v
39+
```
40+
41+
### 2. Real API Client Tests (`test_real_api.py`)
42+
43+
Direct API client integration tests that validate core API functionality with real Atlassian instances. These tests focus on API client behavior, lifecycle operations, and data handling.
44+
45+
**Test Coverage**: Direct API client testing (create, read, update, delete operations)
46+
**Environments**: Both Cloud and Server/Data Center deployments
47+
**Execution**: Requires `--integration` flag and proper environment configuration
48+
49+
#### Test Details
50+
51+
- **Complete Lifecycles**: Create/update/delete workflows
52+
- **Attachments**: File upload/download operations
53+
- **Search Operations**: JQL and CQL queries
54+
- **Bulk Operations**: Multiple item creation
55+
- **Rate Limiting**: API throttling behavior
56+
- **Cross-Service Linking**: Jira-Confluence integration
57+
58+
#### Running Real API Client Tests
59+
60+
```bash
61+
# Run all real API client tests (Server/DC)
62+
uv run --env-file .env.test pytest tests/integration/test_real_api.py --integration -v
63+
64+
# Run all real API client tests (Cloud)
65+
uv run --env-file .env.realcloud pytest tests/integration/test_real_api.py --integration -v
66+
67+
# Run specific test
68+
uv run --env-file .env.test pytest tests/integration/test_real_api.py::TestRealJiraAPI::test_complete_issue_lifecycle --integration -v
69+
```
70+
71+
### 3. FastMCP Tool Validation Tests (`test_real_api_tool_validation.py`)
72+
73+
FastMCP tool validation tests that verify MCP tool functionality with real API data. These tests focus on the MCP tool layer and validate that tools return proper data structures.
74+
75+
**Test Coverage**: FastMCP tool validation (jira_get_issue, jira_search, confluence_get_page, etc.)
76+
**Environments**: Both Cloud and Server/Data Center deployments
77+
**Execution**: Requires `--use-real-data` flag and proper environment configuration
78+
79+
#### Test Details
80+
81+
- **Tool Validation**: Validates individual MCP tools with real API responses
82+
- **Data Structure Verification**: Ensures tools return properly formatted data
83+
- **Parameter Handling**: Tests tool parameter validation and processing
84+
- **Error Response Testing**: Validates proper error handling in tool layer
85+
- **Pagination Testing**: Tests pagination functionality across different tools
86+
- **Field Discovery**: Tests dynamic field discovery and usage
87+
88+
#### Running FastMCP Tool Validation Tests
89+
90+
```bash
91+
# Run all FastMCP tool validation tests (Server/DC)
92+
uv run --env-file .env.test pytest tests/integration/test_real_api_tool_validation.py --use-real-data -v
93+
94+
# Run all FastMCP tool validation tests (Cloud)
95+
uv run --env-file .env.realcloud pytest tests/integration/test_real_api_tool_validation.py --use-real-data -v
96+
97+
# Run specific test
98+
uv run --env-file .env.test pytest tests/integration/test_real_api_tool_validation.py::TestRealJiraToolValidation::test_jira_search_with_start_at --use-real-data -v
99+
```
100+
101+
#### Test Results Summary
102+
103+
**Server/DC (.env.test)**: 6 failed, 18 passed, 23 skipped, 10 errors
104+
**Cloud (.env.realcloud)**: 24 passed, 23 skipped, 10 errors
105+
106+
**Note**: Some tests fail on Server/DC due to Epic functionality differences, but pass on Cloud. The errors are due to fixture scope mismatches and can be ignored.
107+
108+
### 4. Authentication Integration (`test_authentication.py`)
8109
Tests various authentication flows including OAuth, Basic Auth, and PAT tokens.
9110

10111
- **OAuth Token Refresh**: Validates token refresh on expiration
@@ -13,7 +114,7 @@ Tests various authentication flows including OAuth, Basic Auth, and PAT tokens.
13114
- **Fallback Patterns**: Tests authentication fallback (OAuth → Basic → PAT)
14115
- **Mixed Scenarios**: Tests different authentication combinations
15116

16-
### 2. Cross-Service Integration (`test_cross_service.py`)
117+
### 5. Cross-Service Integration (`test_cross_service.py`)
17118
Tests integration between Jira and Confluence services.
18119

19120
- **User Resolution**: Consistent user handling across services
@@ -22,7 +123,7 @@ Tests integration between Jira and Confluence services.
22123
- **Configuration Sharing**: SSL and proxy settings consistency
23124
- **Service Discovery**: Dynamic service availability detection
24125

25-
### 3. MCP Protocol Integration (`test_mcp_protocol.py`)
126+
### 6. MCP Protocol Integration (`test_mcp_protocol.py`)
26127
Tests the FastMCP server implementation and tool management.
27128

28129
- **Tool Discovery**: Dynamic tool listing based on configuration
@@ -31,7 +132,7 @@ Tests the FastMCP server implementation and tool management.
31132
- **Concurrent Execution**: Parallel tool execution support
32133
- **Error Propagation**: Proper error handling through the stack
33134

34-
### 4. Content Processing Integration (`test_content_processing.py`)
135+
### 7. Content Processing Integration (`test_content_processing.py`)
35136
Tests HTML/Markdown conversion and content preprocessing.
36137

37138
- **Roundtrip Conversion**: HTML ↔ Markdown accuracy
@@ -40,15 +141,15 @@ Tests HTML/Markdown conversion and content preprocessing.
40141
- **Edge Cases**: Empty content, malformed HTML, Unicode
41142
- **Cross-Platform**: Content sharing between services
42143

43-
### 5. SSL Verification (`test_ssl_verification.py`)
144+
### 8. SSL Verification (`test_ssl_verification.py`)
44145
Tests SSL certificate handling and verification.
45146

46147
- **SSL Configuration**: Enable/disable verification
47148
- **Custom CA Bundles**: Support for custom certificates
48149
- **Multiple Domains**: SSL adapter mounting for various domains
49150
- **Error Handling**: Certificate validation failures
50151

51-
### 6. Proxy Configuration (`test_proxy.py`)
152+
### 9. Proxy Configuration (`test_proxy.py`)
52153
Tests HTTP/HTTPS/SOCKS proxy support.
53154

54155
- **Proxy Types**: HTTP, HTTPS, and SOCKS5 proxies
@@ -57,16 +158,6 @@ Tests HTTP/HTTPS/SOCKS proxy support.
57158
- **Environment Variables**: Proxy configuration from environment
58159
- **Mixed Configuration**: Proxy + SSL settings
59160

60-
### 7. Real API Tests (`test_real_api.py`)
61-
Tests with actual Atlassian APIs (requires `--use-real-data` flag).
62-
63-
- **Complete Lifecycles**: Create/update/delete workflows
64-
- **Attachments**: File upload/download operations
65-
- **Search Operations**: JQL and CQL queries
66-
- **Bulk Operations**: Multiple item creation
67-
- **Rate Limiting**: API throttling behavior
68-
- **Cross-Service Linking**: Jira-Confluence integration
69-
70161
## Running Integration Tests
71162

72163
### Basic Execution
@@ -98,9 +189,30 @@ export CONFLUENCE_API_TOKEN=your-api-token
98189
export CONFLUENCE_TEST_SPACE_KEY=TEST
99190
```
100191

192+
## Environment Variables Required
193+
194+
### Server/Data Center (.env.test)
195+
```bash
196+
JIRA_CLOUD=false
197+
JIRA_URL=https://jira.your-company.com
198+
JIRA_PERSONAL_TOKEN=your_personal_access_token
199+
JIRA_TEST_PROJECT_KEY=YOUR_PROJECT
200+
JIRA_TEST_ISSUE_KEY=YOUR_PROJECT-123
201+
```
202+
203+
### Cloud (.env.realcloud)
204+
```bash
205+
JIRA_CLOUD=true
206+
JIRA_URL=https://your-company.atlassian.net
207+
[email protected]
208+
JIRA_API_TOKEN=your_api_token
209+
JIRA_TEST_PROJECT_KEY=YOUR_PROJECT
210+
JIRA_TEST_ISSUE_KEY=YOUR_PROJECT-123
211+
```
212+
101213
### Test Markers
102214
- `@pytest.mark.integration` - All integration tests
103-
- `@pytest.mark.anyio` - Async tests supporting multiple backends
215+
- `@pytest.mark.asyncio` - Async tests supporting asyncio backend
104216

105217
## Environment Setup
106218

0 commit comments

Comments
 (0)