@debugmcp/mcp-debugger/docs/archive/refactoring/task-19a-skip-investigation-report.md

Run-time step-through debugging for LLM agents.

# Task 19a: Skip Investigation and Cross-Platform Test Audit Report

## 🔍 **Skip Investigation Results**

### **Total Skip Patterns Found**

Based on comprehensive investigation, the following skip patterns were identified:

#### **1. Explicit Skips (it.skip/describe.skip)**
**Count: 3 tests**

| File | Line | Test Name | Skip Reason |
|------|------|-----------|-------------|
| `tests/adapters/python/integration/python-real-discovery.test.ts` | 144 | `it.skip('should show clear error message when Python is not found on Windows')` | Platform mismatch - Test forces platform to 'win32' but runs on Linux in Act |
| `tests/e2e/mcp-server-smoke-container.test.ts` | 53 | `it.skip('should successfully debug fibonacci.py in containerized server')` | Docker-in-Docker issues - Docker operations are slower than expected in Act |
| `tests/e2e/mcp-server-smoke-container.test.ts` | 135 | `it.skip('should reject absolute paths in container mode')` | Complex volume mount path resolution issues in Act |

#### **2. Conditional Skips (skipIf/runIf)**
**Count: 1 test + 2 dynamic conditions**

| File | Line | Skip Pattern | Condition |
|------|------|--------------|-----------|
| `tests/unit/implementations/process-launcher-impl-debug.test.ts` | 159 | `it.skipIf(process.platform !== 'win32')` | Skips on non-Windows platforms |
| `tests/e2e/full-debug-session.test.ts` | 253 | `describe.skipIf(!process.env.SKIP_PYTHON_TESTS)` | Skips when SKIP_PYTHON_TESTS env var is set |

#### **3. Runtime Skips (this.skip())**
**Count: 2 conditional runtime skips**

| File | Line | Skip Context | Runtime Condition |
|------|------|--------------|-------------------|
| `tests/e2e/mcp-server-smoke-container.test.ts` | 55 | Inside first container test | `if (!dockerAvailable)` |
| `tests/e2e/mcp-server-smoke-container.test.ts` | 137 | Inside second container test | `if (!dockerAvailable)` |

#### **4. Tests Tagged with @requires-python**
**Count: 7 test suites**

These tests are not skipped but are tagged for conditional execution:

1. `tests/adapters/python/integration/python-discovery.failure.test.ts`
2. `tests/adapters/python/integration/python-discovery.success.test.ts`
3. `tests/adapters/python/integration/python-discovery.test.ts`
4. `tests/adapters/python/integration/python-real-discovery.test.ts`
5. `tests/adapters/python/integration/python_debug_workflow.test.ts`
6. `tests/adapters/python/unit/python-adapter.test.ts`
7. `tests/adapters/python/unit/python-utils.test.ts`

### **Summary of Skip Counts**
- **Explicit skips**: 3 tests
- **Conditional skips**: 1 test (platform-based)
- **Environment-based skips**: 1 describe block (SKIP_PYTHON_TESTS)
- **Runtime skips**: 2 tests (Docker availability)
- **Tagged tests**: 7 test suites (not technically skipped, but can be filtered)

**Total unique skip locations: 6** (not counting the @requires-python tags)

## 📊 **Skip Category Analysis**

### **Category A: Docker/Container-Related Skips**
**Count: 2 tests**
- Both in `mcp-server-smoke-container.test.ts`
- Reason: Docker-in-Docker issues in Act environment
- **Recommendation**: Keep skipped, document as architectural debt for CI environment

### **Category B: Platform-Specific Skips**
**Count: 2 tests**
- Python discovery test forcing Windows platform on Linux
- Windows path handling test skipping on non-Windows
- **Recommendation**: Improve platform detection logic

### **Category C: Environment Variable Skips**
**Count: 1 describe block**
- Full debug session Python tests controlled by SKIP_PYTHON_TESTS
- **Recommendation**: Document when/why this variable should be set

### **Category D: Missing Dependency Skips**
**Count: 7 test suites** (tagged, not skipped)
- All @requires-python tests
- **Recommendation**: Consider adding proper skip logic if Python is unavailable

## 🔄 **Failure-Skip Correlation Analysis**

### **Current Test Failures vs Skip Patterns**

Based on the latest test run, the following failures were observed:

#### **E2E Test Failures** (Connection Issues)
- `adapter-switching.test.ts` - "MCP error -32000: Connection closed"
- `error-scenarios.test.ts` - "MCP error -32000: Connection closed"
- `full-debug-session.test.ts` - "MCP error -32000: Connection closed"
- `mcp-server-smoke.test.ts` - "MCP error -32000: Connection closed"
- `mcp-server-smoke-sse.test.ts` - "SSE server exited with code 1"

