@owlmeans/test-integration 0.1.18-rc.3 → 0.1.18-rc.30

package/README.md

@@ -4,7 +4,8 @@ Env-gated harness for integration tests of packages that talk to external servic
 
 Helpers exported here:
 
-- `mongoGate()`, `redisGate()`, `s3Gate()`, `kubeGate()` — read the env keys documented in `.env.example` and return `{ skip, reason?, env }`. A `tests/context.ts` uses these to decide whether to register the corresponding service in the real test context.
+- `mongoGate()`, `redisGate()`, `postgresGate()`, `s3Gate()`, `kubeGate()`, `smtpGate()` — read the env keys documented in `.env.example` and return `{ skip, reason?, env }`. A `tests/context.ts` uses these to decide whether to register the corresponding service in the real test context.
+- The three datastore gates (`mongoGate`, `redisGate`, `postgresGate`) also require a host in the connection string to accept a TCP connect. A set variable pointing at nothing — a port-forward that is not running — closes the gate with a printed reason naming the variable and `host:port`, instead of failing the suite on a refused connection. The probe is synchronous, so gates keep being read at module scope.
 - `randomNamespace(prefix)` — short random suffix to keep DB names, key prefixes, and S3 prefixes unique per test run so suites can safely run in parallel.
 - `registerCleanup(fn)` + `runCleanups()` — opt-in `afterAll` cleanup queue.
 
@@ -18,7 +19,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.42
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/test-integration",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.504Z",
+  "version": "0.1.18-rc.30",
+  "generatedAt": "2026-09-29T08:01:58.123Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/testing-integration/SKILL.md

@@ -1,41 +1,108 @@
 ---
 name: testing-integration
-description: Category-C integration tests for OwlMeans Common packages that talk to external services (PostgreSQL, MongoDB, Redis, S3, Kubernetes). Env-gated, no mocks, per-suite namespaces, conditional context provisioning. Auto-invoked when writing tests in postgres*, mongo*, redis*, kluster, storage*, image-resource, server-api, server-app, queue.
+description: Category-C integration tests for OwlMeans Common packages that talk to external services (PostgreSQL, MongoDB, Redis, S3, Kubernetes, SMTP). Env-gated, no mocks, per-suite namespaces, conditional context provisioning. Auto-invoked when writing tests in postgres*, mongo*, redis*, kluster, llm, storage-resource, mailer-smtp, server-mailer-mailgun, server-api, server-app.
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
 # Integration Tests — Category C
 
+**Install:** `"@owlmeans/test-integration": "^0.1.18-rc.30"` in `devDependencies`
+
 Category C applies to packages that integrate with external services: `postgres`,
-`postgres-resource`, `mongo`, `mongo-resource`, `redis`, `redis-resource`, `kluster`,
-`storage-common`, `storage-resource`, `image-resource`, `server-api`, `server-app`, `queue`,
-`llm` (live inference providers). These tests **never** mock the external service. They run
-only when the corresponding env vars are set, and they self-skip cleanly when those variables
-are missing.
+`postgres-resource`, `mongo`, `mongo-resource`, `redis`, `redis-resource`, `redis-queue`,
+`kluster`, `storage-resource`, `mailer-smtp`, `server-mailer-mailgun`, `server-api`, `planning-postgres`,
+`server-app`, `llm` (live inference providers). These tests **never** mock the external service.
+They run only when the corresponding env vars are set, and they self-skip cleanly when those
+variables are missing.
+
+`queue`, `resource`, `mailer`, `storage-common` and `image-resource` stay in category A: types,
+AJV schemas and error translation only, so their specs need nothing running and there is no gate
+they could open. What decides the category is what a package's own code does at runtime, not what
+its manifest lists — a `*-resource` package that issues real commands through a client the db
+service hands it is category C even when it names no driver of its own.
 
 ## Helpers from `@owlmeans/test-integration`
 
 | Helper | Purpose |
 |---|---|
