@zukhruf/testing 0.3.8 → 0.3.9

package/README.md

@@ -8,32 +8,33 @@ The words in these documents have one meaning each. See the glossary in [CONTEXT
 
 Each area has its own import path, so a test loads only the drivers it uses. The three drivers are optional peer dependencies: install the one an area names.
 
-| Import                        | Gives                                                                                                        | Needs                    |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------ |
-| `@zukhruf/testing/async`      | `timebox`, `settleWithin`                                                                                    |                          |
-| `@zukhruf/testing/docker`     | `Docker`, `Container`, `ServiceContainer`, `DockerVolume`, `DockerDirectory`, `TestRun`, `skipWithoutDocker` | Docker CLI               |
-| `@zukhruf/testing/postgres`   | `Postgres`                                                                                                   | Docker CLI               |
-| `@zukhruf/testing/mysql`      | `Mysql`                                                                                                      | Docker CLI               |
-| `@zukhruf/testing/mariadb`    | `Mariadb`                                                                                                    | Docker CLI               |
-| `@zukhruf/testing/sqlserver`  | `SqlServer`, `SQL_SERVER_FULL_IMAGE`, `SQL_SERVER_EDGE_IMAGE`                                                | Docker CLI, `mssql`      |
-| `@zukhruf/testing/clickhouse` | `ClickHouse`                                                                                                 | Docker CLI               |
-| `@zukhruf/testing/sqlite`     | `Sqlite`                                                                                                     |                          |
-| `@zukhruf/testing/duckdb`     | `DuckDB`                                                                                                     | `@duckdb/node-api`       |
-| `@zukhruf/testing/bigquery`   | `BigQuery`                                                                                                   | `@google-cloud/bigquery` |
-| `@zukhruf/testing/http`       | `HttpServer`                                                                                                 |                          |
-| `@zukhruf/testing/streams`    | `StreamHarness`                                                                                              |                          |
+| Import                        | Gives                                                                                   | Needs                    |
+| ----------------------------- | --------------------------------------------------------------------------------------- | ------------------------ |
+| `@zukhruf/testing/async`      | `timebox`, `settleWithin`                                                               |                          |
+| `@zukhruf/testing/docker`     | `Docker`, `Container`, `ServiceContainer`, `DockerVolume`, `DockerDirectory`, `TestRun` | Docker CLI               |
+| `@zukhruf/testing/postgres`   | `Postgres`                                                                              | Docker CLI               |
+| `@zukhruf/testing/mysql`      | `Mysql`                                                                                 | Docker CLI               |
+| `@zukhruf/testing/mariadb`    | `Mariadb`                                                                               | Docker CLI               |
+| `@zukhruf/testing/sqlserver`  | `SqlServer`, `SQL_SERVER_FULL_IMAGE`, `SQL_SERVER_EDGE_IMAGE`                           | Docker CLI, `mssql`      |
+| `@zukhruf/testing/clickhouse` | `ClickHouse`                                                                            | Docker CLI               |
+| `@zukhruf/testing/sqlite`     | `Sqlite`                                                                                |                          |
+| `@zukhruf/testing/duckdb`     | `DuckDB`                                                                                | `@duckdb/node-api`       |
+| `@zukhruf/testing/bigquery`   | `BigQuery`                                                                              | `@google-cloud/bigquery` |
+| `@zukhruf/testing/http`       | `HttpServer`                                                                            |                          |
+| `@zukhruf/testing/streams`    | `StreamHarness`                                                                         |                          |
 
 ## Docker
 
-A `Docker` is the engine the Docker CLI selects. It resolves the engine once, on first use, and every handle it returns keeps that engine. It supports local Unix sockets, Docker Desktop's named pipe on Windows (`npipe://`), and SSH engines (`ssh://`). On Windows, volumes and containers are tested; `directory()` is not.
+A `Docker` is the engine the Docker CLI selects. It resolves the engine once, on first use, and every handle it returns keeps that engine. It supports local Unix sockets, Docker Desktop's named pipe on Windows (`npipe://`), and SSH engines (`ssh://`).
+
+A test that needs Docker has no skip option. When the engine does not answer, the first acquisition fails with "Docker is required for container-backed tests" and the engine's error as the cause. Start Docker to run these tests.
 
 ```ts
-import { Docker, TestRun, skipWithoutDocker } from '@zukhruf/testing/docker';
+import { Docker, TestRun } from '@zukhruf/testing/docker';
 
 const docker = new Docker({ testRun: TestRun.fromEnvironment(process.env) });
-const skip = await skipWithoutDocker(docker, process.env);
 
-test('a holder in another container', { skip }, async () => {
+test('a holder in another container', async () => {
   await using volume = await docker.volume();
   await using holder = await docker.start({
     image: 'node:lts-alpine',
@@ -76,16 +77,6 @@ docker stop <container-id>
 
 They run with `--rm`, so stopping also removes them. The image tag is part of the configuration: stop the server to pick up a newer image behind the same tag.
 
-### Skipping without Docker
-
-`skipWithoutDocker(docker, process.env)` returns the `skip` option of a test that needs Docker. `ZUKHRUF_TESTING_DOCKER` decides:
-
-| Value      | Result                                                                                |
-| ---------- | ------------------------------------------------------------------------------------- |
-| `required` | Runs. Throws when Docker does not answer, so a machine that must run the tests fails. |
-| `skip`     | Skips.                                                                                |
-| unset      | Runs when Docker answers, skips with a reason when it does not.                       |
-
 ## The supervisor
 
 Disposal cleans up after a test that ends. A test process that is killed (a timeout, Ctrl-C, `--test-force-exit`) never disposes its handles, and a running container does not stop by itself. The `zukhruf-docker-tests` command runs `node --test` as one supervised run:
@@ -111,7 +102,7 @@ import { Postgres } from '@zukhruf/testing/postgres';
 
 const postgres = new Postgres({ docker });
 
-test('stores a record', { skip }, async () => {
+test('stores a record', async () => {
   await using database = await postgres.database();
   // database.connectionString. Close your clients before the scope ends.
 });
@@ -156,4 +147,4 @@ npx nx run testing:test        # builds, then runs the tests
 npx nx run testing:typecheck   # formats, lints, then type checks
 ```
 
-The Docker-backed tests follow `ZUKHRUF_TESTING_DOCKER`. CI skips them on every operating system, and `.github/workflows/docker.yml` runs them with `required` when this package changes: on Linux, and on Windows through Docker Desktop for the mutex's container tests.
+The tests that need Docker run on every machine, and fail when the engine does not answer. CI runs every test on Linux, where Docker runs Linux containers. The `test` target runs alone (`parallelism: false`): Nx starts no other task while it runs, because its database servers slow down the timing tests of the other projects.

package/dist/docker/index.d.ts

@@ -1,7 +1,6 @@
 export { Container, type DockerCommand, ServiceContainer, } from './container.ts';
 export { DockerDirectory } from './directory.ts';
 export { type ContainerOptions, Docker, type DockerOptions, type Mount, type ServiceOptions, } from './docker.ts';
-export { DOCKER_TESTS, skipWithoutDocker } from './skip-without-docker.ts';
 export { TestRun } from './test-run.ts';
 export { DockerVolume } from './volume.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/docker/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docker/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,KAAK,aAAa,EAClB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EACL,KAAK,gBAAgB,EACrB,MAAM,EACN,KAAK,aAAa,EAClB,KAAK,KAAK,EACV,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docker/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,KAAK,aAAa,EAClB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EACL,KAAK,gBAAgB,EACrB,MAAM,EACN,KAAK,aAAa,EAClB,KAAK,KAAK,EACV,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/docker/index.js

@@ -1,7 +1,6 @@
 export { Container, ServiceContainer, } from "./container.js";
 export { DockerDirectory } from "./directory.js";
 export { Docker, } from "./docker.js";
-export { DOCKER_TESTS, skipWithoutDocker } from "./skip-without-docker.js";
 export { TestRun } from "./test-run.js";
 export { DockerVolume } from "./volume.js";
 //# sourceMappingURL=index.js.map

package/dist/docker/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/docker/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EAET,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAEL,MAAM,GAIP,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/docker/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EAET,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAEL,MAAM,GAIP,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zukhruf/testing",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Disposable fixtures for integration tests: Docker containers and database servers, SQLite and DuckDB databases, HTTP servers and streams. A supervisor removes what a killed test run left behind.",
   "license": "MIT",
   "repository": {

package/dist/docker/skip-without-docker.d.ts

@@ -1,12 +0,0 @@
-import type { Docker } from './docker.ts';
-/** How tests treat Docker: `required`, `skip`, or unset to run when Docker answers. */
-export declare const DOCKER_TESTS = "ZUKHRUF_TESTING_DOCKER";
-/**
- * The `skip` option of a test that needs Docker, read from the environment the
- * host passes (`process.env`). With `ZUKHRUF_TESTING_DOCKER=required` it
- * throws when Docker does not answer, so a machine that must run the tests
- * fails instead of skipping them. With `skip` it always skips. Unset, it skips
- * only when Docker does not answer.
- */
-export declare function skipWithoutDocker(docker: Docker, environment: Readonly<Record<string, string | undefined>>): Promise<string | false>;
-//# sourceMappingURL=skip-without-docker.d.ts.map

package/dist/docker/skip-without-docker.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"skip-without-docker.d.ts","sourceRoot":"","sources":["../../src/docker/skip-without-docker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,uFAAuF;AACvF,eAAO,MAAM,YAAY,2BAA2B,CAAC;AAErD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GACxD,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,CAuBzB"}

package/dist/docker/skip-without-docker.js

@@ -1,31 +0,0 @@
-/** How tests treat Docker: `required`, `skip`, or unset to run when Docker answers. */
-export const DOCKER_TESTS = 'ZUKHRUF_TESTING_DOCKER';
-/**
- * The `skip` option of a test that needs Docker, read from the environment the
- * host passes (`process.env`). With `ZUKHRUF_TESTING_DOCKER=required` it
- * throws when Docker does not answer, so a machine that must run the tests
- * fails instead of skipping them. With `skip` it always skips. Unset, it skips
- * only when Docker does not answer.
- */
-export async function skipWithoutDocker(docker, environment) {
-    const mode = environment[DOCKER_TESTS];
-    switch (mode) {
-        case 'skip':
-            return `${DOCKER_TESTS}=skip`;
-        case 'required':
-            await docker.command(['info']).catch((cause) => {
-                throw new Error(`${DOCKER_TESTS}=required, but Docker does not answer`, {
-                    cause,
-                });
-            });
-            return false;
-        case undefined:
-        case '':
-            return (await docker.isAvailable())
-                ? false
-                : `needs Docker; set ${DOCKER_TESTS}=required to fail instead of skipping`;
-        default:
-            throw new Error(`${DOCKER_TESTS} is "required" or "skip", not "${mode}"`);
-    }
-}
-//# sourceMappingURL=skip-without-docker.js.map

package/dist/docker/skip-without-docker.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"skip-without-docker.js","sourceRoot":"","sources":["../../src/docker/skip-without-docker.ts"],"names":[],"mappings":"AAEA,uFAAuF;AACvF,MAAM,CAAC,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAc,EACd,WAAyD;IAEzD,MAAM,IAAI,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;IACvC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,MAAM;YACT,OAAO,GAAG,YAAY,OAAO,CAAC;QAChC,KAAK,UAAU;YACb,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBACtD,MAAM,IAAI,KAAK,CACb,GAAG,YAAY,uCAAuC,EACtD;oBACE,KAAK;iBACN,CACF,CAAC;YACJ,CAAC,CAAC,CAAC;YACH,OAAO,KAAK,CAAC;QACf,KAAK,SAAS,CAAC;QACf,KAAK,EAAE;YACL,OAAO,CAAC,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC;gBACjC,CAAC,CAAC,KAAK;gBACP,CAAC,CAAC,qBAAqB,YAAY,uCAAuC,CAAC;QAC/E;YACE,MAAM,IAAI,KAAK,CAAC,GAAG,YAAY,kCAAkC,IAAI,GAAG,CAAC,CAAC;IAC9E,CAAC;AACH,CAAC"}