Smoke Testing Core Knowledge

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: smoke-testing for comprehensive documentation.

When NOT to Use This Skill

• Unit Testing — Use vitest, jest, junit, or pytest for isolated unit tests
• E2E Browser Testing — Use playwright or cypress for browser-driven end-to-end tests
• Static API Contract Validation — Use integration-validator-expert for OpenAPI schema validation without running services
• Load/Performance Testing — Use performance-expert for benchmarks and profiling

Stack Detection Table

| Marker File | Stack | Build Command | Test Command | Run Command | Default Port | |-------------|-------|---------------|--------------|-------------|--------------| | pom.xml | Spring Boot | ./mvnw clean compile -q | ./mvnw test -q | ./mvnw spring-boot:run & | 8080 | | build.gradle | Spring Boot (Gradle) | ./gradlew build -x test | ./gradlew test | ./gradlew bootRun & | 8080 | | package.json + @nestjs/core | NestJS | npm run build | npm test | npm run start:dev & | 3000 | | package.json + express | Express | npm run build | npm test | npm start & | 3000 | | requirements.txt + fastapi | FastAPI | — | pytest | uvicorn main:app --reload & | 8000 | | go.mod | Go | go build ./... | go test ./... | go run . & | 8080 | | Cargo.toml | Rust | cargo build | cargo test | cargo run & | 8080 | | *.csproj | .NET | dotnet build | dotnet test | dotnet run & | 5000 |

Health Check Endpoints

| Stack | Endpoint | Dependency | |-------|----------|------------| | Spring Boot | /actuator/health | spring-boot-starter-actuator | | NestJS | /health | @nestjs/terminus (or custom) | | FastAPI | /health or /docs | Custom route | | Express | /health or /api/health | Custom route | | Go | /health or /healthz | Custom handler | | .NET | /health | Microsoft.Extensions.Diagnostics.HealthChecks |

Port Detection Strategy

Search in order:

1. CLAUDE.md — explicit port mentions
2. application.yml / application.properties → server.port
3. package.json scripts → --port flag
4. .env / .env.local → PORT=
5. Fall back to stack default from table above

Authentication Patterns

JWT Login Flow

POST /api/auth/login
Content-Type: application/json

{"email": "{email}", "password": "{password}"}

→ Response: {"token": "eyJ...", "refreshToken": "..."}
→ Use: Authorization: Bearer {token}

Credential Discovery

Search in order:

1. Test files → Grep for login, password, testUser in src/test/ or test/
2. Config files → application-test.yml, .env.test, test.env
3. Seed/fixture files → data.sql, seed.ts, fixtures/
4. Known defaults → admin/admin, test@test.com/password

Detecting Auth Requirement

No auth needed if:

• No security dependencies in pom.xml / package.json
• Health endpoint returns 200 without token
• No @PreAuthorize, @UseGuards, Depends(get_current_user) in controllers

Log File Locations

| Stack | Typical Paths | Config Key | |-------|---------------|------------| | Spring Boot | logs/, target/ | logging.file.path in application*.yml | | NestJS | logs/ | LoggerModule config or winston transport | | FastAPI | logs/ | logging.config in Python files | | Docker | Container stdout | Access via docker logs or docker-manager MCP |

Fallback chain: /tmp/smoke-test-app.log (stdout redirect) → Glob **/logs/*.log → Docker container logs

HTTP Verification Patterns

Positive Cases

| Method | Expected Status | Body Check | |--------|----------------|------------| | GET (list) | 200 | Array response, non-empty | | GET (by ID) | 200 | Object with matching ID | | POST (create) | 201 | Created object with generated ID | | PUT (update) | 200 | Updated fields reflected | | DELETE | 204 or 200 | Subsequent GET returns 404 |

Negative Cases

| Test | Expected Status | Meaning | |------|----------------|---------| | No auth token | 401 | Unauthorized | | Invalid ID (e.g. 999999) | 404 | Not Found | | Invalid body (missing required field) | 400 | Bad Request | | Wrong HTTP method | 405 | Method Not Allowed |

Anti-Patterns

| Anti-Pattern | Why It's Bad | Solution | |--------------|-------------|---------| | Testing against production DB | Data corruption risk | Use test profile or Docker container | | Hardcoding test credentials | Security risk, breaks across envs | Read from env/test config files | | Skipping cleanup | Leftover processes and test data | Always kill PID, prefix data with smoke-test-* | | Testing all endpoints | Scope creep, slow | Focus on recently implemented endpoints | | Ignoring log errors | Hidden bugs slip through | Always check logs in Phase 7 | | Retrying without fixing | Wastes iterations | Delegate fix before retrying |

Quick Troubleshooting

| Problem | Likely Cause | Solution | |---------|-------------|---------| | Health check timeout | App not started or wrong port | Check log file, verify port in config | | 401 on all endpoints | JWT expired or wrong header format | Re-authenticate, check Authorization: Bearer format | | Connection refused | Service not listening yet | Increase health check retry interval | | 500 on POST | Missing required fields or DB constraint | Check DTO validation and entity defaults | | Port already in use | Previous smoke test didn't cleanup | kill $(lsof -ti:PORT) then retry | | Build fails on Windows | Maven wrapper not executable | Use mvnw.cmd instead of ./mvnw |

Reference Documentation

• HTTP Testing with api-tester MCP