@zukhruf/testing 0.4.1 → 0.4.2
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.
- package/README.md +45 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -170,6 +170,51 @@ On an SSH engine, run one test file at a time with `--test-concurrency=1` if the
|
|
|
170
170
|
|
|
171
171
|
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
172
|
|
|
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
|
+
|
|
173
218
|
## Databases
|
|
174
219
|
|
|
175
220
|
`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.4.
|
|
3
|
+
"version": "0.4.2",
|
|
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.4.
|
|
147
|
+
"@zukhruf/docker": "^0.4.2",
|
|
148
148
|
"nano-spawn": "^2.1.0",
|
|
149
149
|
"p-memoize": "^8.0.0",
|
|
150
150
|
"p-retry": "^8.0.1"
|