| name | backend-server-verification |
| description | Canonical flow for starting and verifying a backend dev server. Use before running API tests: check port, start from correct directory, confirm readiness via short-timeout health request. Prevents 60–90+ second curl timeouts and port-conflict misdiagnosis. |
Backend Server Verification
Before running any API tests against a backend, verify the server is actually running and reachable.
Before Starting
- Check if target port is in use:
lsof -i :PORT (or equivalent).
- If in use: Kill the process or document using an alternate port. Do not assume "server stuck" or blame Redis/OpenAI—port conflict is a common cause of failures.
Start Command
- Always use an explicit directory so CWD is unambiguous across tool invocations.
- Example:
cd /absolute/path/to/backend && npm run dev (prefer absolute path).
After Start
- Wait briefly (e.g. a few seconds for the process to bind).
- Confirm readiness:
curl -f http://localhost:PORT/api/health --max-time 5.
- If curl fails: Read the terminal output for "port in use" or bind errors before retrying with long timeouts.
Two-Step Pattern (Recommended)
- Invocation 1: Start the server (background or in a separate terminal).
- Invocation 2: Run curl with
--max-time 5 to verify; do not run long curls until health succeeds.
Integration
- Use with
dev-server-lifecycle-management and port-conflict-resolution for port detection and conflict handling.
- Use with
pre-flight-checklist / pre-implementation-check for backend tasks.