-| `postgresGate()`, `mongoGate()`, `redisGate()`, `s3Gate()`, `kubeGate()` | Read env, return `{ skip, reason?, env }`. |
-| `randomNamespace(prefix, len?)` | Schema / DB / key / object-prefix namespacing for parallel-safe runs. |
-| `registerCleanup(fn)` + `runCleanups()` | Process-global LIFO queue. **Single-spec-file packages only** — see below. |
+| `postgresGate()`, `mongoGate()`, `redisGate()`, `s3Gate()`, `kubeGate()`, `smtpGate()` | Read env (and, for the three datastores, probe the address — below), return `IntegrationGate<E>` = `{ skip, reason?, env }`. |
+| `IntegrationGate<E>` | `{ skip: boolean, reason?: string, env: Partial<E> }`. `env` holds only the variables that were actually populated. `skip` is a plain `boolean`, not a discriminant, so `env` stays `Partial<E>` on the open branch too — a suite reads a required variable through a cast: `gate.env.MONGO_URL as string`. |
+| `PostgresEnv`, `MongoEnv`, `RedisEnv`, `S3Env`, `KubeEnv`, `SmtpEnv` | The variable set each gate reads, so `tests/context.ts` types its exported gate. |
+| `randomNamespace(prefix, len?)` | Schema / DB / key / object-prefix namespacing for parallel-safe runs. Default 6 hex chars. |
+| `registerCleanup(fn)` + `runCleanups()` | Process-global LIFO queue. Only where **one** spec file of the package provisions anything — see below. |
+
+Each gate fails closed on its **required** variables and treats the rest as optional:
+
+| Gate | Required | Optional |
+|---|---|---|
+| `mongoGate()` | `MONGO_URL` | `MONGO_TEST_DB_PREFIX` |
+| `postgresGate()` | `POSTGRES_URL` | `POSTGRES_TEST_DB_PREFIX` |
+| `redisGate()` | `REDIS_URL` | `REDIS_TEST_KEY_PREFIX` |
+| `s3Gate()` | `S3_ENDPOINT`, `S3_KEY`, `S3_SECRET`, `S3_TEST_BUCKET` | `S3_REGION` |
+| `kubeGate()` | `KUBE_CONFIG`, `KUBE_TEST_OK` | — |
+| `smtpGate()` | `SMTP_HOST`, `SMTP_USER`, `SMTP_PASSWORD`, `SMTP_FROM`, `SMTP_TEST_TO` | `SMTP_PORT`, `SMTP_SECURE` |
+
+`SMTP_TEST_TO` is required rather than optional because an open SMTP gate sends **real mail** — the
+suite must never guess a recipient.
+
+### A datastore gate also asks whether the server answers
+
+`mongoGate()`, `redisGate()` and `postgresGate()` open only when their connection string is set
+**and** one of the hosts in it accepts a TCP connect (default ports 27017 / 6379 / 5432). A local
+`.env` keeps the port-forward address long after the forward is gone, and a gate that trusted the
+variable alone left `beforeAll` to spend its whole budget on `ECONNREFUSED` and fail the suite. An
+unreachable address therefore closes the gate like an empty variable does, and says so loudly — one
+`console.warn` per address, naming the variable and `host:port` (never the URL, which carries the
+credential), and the same text as `gate.reason`:
+
+```text
+@owlmeans/test-integration: skipping — MONGO_URL is set, but nothing answers at 127.0.0.1:27017 (ECONNREFUSED) — start the service (or its port-forward) to run these specs
+```
 
-The driver libraries (`pg`, `mongodb`, `ioredis`, `@aws-sdk/client-s3`,
-`@kubernetes/client-node`) stay where they already live — in the consuming integration
-packages — and are imported directly in those packages' `tests/`.
+The probe is synchronous (a child process running a bounded connect, 1.5 s per address), because
+Bun decides `test` vs `test.skip` synchronously and every consumer reads its gate at module scope —
+so no `tests/context.ts` changes to get it. It is TCP only: no driver and no login, so a wrong
+password still opens the gate and fails in the suite, where it belongs. It answers "reachable" when
+it cannot tell — an SRV (`mongodb+srv://`) or unix-socket address, a string it cannot parse, a probe
+that cannot spawn — which is exactly the behaviour a gate had before it probed. `s3Gate()`,
+`kubeGate()` and `smtpGate()` do not probe: they name remote services, not a local forward.
+
+An optional variable is only in `env` when it was actually populated, which is why a suite reads a
+defaulted one — `POSTGRES_TEST_DB_PREFIX ?? 'omt'` — straight from `process.env` instead: calling
+any gate has already run `loadEnv`, so the `.env` values are in `process.env` by then.
+
+**Six services, six gates — a category-C package outside that set writes its own.** There is no
+gate for an LLM provider or for the Mailgun HTTP API, and none should be added to
+`@owlmeans/test-integration` for a provider only one package talks to. Declare it in that
+package's `tests/context.ts` with `makeGates` from `@owlmeans/test` instead, listing the variables
+the provider needs; the result skips exactly the same way. `@owlmeans/llm` is the worked example.
+
+Every driver stays where it already lives — in the package that integrates with the service, not
+in a test package: `pg` (`@owlmeans/postgres`), `mongodb` (`@owlmeans/mongo`), `ioredis`
+(`@owlmeans/redis`), `bullmq` (`@owlmeans/redis-queue`), `@aws-sdk/client-s3`
+(`@owlmeans/storage-resource`), `@kubernetes/client-node` (`@owlmeans/kluster`) and `nodemailer`
+(`@owlmeans/mailer-smtp`). A suite that must reach the service outside the package's own
+service — to seed a fixture, or to assert on what really landed — imports that driver directly in
+its `tests/`. `@owlmeans/server-mailer-mailgun` has no driver: it posts to the Mailgun HTTP API
+with the global `fetch`, so a suite there imports nothing beyond the package under test and
+asserts on the request it builds and the API's reply.
 
 ## Env contract
 
-`/.env.example` documents every required variable, grouped by service, with comments. The
-single `.env` at the monorepo root supplies real values for local runs. CI sets them via
-secrets. **Empty value = skip** — never a failure.
+One `.env.example` at the workspace root documents every variable, grouped by service, with
+comments; the `.env` beside it supplies real values for local runs and `loadEnv` (from
+`@owlmeans/test`) picks it up. CI sets the same variables from secrets. **Empty value = skip, and
+so is a datastore address nothing answers at** — never a failure. A developer's `.env` may keep the
+port-forward address permanently: with the forward up the suites run, without it they skip.
 
-When a required variable is empty:
+When a required variable is empty, or a datastore gate's server does not answer:
 1. The corresponding gate reports `skip: true`.
 2. The per-package `tests/context.ts` does **not** register the dependent service in the real context.
 3. Specs that touch that service self-skip with the reason printed.
 
+A CI job that provisions the service beside its secrets must therefore check the service is up
+before the tests, or read the run's skip count: an outage there skips rather than fails.
+
 **Never print a credential.** Pipe it straight from its source into the env var the gate
 reads — the value must never reach a log, a report, or a committed file:
 
