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:
CLAUDE.md — explicit port mentionsapplication.yml / application.properties → server.portpackage.json scripts → --port flag.env / .env.local → PORT=- 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:
- Test files → Grep for
login, password, testUser in src/test/ or test/ - Config files →
application-test.yml, .env.test, test.env - Seed/fixture files →
data.sql, seed.ts, fixtures/ - 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