**Correlation**: These failures are NOT related to skip patterns. They indicate a fundamental connection issue with the MCP server startup.

#### **Build-Related Failures**
- `proxy-startup.test.ts` - "Cannot find module 'proxy-bootstrap.js'"

**Correlation**: No skip pattern exists for this. This is a build artifact issue.

#### **Python Discovery Failures**
- `python-discovery.success.test.ts` - "expected false to be true"

**Correlation**: This test is tagged @requires-python but NOT skipped, which may be causing the failure.

#### **Session Manager Test Failures**
- `session-manager-dry-run.test.ts` - Timeout and event listener issues
- `session-manager-edge-cases.test.ts` - Default executable path issues

**Correlation**: No skip patterns. These are legitimate test failures.

### **Key Finding**: Most current failures are NOT in files with skip patterns, indicating:
1. **Skip patterns are not masking the current failures**
2. **The failures are primarily infrastructure issues** (MCP connection, build artifacts)
3. **Some tests that should be skipped (Python-dependent) are not being skipped**

## 🏗️ **Cross-Platform Compatibility Issues**

### **Identified Path-Related Issues**

1. **Container Path Translation Test** (`container-path-translation.test.ts`)
   - Expected: "examples/python/fibonacci.py:15"
   - Received: "Breakpoint set at C:\path\to\project\examples\python\fibonacci.py:15"
   - **Issue**: Windows backslashes vs Unix forward slashes
   - **Current Status**: Tests have no skips (they probably should)

2. **Platform Detection Logic Issues**
   - `python-real-discovery.test.ts` - Forces `process.platform = 'win32'` on Linux
   - **Current Status**: Correctly skipped with it.skip

3. **File System Assumptions**
   - Multiple tests use `process.platform` checks (70+ occurrences found)
   - Path construction varies between platforms

## 📋 **Skip Logic Quality Assessment**

### **Well-Documented Skips**
- ✅ Container smoke tests - Clear comments about Docker-in-Docker issues
- ✅ Python real discovery test - Clear comment about platform mismatch
- ✅ Windows path test - Clear skipIf condition

### **Poorly Documented Skips**
- ❌ No explicit skip reason in test names/comments for some tests
- ❌ @requires-python tags don't automatically skip when Python unavailable

### **Missing Skips** (Tests that fail but should skip)
1. **All E2E tests** - Should skip when MCP server can't start
2. **Python-dependent tests without proper skip logic** - Currently only tagged
3. **Container path translation tests** - Should skip or document cross-platform issues

## 🎯 **Recommendations**

### **Immediate Actions Needed**
1. **Fix MCP Server Connection Issues** - Primary cause of test failures
2. **Add Skip Logic for Python Tests** - Convert @requires-python tags to actual skips
3. **Document Container Path Issues** - Add architectural debt documentation

### **Skip Categories to Address**

#### **Enable These Tests** (Currently unnecessarily skipped)
- None identified - all current skips appear legitimate

#### **Improve Skip Conditions**
1. Python discovery tests - Add environment detection
2. Container tests - Add proper Docker detection beyond just availability

#### **Add Missing Skips**
1. E2E tests when MCP server unavailable
2. Tests requiring specific build artifacts
3. Cross-platform path tests that can't be fixed

### **Architectural Debt to Document**
1. **Cross-platform path handling** - Needs abstraction layer
2. **Docker-in-Docker limitations** - Act environment specific
3. **Python dependency management** - No automatic skip when unavailable

## 📈 **Summary Statistics**

- **Total Skip Patterns Found**: 6 unique locations
- **Tests with Explicit Skips**: 3
- **Tests with Conditional Skips**: 3
- **Test Suites Tagged (not skipped)**: 7
- **Current Test Failures**: 11+ files
- **Failures in Files with Skips**: 0 (no correlation)
- **Tests Needing Skip Logic**: 5-10 (E2E and Python tests)

## 🔮 **Next Steps for Task 19b/19c**

Based on this investigation:
1. **Priority 1**: Fix MCP server connection issues (not skip-related)
2. **Priority 2**: Implement proper skip logic for Python-dependent tests
3. **Priority 3**: Document cross-platform path issues as architectural debt
4. **Priority 4**: Create skip guidelines to prevent future issues

The investigation reveals that the current test failures are primarily infrastructure issues rather than skip-related problems. The existing skips are mostly legitimate and well-reasoned.