@@ -45,26 +112,26 @@ POSTGRES_URL="$(<build it from the secret file, without echoing>)" bun test ./te
 
 ### Where the real credentials come from
 
-The dev-cluster secrets are the source of truth; `../viable/.env.dev.secrets` holds the same
-values under kebab-case keys (`mongo-secret`, `redis-secret`, `s3-storage`, …) for
-`kubectl create secret --from-env-file`. Read the cluster secret directly rather than transcribing:
+Read each secret from wherever it actually lives — a cluster secret, a vault, the provider's own
+console — and pipe it into the variable in one step. Never transcribe a credential into a file,
+a fixture or this guidance.
 
 ```bash
-kubectl get secret mongo-owlmeans-mongo-main-db-admin-admin -o jsonpath='{.data.password}' | base64 -d
+kubectl get secret <name> -o jsonpath='{.data.password}' | base64 -d
 ```
 
 Two things that will bite:
 
-- **URL-escape the password before putting it in a connection string.** These generated passwords
+- **URL-escape the password before putting it in a connection string.** Generated passwords
   contain reserved characters; an unescaped one fails with `MongoParseError: Password contains
   unescaped characters`. Escape with `urllib.parse.quote(pw, safe='')`.
-- **The port-forward may already be running** — the slots share one cluster, so
-  `bind: address already in use` on 27017/5432/6379 usually means another checkout forwards the
-  same service. Reuse it; never kill another environment's process.
+- **A port-forward may already be running.** `bind: address already in use` on 27017/5432/6379
+  usually means another checkout or another developer already forwards that service. Reuse the
+  forward; never kill a process you did not start.
 
 The suites namespace every database/schema (`MONGO_TEST_DB_PREFIX`, default `omt`) and drop it on
-completion, so they are safe against the shared cluster. Confirm nothing was left behind after a
-run that aborted mid-way.
+completion, so they are safe against an instance shared with anything else. Confirm nothing was
+left behind after a run that aborted mid-way.
 
 ## Where the specs live
 
@@ -73,19 +140,31 @@ A resource package (`*-resource`) owns the `Resource<T>` contract; the db packag
 **depends on** the resource package.
 
 - **Unit specs** — schema compilation, identifier derivation, placeholder resolution, error
-  translation — live in the **resource** package. No gate, no service.
-- **Integration specs** that build a real `ServerContext` live in the **db** package. Putting
-  them in the resource package would need a devDependency on its own dependent, which is a
-  cycle and risks breaking `publish.ts`'s topological batching.
+  translation — live in the **resource** package and gate on nothing: they leave the process
+  alone. `@owlmeans/postgres-resource` is entirely this shape.
+- **Raw-driver specs** belong there too when the subject is the round trip and not the service.
+  `@owlmeans/mongo-resource` opens `mongoGate()`, derives a namespaced database with
+  `randomNamespace`, registers a cleanup that drops it, and drives `mongodb` directly with the
+  driver as its own devDependency — legitimate precisely because it never constructs the db
+  service. It is also the one package that may use the global cleanup queue, because only that
+  one spec file of the three provisions anything.
+- **Integration specs that build a real `ServerContext`** live in the **db** package. It already
+  depends on the resource package, so the pair it boots is the real one; putting them in the
+  resource package would make a contract dev-depend on its own implementation just to run its
+  specs.
 
 ## Per-suite namespaces, not the global cleanup queue
 
-Bun runs **every spec file of a package in one process** with one shared module registry. A
-process-global `registerCleanup`/`runCleanups()` therefore misfires: the first file to reach
-`afterAll` drops the namespaces of the files still to come. Use `registerCleanup` only in a
-package with a single spec file.
+Bun runs **every spec file of a package in one process** with one shared module registry, and the
+queue is one array for that whole process. A process-global `registerCleanup`/`runCleanups()`
+therefore misfires as soon as two spec files provision: the first to reach `afterAll` drains the
+entire queue and drops the namespaces of the files still to come. The queue is safe only where a
+**single** spec file provisions anything and that same file calls `runCleanups()`. That is the
+shape `@owlmeans/mongo-resource` has — one gated round-trip spec registering one dropped database,
+beside two ungated spec files that translate criteria and references in memory and open nothing.
 
