How to Start the API and Wait for It Before Testing in CI

Tests that start before the server is listening flake, so block on a readiness URL before running them.

Launch the API in the background with &, then run npx wait-on <url> (or a curl retry loop) so the suite starts only once the server answers.

Steps

• Start the server in the background so the step does not block.
• Run npx wait-on http://localhost:PORT/health to gate on readiness.
• Only then run the test command.

Workflow

steps:
  - run: npm start &
  - run: npx wait-on --timeout 60000 http://localhost:3000/health
  - run: npm run test:api

Pure-shell alternative

for i in $(seq 1 30); do
  curl -sf http://localhost:3000/health && break
  echo "waiting for api ($i)"; sleep 2
done
curl -sf http://localhost:3000/health || { echo "api never came up"; exit 1; }

Gotchas

• Always set a timeout so a server that never boots fails the job instead of hanging.
• Poll a real readiness endpoint, not the TCP port, so you wait for the app and not just the socket.

Related guides