claude-dev-suite Smoke Testing Core Knowledge
Deep Knowledge: Use
mcp__documentation__fetch_docswith technology:smoke-testingfor comprehensive documentation.
When NOT to Use This Skill
- Unit Testing — Use
vitest,jest,junit, orpytestfor isolated unit tests - E2E Browser Testing — Use
playwrightorcypressfor browser-driven end-to-end tests - Static API Contract Validation — Use
integration-validator-expertfor OpenAPI schema validation without running services - Load/Performance Testing — Use
performance-expertfor 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.jsonscripts →--portflag.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,testUserinsrc/test/ortest/ - 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
- HTTP Testing with api-tester MCP