-Give each spec file its own namespace and its own teardown instead:
+Any package with a second provisioning spec file gives each spec file its own namespace and its
+own teardown instead:
 
 ```ts
 // tests/context.ts
@@ -142,10 +221,12 @@ export const capabilities: PgCapabilities = gate.skip
 
 Specs then branch on it once, at the top: `const it = gate.skip || !capabilities.bootstrap ? test.skip : test`.
 
-## Module-scope declarations survive a context switch
+## Module-scope declarations outlive a `boot()`
 
-Migration registries and table declarations are keyed by resource **alias** at module scope so
-they outlive `reinitializeContext`. That means they also outlive a `boot()` — deliberately.
+Migration registries and table declarations are keyed by resource **alias** at module scope, so a
+maker that runs more than once for the same alias re-declares the same entries and loses nothing.
+A `boot()` builds a whole new context, but the declarations belong to the module registry rather
+than to any context, so they carry across every boot in the process — deliberately.
 Never reset them inside a shared `boot()` helper: a `.migration()` registered before the boot
 would be silently dropped. A spec that wants a clean slate calls `resetDeclarations(alias)`
 itself, which is what a spec simulating a restarted process should have to say out loud.
@@ -192,13 +273,25 @@ Add `"./tests/**/*"` to the package's `tsconfig.json` `exclude` so `tsc -b` neve
 specs into `build/`, and declare `@owlmeans/test-integration` plus `@types/bun` as
 devDependencies.
 
-The Bun runtime auto-loads `<root>/.env` when the test command runs from a workspace package.
-If you need to override, `bun test --env-file=../../.env` works. Long-running specs may need a
-higher timeout — set it locally in a per-package `bunfig.toml`:
+**Nothing auto-loads the workspace `.env`.** Bun reads a `.env` beside the working directory, so
+`bun test` inside a package never sees the one at the workspace root. The gates work because
+`@owlmeans/test`'s `loadEnv` does the loading itself and every gate calls it before reading a
+variable: it walks up from the working directory for a `bun.lock`, or for a `package.json`
+sitting beside a directory named `packages`, and reads the `.env` it finds there. A variable
+already set to a non-empty value always wins, so `MONGO_URL=… bun test ./tests` still overrides
+the file. A workspace shaped any other way names the file itself — `loadEnv({ file })` at the top
+of `tests/context.ts`, before the gates run.
+
+Bun's per-test timeout is 5s, and **`bunfig.toml`'s `[test] timeout` does not raise it** — bun
+1.4.0 reads the section (`preload` in it works) and ignores that key. Give a long-running spec its
+own budget as the third argument to `test`, or raise the whole run on the command line:
+
+```ts
+test('round-trips through a real service', async () => { /* … */ }, 60_000)
+```
 
-```toml
-[test]
-timeout = 60000
+```sh
+bun test --timeout=60000 ./tests
 ```
 
 ## Bun assertion gotcha
@@ -221,7 +314,8 @@ expect(pgErrorToResourceError(circular)).toBe(circular)   // not: expect(() =>
   service holds no leftovers matching the prefix.
 - **Cover SKILL.md cases first.**
 - **Max 3-4 tests per method/function.**
-- **CI runs C only when secrets are set.** Locally, an empty `.env` produces a clean skip.
+- **CI runs C only when secrets are set.** Locally, an empty `.env` — or a set one whose forward is
+  down — produces a clean, printed skip.
 
 ## When the env is partially populated
 

