wait-on
Utility to wait for files, ports, sockets, or HTTP endpoints to become available. Used in npm scripts, CI pipelines, and test setup to wait for services to start before proceeding. Supports HTTP/HTTPS/TCP/UDP/file/socket targets with configurable timeout, interval, and retry settings. CLI: 'wait-on tcp:5432 http://localhost:3000/health && npm test'. Also available as a Node.js API.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Polling utility — minimal security surface. HTTPS target SSL verification configurable. No credentials involved.
⚡ Reliability
Best When
You need to synchronize service startup in CI pipelines, test scripts, or local development setups by waiting for ports/URLs to become available.
Avoid When
You need production-grade health checking or complex dependency graphs — use infrastructure-level health checks instead.
Use Cases
- • Wait for a PostgreSQL database to accept connections before running database migrations in CI/CD pipelines
- • Wait for a development server to start before launching E2E tests: 'wait-on http://localhost:3000 && cypress run'
- • Wait for a file to appear on disk before processing it in automation scripts
- • Block CI pipeline steps until dependent services are healthy (Redis, Kafka, third-party services)
- • Coordinate startup order of microservices in Docker Compose or local dev setups
Not For
- • Production health checking — use dedicated health check tools (Kubernetes probes, load balancer health checks) for production
- • Service mesh — use Envoy, Istio, or linkerd for production service dependency management
- • Complex dependency orchestration — use Docker Compose healthcheck or Kubernetes init containers for container orchestration
Interface
Authentication
No authentication — polling utility.
Pricing
Fully free, MIT licensed.
Agent Metadata
Known Gotchas
- ⚠ Default timeout is 60 seconds — for slow-starting services (large Docker images, database migrations), set explicit --timeout to prevent premature failure
- ⚠ HTTP polling returns 200-series for success — endpoints returning 404/503 during startup are considered not ready; ensure health endpoint returns 2xx when ready
- ⚠ TCP port open doesn't mean service is ready — a port may accept TCP connections before the service is fully initialized; use HTTP health endpoint URL instead of tcp: when possible
- ⚠ wait-on waits for ALL specified resources — if checking multiple targets, all must be ready; use separate wait-on calls if some resources are optional
- ⚠ Interval default is 250ms — for resources that take time to poll (HTTP), configure --interval to reduce load on services during startup polling
- ⚠ SSL certificate verification: wait-on verifies SSL certs by default for HTTPS targets — use --validateStatus or custom httpSignal options for self-signed cert environments
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for wait-on.
Scores are editorial opinions as of 2026-03-06.