@zukhruf/testing 0.5.2 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +2 -45
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -136,6 +136,8 @@ docker stop <container-id>
136
136
 
137
137
  The engine removes a server when it stops, so stopping also removes it. The image tag is part of the configuration: stop the server to pick up a newer image behind the same tag.
138
138
 
139
+ A shared server starts on the first `database()` call that needs it. When that call is in a test, the time limit of the test also counts the start of the server. Each fixture sets a time limit for the start, its readiness bound: Postgres 60 s, MySQL and MariaDB 90 s, SQL Server 180 s. When the server does not answer in that time, the call fails with "Container … was not ready" and the output of the container. The default time limit of `@zukhruf/nx/test` is 240 s: the slowest readiness bound plus 60 s for the test (see [the test area](../nx/README.md#what-the-test-target-runs)). When you change a readiness bound, change that default with it.
140
+
139
141
  ## A killed run
140
142
 
141
143
  Disposal cleans up after a test that ends. A test process that is killed (a timeout with `--test-force-exit`, Ctrl-C, an out-of-memory kill) does not dispose its handles. A running container does not stop by itself. Thus Node's global setup and global teardown make the test processes of one `node --test` invocation into one run.
@@ -170,51 +172,6 @@ On an SSH engine, run one test file at a time with `--test-concurrency=1` if the
170
172
 
171
173
  Another Docker client can create containers for the run, for example a sandbox launcher. Give it `testbed.defaults`: its `Labels` are the run's labels, and its `HostConfig` has the default `Memory` and `NanoCpus`. A client that takes the Engine API body uses them as they are. Map them to the options of a client that has its own options. Reading `defaults` writes a process record for this process, so the global teardown keeps the run's records while this process lives.
172
174
 
173
- ## Shared servers before the first test
174
-
175
- Status: design for review (#3404). The code does not exist yet.
176
-
177
- A shared server starts on the first `database()` call that needs it. When that call is in a test, the time limit of the test also counts the start of the server. A cold start pulls the image and boots the server, and on a slow engine that takes tens of seconds. SQL Server takes the longest. A cold start happens on each CI run, and on each machine after a new version of this package, because a new version selects new shared servers (see [Shared servers](#shared-servers)). Then the first test of a file can fail at the time limit, for example at the 60 s default of `@zukhruf/nx/test`.
178
-
179
- To prevent this, make a prebuilt fixture of each shared server: the global setup creates the server before the run starts. Write one global setup file in your project. Give `prebuild` one acquisition for each shared server that your tests use. Use the same options as your tests, because different options select a different server.
180
-
181
- ```ts
182
- // src/testing/docker-global-setup.ts
183
- import { prebuild } from '@zukhruf/testing/docker-global-setup';
184
- import { Postgres } from '@zukhruf/testing/postgres';
185
- import { SQL_SERVER_FULL_IMAGE, SqlServer } from '@zukhruf/testing/sqlserver';
186
-
187
- export { globalTeardown } from '@zukhruf/testing/docker-global-setup';
188
-
189
- export const globalSetup = prebuild([
190
- () => new Postgres({ environment: process.env }).database(),
191
- () =>
192
- new SqlServer({
193
- environment: process.env,
194
- image: SQL_SERVER_FULL_IMAGE,
195
- }).database(),
196
- ]);
197
- ```
198
-
199
- `@zukhruf/nx/test` uses this file when it is at `src/testing/docker-global-setup.ts` of the project. With no Nx plugin, give its path to `--test-global-setup` (see [A killed run](#a-killed-run)). You must write the file, because Node takes a path there, not a package name, and only your project knows which servers its tests use.
200
-
201
- ```ts
202
- function prebuild(
203
- acquisitions: readonly (() => Promise<AsyncDisposable>)[],
204
- ): () => Promise<void>;
205
- ```
206
-
207
- An acquisition is a function that creates a fixture and returns its handle. It can be a `database()` call, or a fixture of your own that starts a shared server. `prebuild` returns a global setup. Node calls it one time for each `node --test` process. It does these steps:
208
-
209
- 1. It calls all the acquisitions at the same time.
210
- 2. It disposes each handle when its acquisition resolves. The database drops, and the shared server stays.
211
- 3. It waits until all the acquisitions and disposals end. When one or more acquisitions fail, it rejects with an `AggregateError` of the errors, and no test runs.
212
- 4. It calls `globalSetup`, which starts the run.
213
-
214
- The acquisitions run before the run starts. Thus the runner writes no process record, and the global teardown, which runs in the runner, can delete the run's records. The databases of the acquisitions have no run id in their names, and disposal drops them. The runner holds a process lease while it lives, so a teardown of another version keeps these servers during your run.
215
-
216
- A test still calls `database()`. The server already answers, so the call only creates a database.
217
-
218
175
  ## Databases
219
176
 
220
177
  `Postgres`, `Mysql`, `Mariadb`, `SqlServer` and `ClickHouse` take the `environment`, such as `process.env`. The environment selects the engine and the run. Each instance makes its own `DockerTestbed` from it. Each `database()` call creates a fresh database on a shared server; disposal drops it. In a run, the name of the database has the run's id. When a test process is killed before its disposal, or a drop in disposal fails, the global teardown drops the database (see [A killed run](#a-killed-run)). Outside a run, only disposal drops it. `start()` creates a dedicated server; disposal stops it.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zukhruf/testing",
3
- "version": "0.5.2",
3
+ "version": "0.6.1",
4
4
  "description": "Disposable fixtures for integration tests: Docker containers, database servers, SQLite and DuckDB databases, HTTP servers, streams, temporary directories and intercepted requests. Node's global setup and teardown remove what a killed test run left behind.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -144,7 +144,7 @@
144
144
  "pg": "^8.23.1"
145
145
  },
146
146
  "dependencies": {
147
- "@zukhruf/docker": "^0.5.2",
147
+ "@zukhruf/docker": "^0.6.1",
148
148
  "nano-spawn": "^2.1.0",
149
149
  "p-memoize": "^8.0.0",
150
150
  "p-retry": "^8.0.1"