package/build/gates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CAChB;AAoBD,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,oBAAoB,EAAE,MAAM,CAAA;CAC7B;AAED,eAAO,MAAM,SAAS,QAAO,eAAe,CAAC,QAAQ,CACiB,CAAA;AAEtE,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,qBAAqB,EAAE,MAAM,CAAA;CAC9B;AAED,eAAO,MAAM,SAAS,QAAO,eAAe,CAAC,QAAQ,CACkB,CAAA;AAEvE,MAAM,WAAW,KAAK;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,eAAO,MAAM,MAAM,QAAO,eAAe,CAAC,KAAK,CAI5C,CAAA;AAEH,MAAM,WAAW,OAAO;IACtB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,eAAO,MAAM,QAAQ,QAAO,eAAe,CAAC,OAAO,CACU,CAAA;AAE7D,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAA;IACpB,uBAAuB,EAAE,MAAM,CAAA;CAChC;AAED,eAAO,MAAM,YAAY,QAAO,eAAe,CAAC,WAAW,CACoB,CAAA;AAE/E,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,eAAO,MAAM,QAAQ,QAAO,eAAe,CAAC,OAAO,CAIhD,CAAA"}
+{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CAChB;AAqCD,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,oBAAoB,EAAE,MAAM,CAAA;CAC7B;AAED,eAAO,MAAM,SAAS,QAAO,eAAe,CAAC,QAAQ,CAC2D,CAAA;AAEhH,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,qBAAqB,EAAE,MAAM,CAAA;CAC9B;AAED,eAAO,MAAM,SAAS,QAAO,eAAe,CAAC,QAAQ,CAC2D,CAAA;AAEhH,MAAM,WAAW,KAAK;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,eAAO,MAAM,MAAM,QAAO,eAAe,CAAC,KAAK,CAI5C,CAAA;AAEH,MAAM,WAAW,OAAO;IACtB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,eAAO,MAAM,QAAQ,QAAO,eAAe,CAAC,OAAO,CACU,CAAA;AAE7D,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAA;IACpB,uBAAuB,EAAE,MAAM,CAAA;CAChC;AAED,eAAO,MAAM,YAAY,QAAO,eAAe,CAAC,WAAW,CACgE,CAAA;AAE3H,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,eAAO,MAAM,QAAQ,QAAO,eAAe,CAAC,OAAO,CAIhD,CAAA"}

package/build/gates.js

@@ -1,4 +1,5 @@
 import { hasEnv, requireEnv } from '@owlmeans/test';
+import { unreachableReason } from './reachability.js';
 const collect = (keys) => {
     const env = {};
     for (const k of keys) {
@@ -7,17 +8,22 @@ const collect = (keys) => {
     }
     return env;
 };
-const toIntegrationGate = (required, optional = []) => {
+const toIntegrationGate = (required, optional = [], reachable) => {
     const gate = requireEnv(required);
     const env = collect([...required, ...optional]);
-    if ('ok' in gate)
-        return { skip: false, env };
-    return { skip: true, reason: gate.reason, env };
+    if (!('ok' in gate))
+        return { skip: true, reason: gate.reason, env };
+    if (reachable != null) {
+        const reason = unreachableReason(reachable.key, process.env[reachable.key], reachable.defaultPort);
+        if (reason != null)
+            return { skip: true, reason, env };
+    }
+    return { skip: false, env };
 };
-export const mongoGate = () => toIntegrationGate(['MONGO_URL'], ['MONGO_TEST_DB_PREFIX']);
-export const redisGate = () => toIntegrationGate(['REDIS_URL'], ['REDIS_TEST_KEY_PREFIX']);
+export const mongoGate = () => toIntegrationGate(['MONGO_URL'], ['MONGO_TEST_DB_PREFIX'], { key: 'MONGO_URL', defaultPort: 27017 });
+export const redisGate = () => toIntegrationGate(['REDIS_URL'], ['REDIS_TEST_KEY_PREFIX'], { key: 'REDIS_URL', defaultPort: 6379 });
 export const s3Gate = () => toIntegrationGate(['S3_ENDPOINT', 'S3_KEY', 'S3_SECRET', 'S3_TEST_BUCKET'], ['S3_REGION']);
 export const kubeGate = () => toIntegrationGate(['KUBE_CONFIG', 'KUBE_TEST_OK']);
-export const postgresGate = () => toIntegrationGate(['POSTGRES_URL'], ['POSTGRES_TEST_DB_PREFIX']);
+export const postgresGate = () => toIntegrationGate(['POSTGRES_URL'], ['POSTGRES_TEST_DB_PREFIX'], { key: 'POSTGRES_URL', defaultPort: 5432 });
 export const smtpGate = () => toIntegrationGate(['SMTP_HOST', 'SMTP_USER', 'SMTP_PASSWORD', 'SMTP_FROM', 'SMTP_TEST_TO'], ['SMTP_PORT', 'SMTP_SECURE']);
 //# sourceMappingURL=gates.js.map

package/build/gates.js.map

@@ -1 +1 @@
-{"version":3,"file":"gates.js","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAQnD,MAAM,OAAO,GAAG,CAAI,IAA0B,EAAc,EAAE;IAC5D,MAAM,GAAG,GAA2B,EAAE,CAAA;IACtC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,MAAM,CAAC,CAAC,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAW,CAAA;IAClD,CAAC;IACD,OAAO,GAAiB,CAAA;AAC1B,CAAC,CAAA;AAED,MAAM,iBAAiB,GAAG,CACxB,QAA8B,EAC9B,QAAQ,GAAyB,EAAE,EACf,EAAE;IACtB,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAA;IACjC,MAAM,GAAG,GAAG,OAAO,CAAI,CAAC,GAAG,QAAQ,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAA;IAClD,IAAI,IAAI,IAAI,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;IAC7C,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAA;AACjD,CAAC,CAAA;AAOD,MAAM,CAAC,MAAM,SAAS,GAAG,GAA8B,EAAE,CACvD,iBAAiB,CAAW,CAAC,WAAW,CAAC,EAAE,CAAC,sBAAsB,CAAC,CAAC,CAAA;AAOtE,MAAM,CAAC,MAAM,SAAS,GAAG,GAA8B,EAAE,CACvD,iBAAiB,CAAW,CAAC,WAAW,CAAC,EAAE,CAAC,uBAAuB,CAAC,CAAC,CAAA;AAUvE,MAAM,CAAC,MAAM,MAAM,GAAG,GAA2B,EAAE,CACjD,iBAAiB,CACf,CAAC,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,CAAC,EACxD,CAAC,WAAW,CAAC,CACd,CAAA;AAOH,MAAM,CAAC,MAAM,QAAQ,GAAG,GAA6B,EAAE,CACrD,iBAAiB,CAAU,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,CAAA;AAO7D,MAAM,CAAC,MAAM,YAAY,GAAG,GAAiC,EAAE,CAC7D,iBAAiB,CAAc,CAAC,cAAc,CAAC,EAAE,CAAC,yBAAyB,CAAC,CAAC,CAAA;AAa/E,MAAM,CAAC,MAAM,QAAQ,GAAG,GAA6B,EAAE,CACrD,iBAAiB,CACf,CAAC,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,cAAc,CAAC,EACxE,CAAC,WAAW,EAAE,aAAa,CAAC,CAC7B,CAAA"}
+{"version":3,"file":"gates.js","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAQrD,MAAM,OAAO,GAAG,CAAI,IAA0B,EAAc,EAAE;IAC5D,MAAM,GAAG,GAA2B,EAAE,CAAA;IACtC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,MAAM,CAAC,CAAC,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAW,CAAA;IAClD,CAAC;IACD,OAAO,GAAiB,CAAA;AAC1B,CAAC,CAAA;AAcD,MAAM,iBAAiB,GAAG,CACxB,QAA8B,EAC9B,QAAQ,GAAyB,EAAE,EACnC,SAAwB,EACJ,EAAE;IACtB,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAA;IACjC,MAAM,GAAG,GAAG,OAAO,CAAI,CAAC,GAAG,QAAQ,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAA;IAClD,IAAI,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAA;IACpE,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAW,EAAE,SAAS,CAAC,WAAW,CAAC,CAAA;QAC5G,IAAI,MAAM,IAAI,IAAI;YAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAA;IACxD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;AAC7B,CAAC,CAAA;AAOD,MAAM,CAAC,MAAM,SAAS,GAAG,GAA8B,EAAE,CACvD,iBAAiB,CAAW,CAAC,WAAW,CAAC,EAAE,CAAC,sBAAsB,CAAC,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAA;AAOhH,MAAM,CAAC,MAAM,SAAS,GAAG,GAA8B,EAAE,CACvD,iBAAiB,CAAW,CAAC,WAAW,CAAC,EAAE,CAAC,uBAAuB,CAAC,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAA;AAUhH,MAAM,CAAC,MAAM,MAAM,GAAG,GAA2B,EAAE,CACjD,iBAAiB,CACf,CAAC,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,CAAC,EACxD,CAAC,WAAW,CAAC,CACd,CAAA;AAOH,MAAM,CAAC,MAAM,QAAQ,GAAG,GAA6B,EAAE,CACrD,iBAAiB,CAAU,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,CAAA;AAO7D,MAAM,CAAC,MAAM,YAAY,GAAG,GAAiC,EAAE,CAC7D,iBAAiB,CAAc,CAAC,cAAc,CAAC,EAAE,CAAC,yBAAyB,CAAC,EAAE,EAAE,GAAG,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAA;AAa3H,MAAM,CAAC,MAAM,QAAQ,GAAG,GAA6B,EAAE,CACrD,iBAAiB,CACf,CAAC,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,cAAc,CAAC,EACxE,CAAC,WAAW,EAAE,aAAa,CAAC,CAC7B,CAAA"}

package/build/reachability.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Whether the server a connection string names answers at all — asked synchronously, because
+ * Bun decides `test` vs `test.skip` synchronously and every gate is read at module scope.
+ *
+ * A populated variable says where the service should be, not that it is there: a developer's
+ * `.env` keeps the port-forward address long after the forward is gone, and a suite that trusts
+ * it spends its whole `beforeAll` budget on a refused connection and FAILS. Only a TCP connect is
+ * asked — never a login — so no driver is needed here and no credential leaves the variable.
+ */
+export interface ProbeTarget {
+    host: string;
+    port: number;
+}
+/**
+ * Every `host:port` in the authority of a connection string, or `null` when the string names
+ * nothing a TCP connect can check — an SRV record, a unix socket, or a shape this cannot read.
+ * `null` leaves the gate exactly as the variable alone would have it.
+ */
+export declare const parseTargets: (url: string, defaultPort: number) => ProbeTarget[] | null;
+/**
+ * `null` when at least one target accepts a TCP connection, otherwise the reason none did.
+ *
+ * A probe that cannot run at all also answers `null`: not knowing is not evidence the service is
+ * down, and the suite then behaves exactly as it did before probes existed.
+ */
+export declare const probeTargets: (targets: ProbeTarget[]) => string | null;
+/**
+ * The skip reason for a populated connection-string variable whose server does not answer, or
+ * `null` when it answers or cannot be probed. Printed once per variable and address, so a closed
+ * gate is never mistaken for a suite that has nothing to run.
+ */
+export declare const unreachableReason: (variable: string, url: string, defaultPort: number) => string | null;
+//# sourceMappingURL=reachability.d.ts.map

package/build/reachability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reachability.d.ts","sourceRoot":"","sources":["../src/reachability.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb;AAWD;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAS,MAAM,eAAe,MAAM,KAAG,WAAW,EAAE,GAAG,IA6B/E,CAAA;AA0BD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,YAAa,WAAW,EAAE,KAAG,MAAM,GAAG,IAkB9D,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAAc,MAAM,OAAO,MAAM,eAAe,MAAM,KAAG,MAAM,GAAG,IAiB/F,CAAA"}

package/build/reachability.js

@@ -0,0 +1,109 @@
+import { spawnSync } from 'node:child_process';
+/** How long one connect may take before the address counts as unreachable. */
+const CONNECT_TIMEOUT_MS = 1_500;
+/** The probe runs in a child process; this covers its own startup on a loaded machine. */
+const SPAWN_GRACE_MS = 5_000;
+const answers = new Map();
+const warned = new Set();
+/**
+ * Every `host:port` in the authority of a connection string, or `null` when the string names
+ * nothing a TCP connect can check — an SRV record, a unix socket, or a shape this cannot read.
+ * `null` leaves the gate exactly as the variable alone would have it.
+ */
+export const parseTargets = (url, defaultPort) => {
+    const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(url);
+    if (scheme == null || scheme[1].toLowerCase().endsWith('+srv')) {
+        return null;
+    }
+    const rest = url.slice(scheme[0].length);
+    const end = rest.search(/[/?#]/);
+    const authority = end < 0 ? rest : rest.slice(0, end);
+    const hosts = authority.slice(authority.lastIndexOf('@') + 1);
+    const targets = [];
+    for (const entry of hosts.split(',')) {
+        const match = /^(\[[^\]]+\]|[^:]*)(?::(\d+))?$/.exec(entry);
+        if (match == null) {
+            return null;
+        }
+        let host;
+        try {
+            host = decodeURIComponent(match[1]).replace(/^\[|\]$/g, '');
+        }
+        catch {
+            return null;
+        }
+        if (host === '' || host.includes('/')) {
+            return null;
+        }
+        targets.push({ host, port: match[2] != null ? parseInt(match[2], 10) : defaultPort });
+    }
+    return targets.length > 0 ? targets : null;
+};
+// Runs under whichever runtime runs the suite (`process.execPath`), so it is plain CommonJS
+// that both `bun -e` and `node -e` evaluate.
+const PROBE_SCRIPT = `
+const net = require('net')
+const [targets, timeout] = JSON.parse(process.env.OWLMEANS_TEST_PROBE)
+let pending = targets.length
+let last = ''
+for (const target of targets) {
+  let settled = false
+  const socket = net.connect({ host: target.host, port: target.port })
+  const fail = code => {
+    if (settled) return
+    settled = true
+    socket.destroy()
+    last = code
+    if (--pending === 0) { process.stdout.write(last); process.exit(1) }
+  }
+  socket.setTimeout(timeout)
+  socket.once('connect', () => process.exit(0))
+  socket.once('timeout', () => fail('ETIMEDOUT'))
+  socket.once('error', error => fail(error.code || String(error)))
+}
+`;
+/**
+ * `null` when at least one target accepts a TCP connection, otherwise the reason none did.
+ *
+ * A probe that cannot run at all also answers `null`: not knowing is not evidence the service is
+ * down, and the suite then behaves exactly as it did before probes existed.
+ */
+export const probeTargets = (targets) => {
+    const key = targets.map(({ host, port }) => `${host}:${port}`).join(',');
+    if (answers.has(key)) {
+        return answers.get(key) ?? null;
+    }
+    const result = spawnSync(process.execPath, ['-e', PROBE_SCRIPT], {
+        env: { ...process.env, OWLMEANS_TEST_PROBE: JSON.stringify([targets, CONNECT_TIMEOUT_MS]) },
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: CONNECT_TIMEOUT_MS + SPAWN_GRACE_MS,
+        encoding: 'utf8',
+    });
+    const answer = result.error == null && result.status === 1
+        ? `nothing answers at ${key} (${result.stdout.trim() !== '' ? result.stdout.trim() : 'unreachable'})`
+        : null;
+    answers.set(key, answer);
+    return answer;
+};
+/**
+ * The skip reason for a populated connection-string variable whose server does not answer, or
+ * `null` when it answers or cannot be probed. Printed once per variable and address, so a closed
+ * gate is never mistaken for a suite that has nothing to run.
+ */
+export const unreachableReason = (variable, url, defaultPort) => {
+    const targets = parseTargets(url, defaultPort);
+    if (targets == null) {
+        return null;
+    }
+    const unreachable = probeTargets(targets);
+    if (unreachable == null) {
+        return null;
+    }
+    const reason = `${variable} is set, but ${unreachable} — start the service (or its port-forward) to run these specs`;
+    if (!warned.has(reason)) {
+        warned.add(reason);
+        console.warn(`@owlmeans/test-integration: skipping — ${reason}`);
+    }
+    return reason;
+};
+//# sourceMappingURL=reachability.js.map

package/build/reachability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reachability.js","sourceRoot":"","sources":["../src/reachability.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/test-integration",
-  "version": "0.1.18-rc.3",
+  "version": "0.1.18-rc.30",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,11 +21,11 @@
     }
   },
   "dependencies": {
-    "@owlmeans/test": "^0.1.18-rc.3"
+    "@owlmeans/test": "^0.1.18-rc.33"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "^0.1.18-rc.3",
-    "@types/bun": "^1.3.14",
+    "@owlmeans/dep-config": "^0.1.18-rc.6",
+    "@types/bun": "^1.4.0",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

package/src/gates.ts

@@ -1,4 +1,5 @@
 import { hasEnv, requireEnv } from '@owlmeans/test'
+import { unreachableReason } from './reachability.js'
 
 export interface IntegrationGate<E> {
   skip: boolean
@@ -14,14 +15,31 @@ const collect = <E>(keys: (keyof E & string)[]): Partial<E> => {
   return env as Partial<E>
 }
 
+/**
+ * A connection-string variable whose server must answer a TCP connect for the gate to open.
+ *
+ * Only for a service a developer reaches through a local address that can go away — a
+ * port-forward, a container. A populated variable pointing at nothing then closes the gate with
+ * a printed reason instead of failing every suite behind it on a refused connection.
+ */
+interface Reachable<E> {
+  key: keyof E & string
+  defaultPort: number
+}
+
 const toIntegrationGate = <E>(
   required: (keyof E & string)[],
-  optional: (keyof E & string)[] = []
+  optional: (keyof E & string)[] = [],
+  reachable?: Reachable<E>
 ): IntegrationGate<E> => {
   const gate = requireEnv(required)
   const env = collect<E>([...required, ...optional])
-  if ('ok' in gate) return { skip: false, env }
-  return { skip: true, reason: gate.reason, env }
+  if (!('ok' in gate)) return { skip: true, reason: gate.reason, env }
+  if (reachable != null) {
+    const reason = unreachableReason(reachable.key, process.env[reachable.key] as string, reachable.defaultPort)
+    if (reason != null) return { skip: true, reason, env }
+  }
+  return { skip: false, env }
 }
 
 export interface MongoEnv {
@@ -30,7 +48,7 @@ export interface MongoEnv {
 }
 
 export const mongoGate = (): IntegrationGate<MongoEnv> =>
-  toIntegrationGate<MongoEnv>(['MONGO_URL'], ['MONGO_TEST_DB_PREFIX'])
+  toIntegrationGate<MongoEnv>(['MONGO_URL'], ['MONGO_TEST_DB_PREFIX'], { key: 'MONGO_URL', defaultPort: 27017 })
 
 export interface RedisEnv {
   REDIS_URL: string
@@ -38,7 +56,7 @@ export interface RedisEnv {
 }
 
 export const redisGate = (): IntegrationGate<RedisEnv> =>
-  toIntegrationGate<RedisEnv>(['REDIS_URL'], ['REDIS_TEST_KEY_PREFIX'])
+  toIntegrationGate<RedisEnv>(['REDIS_URL'], ['REDIS_TEST_KEY_PREFIX'], { key: 'REDIS_URL', defaultPort: 6379 })
 
 export interface S3Env {
   S3_ENDPOINT: string
@@ -68,7 +86,7 @@ export interface PostgresEnv {
 }
 
 export const postgresGate = (): IntegrationGate<PostgresEnv> =>
-  toIntegrationGate<PostgresEnv>(['POSTGRES_URL'], ['POSTGRES_TEST_DB_PREFIX'])
+  toIntegrationGate<PostgresEnv>(['POSTGRES_URL'], ['POSTGRES_TEST_DB_PREFIX'], { key: 'POSTGRES_URL', defaultPort: 5432 })
 
 export interface SmtpEnv {
   SMTP_HOST: string

package/src/reachability.ts

@@ -0,0 +1,135 @@
+import { spawnSync } from 'node:child_process'
+
+/**
+ * Whether the server a connection string names answers at all — asked synchronously, because
+ * Bun decides `test` vs `test.skip` synchronously and every gate is read at module scope.
+ *
+ * A populated variable says where the service should be, not that it is there: a developer's
+ * `.env` keeps the port-forward address long after the forward is gone, and a suite that trusts
+ * it spends its whole `beforeAll` budget on a refused connection and FAILS. Only a TCP connect is
+ * asked — never a login — so no driver is needed here and no credential leaves the variable.
+ */
+
+export interface ProbeTarget {
+  host: string
+  port: number
+}
+
+/** How long one connect may take before the address counts as unreachable. */
+const CONNECT_TIMEOUT_MS = 1_500
+
+/** The probe runs in a child process; this covers its own startup on a loaded machine. */
+const SPAWN_GRACE_MS = 5_000
+
+const answers = new Map<string, string | null>()
+const warned = new Set<string>()
+
+/**
+ * Every `host:port` in the authority of a connection string, or `null` when the string names
+ * nothing a TCP connect can check — an SRV record, a unix socket, or a shape this cannot read.
+ * `null` leaves the gate exactly as the variable alone would have it.
+ */
+export const parseTargets = (url: string, defaultPort: number): ProbeTarget[] | null => {
+  const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(url)
+  if (scheme == null || scheme[1].toLowerCase().endsWith('+srv')) {
+    return null
+  }
+  const rest = url.slice(scheme[0].length)
+  const end = rest.search(/[/?#]/)
+  const authority = end < 0 ? rest : rest.slice(0, end)
+  const hosts = authority.slice(authority.lastIndexOf('@') + 1)
+
+  const targets: ProbeTarget[] = []
+  for (const entry of hosts.split(',')) {
+    const match = /^(\[[^\]]+\]|[^:]*)(?::(\d+))?$/.exec(entry)
+    if (match == null) {
+      return null
+    }
+    let host: string
+    try {
+      host = decodeURIComponent(match[1]).replace(/^\[|\]$/g, '')
+    } catch {
+      return null
+    }
+    if (host === '' || host.includes('/')) {
+      return null
+    }
+    targets.push({ host, port: match[2] != null ? parseInt(match[2], 10) : defaultPort })
+  }
+
+  return targets.length > 0 ? targets : null
+}
+
+// Runs under whichever runtime runs the suite (`process.execPath`), so it is plain CommonJS
+// that both `bun -e` and `node -e` evaluate.
+const PROBE_SCRIPT = `
+const net = require('net')
+const [targets, timeout] = JSON.parse(process.env.OWLMEANS_TEST_PROBE)
+let pending = targets.length
+let last = ''
+for (const target of targets) {
+  let settled = false
+  const socket = net.connect({ host: target.host, port: target.port })
+  const fail = code => {
+    if (settled) return
+    settled = true
+    socket.destroy()
+    last = code
+    if (--pending === 0) { process.stdout.write(last); process.exit(1) }
+  }
+  socket.setTimeout(timeout)
+  socket.once('connect', () => process.exit(0))
+  socket.once('timeout', () => fail('ETIMEDOUT'))
+  socket.once('error', error => fail(error.code || String(error)))
+}
+`
+
+/**
+ * `null` when at least one target accepts a TCP connection, otherwise the reason none did.
+ *
+ * A probe that cannot run at all also answers `null`: not knowing is not evidence the service is
+ * down, and the suite then behaves exactly as it did before probes existed.
+ */
+export const probeTargets = (targets: ProbeTarget[]): string | null => {
+  const key = targets.map(({ host, port }) => `${host}:${port}`).join(',')
+  if (answers.has(key)) {
+    return answers.get(key) ?? null
+  }
+
+  const result = spawnSync(process.execPath, ['-e', PROBE_SCRIPT], {
+    env: { ...process.env, OWLMEANS_TEST_PROBE: JSON.stringify([targets, CONNECT_TIMEOUT_MS]) },
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: CONNECT_TIMEOUT_MS + SPAWN_GRACE_MS,
+    encoding: 'utf8',
+  })
+  const answer = result.error == null && result.status === 1
+    ? `nothing answers at ${key} (${result.stdout.trim() !== '' ? result.stdout.trim() : 'unreachable'})`
+    : null
+  answers.set(key, answer)
+
+  return answer
+}
+
+/**
+ * The skip reason for a populated connection-string variable whose server does not answer, or
+ * `null` when it answers or cannot be probed. Printed once per variable and address, so a closed
+ * gate is never mistaken for a suite that has nothing to run.
+ */
+export const unreachableReason = (variable: string, url: string, defaultPort: number): string | null => {
+  const targets = parseTargets(url, defaultPort)
+  if (targets == null) {
+    return null
+  }
+  const unreachable = probeTargets(targets)
+  if (unreachable == null) {
+    return null
+  }
+
+  const reason = `${variable} is set, but ${unreachable} — start the service (or its port-forward) to run these specs`
+  if (!warned.has(reason)) {
+    warned.add(reason)
+    console.warn(`@owlmeans/test-integration: skipping — ${reason}`)
+  }
+
+  return reason
+}