@owlmeans/test-integration 0.1.18-rc.22 → 0.1.18-rc.24

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@^0.1.18-rc.28
+npx @owlmeans/agent-skills@^0.1.18-rc.31
 ```
 
 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.22",
-  "generatedAt": "2026-09-17T08:16:11.217Z",
+  "version": "0.1.18-rc.24",
+  "generatedAt": "2026-09-21T21:55:20.669Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -6,7 +6,7 @@ description: Category-C integration tests for OwlMeans Common packages that talk
 
 # Integration Tests — Category C
 
-**Install:** `"@owlmeans/test-integration": "^0.1.18-rc.22"` in `devDependencies`
+**Install:** `"@owlmeans/test-integration": "^0.1.18-rc.24"` in `devDependencies`
 
 Category C applies to packages that integrate with external services: `postgres`,
 `postgres-resource`, `mongo`, `mongo-resource`, `redis`, `redis-resource`, `redis-queue`,
@@ -25,7 +25,7 @@ service hands it is category C even when it names no driver of its own.
 
 | Helper | Purpose |
 |---|---|
-| `postgresGate()`, `mongoGate()`, `redisGate()`, `s3Gate()`, `kubeGate()`, `smtpGate()` | Read env, return `IntegrationGate<E>` = `{ skip, reason?, env }`. |
+| `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. |
@@ -45,6 +45,28 @@ Each gate fails closed on its **required** variables and treats the rest as opti
 `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 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.
@@ -69,14 +91,18 @@ asserts on the request it builds and the API's reply.
 
 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** —
-never a failure.
+`@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:
 
@@ -288,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.22",
+  "version": "0.1.18-rc.24",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,7 +21,7 @@
     }
   },
   "dependencies": {
-    "@owlmeans/test": "^0.1.18-rc.24"
+    "@owlmeans/test": "^0.1.18-rc.27"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "^0.1.18-rc.6",

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
+}