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 mentions
-
application.yml / application.properties → server.port
-
package.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
- HTTP Testing with api-tester MCP