# Smoke Tests for ChunkHound

## PURPOSE
Catch critical failures BEFORE they reach users. These tests run in ~10 seconds and prevent:
- Import-time crashes (type annotation errors, syntax errors)
- CLI command failures
- Server startup crashes

## WHEN_TO_RUN
- ALWAYS: Before any commit
- ALWAYS: After modifying type annotations
- ALWAYS: After adding new modules or CLI commands
- AUTOMATED: Should run in CI on every push

## HOW_TO_RUN
```bash
# Quick smoke test (10 seconds)
uv run pytest tests/test_smoke.py -v

# Just import tests (2 seconds)
uv run pytest tests/test_smoke.py::TestModuleImports -v

# Just CLI tests (3 seconds)
uv run pytest tests/test_smoke.py::TestCLICommands -v
```

## WHAT_THEY_TEST

### 1. Module Import Tests
- **Purpose**: Catch syntax/type errors at import time
- **Example Bug Caught**: `_server_config: "Config" | None = None`
- **Coverage**: All chunkhound modules via pkgutil.walk_packages

### 2. CLI Command Tests
- **Purpose**: Ensure CLI doesn't crash on basic operations
- **Coverage**: All major commands with --help flag
- **Special Test**: Direct import of mcp_http_server module

### 3. Server Startup Tests
- **Purpose**: Verify servers can start without immediate crashes
- **Coverage**: MCP HTTP server startup (2-second timeout)

### 4. Type Annotation Pattern Tests
- **Purpose**: Detect problematic patterns before they cause crashes
- **Coverage**: Scans for forward reference union patterns

## REAL_WORLD_EXAMPLE
The type annotation bug that crashed MCP HTTP server:
```python
# BAD - Crashes at import time
_server_config: "Config" | None = None

# GOOD - Config already imported, no quotes needed
_server_config: Config | None = None
```

This smoke test would have caught it immediately:
```bash
$ uv run pytest tests/test_smoke.py::TestCLICommands::test_mcp_http_import -v
FAILED - subprocess.TimeoutExpired: Command '['uv', 'run', 'python', '-c', 
'import chunkhound.mcp_http_server']' failed with TypeError
```

## DESIGN_PRINCIPLES
1. **FAST**: Total runtime < 10 seconds
2. **FOCUSED**: Only test critical paths
3. **RELIABLE**: No flaky tests, no external dependencies
4. **ACTIONABLE**: Clear error messages pointing to the issue

## FUTURE_ADDITIONS
When adding new functionality:
1. Add module to `critical_modules` list if it's user-facing
2. Add CLI command to parametrized test if it has --help
3. Consider adding specific import test for complex modules

## INTEGRATION_WITH_AI_DEVELOPMENT
Since ChunkHound is 100% AI-developed:
- Smoke tests act as guardrails for AI agents
- Prevent syntax/type errors that AI might introduce
- Provide immediate feedback loop during development
- CRITICAL: AI agents should ALWAYS run smoke tests before marking tasks complete