@neomaventures/wait-for

Wait for a TCP port or HTTP endpoint to accept traffic. Host-side readiness polling for tests, with no agent inside the target.

Installation

npm install --save-dev @neomaventures/wait-for

No dependencies, and no peer dependencies.

Why

docker compose up -d --wait blocks until every service is healthy, which is the right tool when your images declare a HEALTHCHECK. Two cases it does not cover:

1. The image has no healthcheck. --wait then only waits for the container to be running, which is not the same as ready — the classic case being a database whose process has started but whose socket is not yet accepting.
2. The image is too slim to probe itself. Compose healthchecks execute inside the container, so the image must carry curl, wget, nc or similar. Many slim and distroless images carry none, and adding one means maintaining a derived image purely to make it testable.

This runs on the host, so it needs nothing inside the target. Use the compose healthcheck where the image provides one, and this where it does not.

Usage

import { waitForHttp, waitForTcp } from "@neomaventures/wait-for"

// Block until a TCP port accepts a connection
await waitForTcp("localhost", 5432)

// Block until an endpoint answers 2xx
await waitForHttp("http://localhost:1080/mockserver/status", { method: "PUT" })

Typically in a Jest globalSetup, after your compose stack is up:

export default async function setup(): Promise<void> {
  await waitForTcp("localhost", 5432)
  await waitForHttp("http://localhost:1080/mockserver/status", {
    method: "PUT",
  })
}

Options

Both functions take the same options object.

| Option | Default | Meaning | | ------------ | ------- | --------------------------------------------- | | retries | 30 | Maximum attempts | | intervalMs | 1000 | Milliseconds between attempts | | timeoutMs | 30000 | Total time budget | | method | "GET" | HTTP method to probe with. waitForHttp only |

Polling stops at whichever limit is reached first — retries attempts or timeoutMs elapsed — and the returned promise rejects. A timeoutMs of 0 aborts before the first attempt.

waitForHttp treats any 2xx as ready and retries everything else, so a service answering 503 while it warms up is handled correctly.

API

waitForTcp(host, port, options?): Promise<void>

Resolves when a TCP connection succeeds. Rejects once the retry or timeout budget is exhausted.

waitForHttp(url, options?): Promise<void>

Resolves when the endpoint returns a 2xx status. Rejects once the retry or timeout budget is exhausted.

WaitOptions

The options interface shared by both.

License

MIT