@omnitron-dev/testing 0.2.0 → 0.3.0

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 (65) hide show
  1. package/dist/async/events.js.map +1 -1
  2. package/dist/async/retry.js.map +1 -1
  3. package/dist/async/wait.js.map +1 -1
  4. package/dist/docker/database-manager.js.map +1 -1
  5. package/dist/docker/docker-test-manager.d.ts +8 -0
  6. package/dist/docker/docker-test-manager.js +194 -45
  7. package/dist/docker/docker-test-manager.js.map +1 -1
  8. package/dist/docker/redis-manager.js +24 -50
  9. package/dist/docker/redis-manager.js.map +1 -1
  10. package/dist/errors.js.map +1 -1
  11. package/dist/index.d.ts +1 -1
  12. package/dist/runtime/bun-adapter.d.ts +23 -1
  13. package/dist/runtime/bun-adapter.js +3 -0
  14. package/dist/runtime/bun-adapter.js.map +1 -1
  15. package/dist/runtime/deno-adapter.d.ts +72 -16
  16. package/dist/runtime/deno-adapter.js +79 -77
  17. package/dist/runtime/deno-adapter.js.map +1 -1
  18. package/dist/runtime/node-adapter.d.ts +14 -2
  19. package/dist/titan/database/database-testing.module.d.ts +1 -1
  20. package/dist/titan/database/database-testing.module.js.map +1 -1
  21. package/dist/titan/database/test-utilities.d.ts +1 -1
  22. package/dist/titan/database/test-utilities.js +1 -1
  23. package/dist/titan/database/test-utilities.js.map +1 -1
  24. package/dist/titan/index.d.ts +2 -2
  25. package/dist/titan/index.js +1 -1
  26. package/dist/titan/index.js.map +1 -1
  27. package/dist/titan/nexus/mock-provider.js.map +1 -1
  28. package/dist/titan/nexus/test-container.js.map +1 -1
  29. package/dist/titan/nexus/test-utilities.js.map +1 -1
  30. package/dist/titan/pm/mock-process-spawner.js.map +1 -1
  31. package/dist/titan/pm/mock-spawner.js.map +1 -1
  32. package/dist/titan/pm/test-process-manager.js.map +1 -1
  33. package/dist/titan/redis-test-utils.d.ts +6 -0
  34. package/dist/titan/redis-test-utils.js +29 -0
  35. package/dist/titan/redis-test-utils.js.map +1 -1
  36. package/dist/titan/test-application.js.map +1 -1
  37. package/dist/titan/test-fixtures.js.map +1 -1
  38. package/dist/titan/test-mocks.js.map +1 -1
  39. package/dist/titan/test-module.js.map +1 -1
  40. package/package.json +36 -29
  41. package/src/docker/a-port-the-network-could-reach.spec.ts +66 -0
  42. package/src/docker/docker-orphan-reaper.spec.ts +175 -0
  43. package/src/docker/docker-port-collision.spec.ts +97 -0
  44. package/src/docker/docker-test-manager.spec.ts +122 -0
  45. package/src/docker/docker-test-manager.ts +329 -20
  46. package/src/docker/docker-volume-cleanup.spec.ts +66 -0
  47. package/src/docker/redis-manager.ts +41 -58
  48. package/src/docker/types.ts +1 -0
  49. package/src/runtime/adapter-surface.spec.ts +83 -0
  50. package/src/runtime/bun-adapter.ts +21 -0
  51. package/src/runtime/deno-adapter.ts +149 -104
  52. package/src/titan/database/database-testing.module.ts +1 -1
  53. package/src/titan/database/test-utilities.ts +1 -1
  54. package/src/titan/index.ts +6 -1
  55. package/src/titan/nexus/test-utilities.ts +1 -0
  56. package/src/titan/pm/test-process-manager.ts +12 -2
  57. package/src/titan/redis-test-utils.ts +67 -0
  58. package/runtime/bun.d.ts +0 -2
  59. package/runtime/bun.js +0 -5
  60. package/runtime/bun.ts +0 -7
  61. package/runtime/deno.d.ts +0 -2
  62. package/runtime/deno.js +0 -4
  63. package/runtime/vitest.d.ts +0 -2
  64. package/runtime/vitest.js +0 -16
  65. package/runtime/vitest.ts +0 -7
@@ -0,0 +1,175 @@
1
+ /**
2
+ * A test run that is killed leaves its containers running forever.
3
+ *
4
+ * `cleanup` is wired to `process.on('exit')`, `SIGINT` and `SIGTERM`, which
5
+ * covers every ending the process gets to observe. It does not cover SIGKILL,
6
+ * and that is the ending vitest uses when a worker overruns its teardown — so
7
+ * the containers of a killed run keep their ports, their memory and their
8
+ * anonymous volumes, and nothing on the machine is left holding a reference to
9
+ * them.
10
+ *
11
+ * Measured on this machine: `docker ps -a --filter label=test.cleanup=true`
12
+ * returned 67 containers, some `Up 7 hours`, some still in `Created` — from
13
+ * runs that had ended hours earlier. Their layers and volumes were a large part
14
+ * of a Docker VM at 93% (191.2 G of 205.4 G), which is what turned
15
+ * `titan-redis` (45 failures, 112 × "no space") and every `test/security` file
16
+ * in payments (19 failures, all `TRUNCATE` in `beforeEach`) red. None of those
17
+ * failures were in the code they named.
18
+ *
19
+ * The `test.manager` label already carries the creating process's pid, so an
20
+ * orphan is identifiable without guessing: the process that owns it is gone.
21
+ * Two conditions, both required, because either one alone can be wrong —
22
+ *
23
+ * - the owner pid is not alive. A pid can be REUSED, so this alone could call
24
+ * a live manager's container someone else's;
25
+ * - the container is older than a grace period. A container seconds old
26
+ * belongs to a run that is starting, whatever the pid table says.
27
+ *
28
+ * Reaping needs both, so a container is removed only when it is both
29
+ * unclaimed and not new. The failure direction of each condition is to leave
30
+ * a container behind, which the next run reaps — never to remove a live one.
31
+ */
32
+ import { describe, it, expect, vi, beforeEach } from 'vitest';
33
+
34
+ const execFileSyncMock = vi.fn<(...args: any[]) => any>(() => '');
35
+
36
+ vi.mock('node:child_process', async (importOriginal) => {
37
+ const actual = await importOriginal<typeof import('node:child_process')>();
38
+ return { ...actual, execFileSync: (...args: unknown[]) => execFileSyncMock(...args) };
39
+ });
40
+ vi.mock('child_process', async (importOriginal) => {
41
+ const actual = await importOriginal<typeof import('child_process')>();
42
+ return { ...actual, execFileSync: (...args: unknown[]) => execFileSyncMock(...args) };
43
+ });
44
+
45
+ const { DockerTestManager } = await import('./docker-test-manager.js');
46
+
47
+ /** A pid above Linux/macOS pid_max: `kill(pid, 0)` is guaranteed ESRCH. */
48
+ const DEAD_PID = 9_999_999;
49
+
50
+ /** `docker ps --format` renders this shape; the reaper has to read it back. */
51
+ function psRow(id: string, ageMs: number, managerId: string): string {
52
+ const created = new Date(Date.now() - ageMs);
53
+ const pad = (n: number) => String(n).padStart(2, '0');
54
+ const stamp =
55
+ `${created.getFullYear()}-${pad(created.getMonth() + 1)}-${pad(created.getDate())} ` +
56
+ `${pad(created.getHours())}:${pad(created.getMinutes())}:${pad(created.getSeconds())} ` +
57
+ `${offset(created)} MSK`;
58
+ return `${id}\t${stamp}\ttest.cleanup=true,test.id=${id},test.manager=${managerId}`;
59
+ }
60
+
61
+ function offset(d: Date): string {
62
+ const mins = -d.getTimezoneOffset();
63
+ const sign = mins < 0 ? '-' : '+';
64
+ const abs = Math.abs(mins);
65
+ return `${sign}${String(Math.floor(abs / 60)).padStart(2, '0')}${String(abs % 60).padStart(2, '0')}`;
66
+ }
67
+
68
+ function removedIds(): string[] {
69
+ return execFileSyncMock.mock.calls
70
+ .map((c) => c[1] as string[])
71
+ .filter((args) => Array.isArray(args) && args[0] === 'rm')
72
+ .flatMap((args) => args.filter((a) => a.startsWith('orphan') || a.startsWith('live') || a.startsWith('fresh')));
73
+ }
74
+
75
+ function armPs(rows: string[]) {
76
+ execFileSyncMock.mockImplementation((_bin: string, args: string[]) => {
77
+ if (args?.[0] === 'ps') return rows.join('\n');
78
+ return '';
79
+ });
80
+ }
81
+
82
+ describe('DockerTestManager orphan reaper', () => {
83
+ beforeEach(() => {
84
+ execFileSyncMock.mockReset();
85
+ execFileSyncMock.mockReturnValue('');
86
+ (DockerTestManager as any).orphanReapDone = false;
87
+ });
88
+
89
+ it('removes a container whose owning process is gone', () => {
90
+ armPs([psRow('orphan-1', 2 * 60 * 60 * 1000, `${DEAD_PID}-abc-def`)]);
91
+
92
+ new DockerTestManager();
93
+
94
+ expect(removedIds()).toEqual(['orphan-1']);
95
+ });
96
+
97
+ it('keeps a container whose owning process is still running', () => {
98
+ // A parallel vitest run is exactly this: another worker, alive, with
99
+ // containers this manager must not touch. Removing them is how the
100
+ // previous label-wide cleanup broke parallel runs.
101
+ armPs([psRow('live-1', 2 * 60 * 60 * 1000, `${process.pid}-abc-def`)]);
102
+
103
+ new DockerTestManager();
104
+
105
+ expect(removedIds()).toEqual([]);
106
+ });
107
+
108
+ it('keeps a container that is younger than the grace period', () => {
109
+ // Pids are reused. A container created a minute ago belongs to a run that
110
+ // is starting, whatever the pid table now says about its creator.
111
+ armPs([psRow('fresh-1', 30 * 1000, `${DEAD_PID}-abc-def`)]);
112
+
113
+ new DockerTestManager();
114
+
115
+ expect(removedIds()).toEqual([]);
116
+ });
117
+
118
+ it('reaps in one call rather than one call per container', () => {
119
+ // 67 orphans at ~200 ms per `docker rm` is 13 s added to the start of a
120
+ // test file, paid by every worker at once.
121
+ armPs([
122
+ psRow('orphan-1', 2 * 60 * 60 * 1000, `${DEAD_PID}-a-b`),
123
+ psRow('orphan-2', 2 * 60 * 60 * 1000, `${DEAD_PID}-c-d`),
124
+ psRow('orphan-3', 2 * 60 * 60 * 1000, `${DEAD_PID}-e-f`),
125
+ ]);
126
+
127
+ new DockerTestManager();
128
+
129
+ const rmCalls = execFileSyncMock.mock.calls
130
+ .map((c) => c[1] as string[])
131
+ .filter((args) => Array.isArray(args) && args[0] === 'rm');
132
+
133
+ expect(rmCalls.length, 'one removal call expected for all orphans').toBe(1);
134
+ expect(removedIds()).toEqual(['orphan-1', 'orphan-2', 'orphan-3']);
135
+ });
136
+
137
+ it('removes anonymous volumes along with the orphan', () => {
138
+ // The orphan holds the same anonymous volume a normal removal would drop;
139
+ // reaping without -v converts a container leak into a volume leak.
140
+ armPs([psRow('orphan-1', 2 * 60 * 60 * 1000, `${DEAD_PID}-a-b`)]);
141
+
142
+ new DockerTestManager();
143
+
144
+ const rmArgs = execFileSyncMock.mock.calls
145
+ .map((c) => c[1] as string[])
146
+ .find((args) => Array.isArray(args) && args[0] === 'rm');
147
+
148
+ expect(rmArgs).toContain('-v');
149
+ expect(rmArgs).toContain('-f');
150
+ });
151
+
152
+ it('runs once per process, not once per manager', () => {
153
+ armPs([]);
154
+
155
+ new DockerTestManager();
156
+ const afterFirst = execFileSyncMock.mock.calls.filter((c) => (c[1] as string[])?.[0] === 'ps').length;
157
+ new DockerTestManager();
158
+ const afterSecond = execFileSyncMock.mock.calls.filter((c) => (c[1] as string[])?.[0] === 'ps').length;
159
+
160
+ expect(afterFirst).toBe(1);
161
+ expect(afterSecond).toBe(1);
162
+ });
163
+
164
+ it('survives docker being unavailable', () => {
165
+ // The reaper runs in a constructor. A machine without a reachable docker
166
+ // must still get a manager — the failure belongs to the first container
167
+ // command, with its own message, not to construction.
168
+ execFileSyncMock.mockImplementation((_bin: string, args: string[]) => {
169
+ if (args?.[0] === 'ps') throw new Error('Cannot connect to the Docker daemon');
170
+ return '';
171
+ });
172
+
173
+ expect(() => new DockerTestManager()).not.toThrow();
174
+ });
175
+ });
@@ -0,0 +1,97 @@
1
+ /**
2
+ * A host port taken between the availability check and `docker run` must not
3
+ * fail the container start.
4
+ *
5
+ * `findAvailablePort()` binds a socket, reads the port and releases it. Between
6
+ * that release and `docker run -p <port>:...` anything on the machine can take
7
+ * it — another suite in this repo, another session, a container someone
8
+ * restarted. The window is small and the machine is shared, which is the
9
+ * combination that produces a red test blaming the code under test. Observed
10
+ * exactly that way: a Redis cluster master failed with
11
+ * "Bind for 0.0.0.0:15432 failed: port is already allocated", where 15432
12
+ * belonged to a Postgres container started by a parallel run.
13
+ */
14
+ import { describe, it, expect, afterAll, vi } from 'vitest';
15
+ import { execFileSync } from 'node:child_process';
16
+
17
+ import { DockerTestManager } from './docker-test-manager.js';
18
+
19
+ /**
20
+ * What a test that starts a real container may take: docker's time, not the
21
+ * behaviour's. Measured 2026-09-25 at a load of ~50 on 16 cores with the host
22
+ * volume nearly full: two runs of three exceeded 120 s starting and removing
23
+ * a `redis:7-alpine`, every inner wait inside its own 30 s. These tests say
24
+ * what docker does — waits, leaves another worker's containers, re-draws a
25
+ * port — never how fast.
26
+ */
27
+ const DOCKER_BUDGET_MS = 300_000;
28
+
29
+ function docker(...args: string[]): string {
30
+ return execFileSync('docker', args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
31
+ }
32
+
33
+ function dockerAvailable(): boolean {
34
+ try {
35
+ docker('version', '--format', '{{.Server.Version}}');
36
+ return true;
37
+ } catch {
38
+ return false;
39
+ }
40
+ }
41
+
42
+ const describeOrSkip = dockerAvailable() ? describe : describe.skip;
43
+ if (!dockerAvailable()) {
44
+ console.log('⏭️ Skipping docker-port-collision.spec.ts - requires Docker');
45
+ }
46
+
47
+ describeOrSkip('DockerTestManager host-port collision', () => {
48
+ const manager = new DockerTestManager();
49
+ const holderName = `port-holder-${process.pid}`;
50
+ const probeName = `port-probe-${process.pid}`;
51
+
52
+ afterAll(async () => {
53
+ for (const name of [holderName, probeName]) {
54
+ try {
55
+ docker('rm', '-f', name);
56
+ } catch {
57
+ // already gone
58
+ }
59
+ }
60
+ });
61
+
62
+ it('re-draws an auto port and starts anyway when docker refuses the first one', async () => {
63
+ // Take a port with a real container, the way a parallel suite would.
64
+ const taken = await (manager as any).findAvailablePort();
65
+ await manager.createContainer({
66
+ name: holderName,
67
+ image: 'redis:7-alpine',
68
+ ports: { 6379: taken },
69
+ });
70
+
71
+ // Hand the next container that same port on its first draw. This is the
72
+ // race made deterministic: the availability check said yes, and by the time
73
+ // docker runs the port is gone.
74
+ const original = (manager as any).findAvailablePort.bind(manager);
75
+ let firstDraw = true;
76
+ const spy = vi.spyOn(manager as any, 'findAvailablePort').mockImplementation(async () => {
77
+ if (firstDraw) {
78
+ firstDraw = false;
79
+ return taken;
80
+ }
81
+ return original();
82
+ });
83
+
84
+ const container = await manager.createContainer({
85
+ name: probeName,
86
+ image: 'redis:7-alpine',
87
+ ports: { 6379: 'auto' },
88
+ });
89
+
90
+ // Before the retry this threw "port is already allocated" and the whole
91
+ // suite failed for a reason that had nothing to do with it.
92
+ expect(container).toBeDefined();
93
+ const published = docker('port', probeName, '6379/tcp');
94
+ expect(published).not.toContain(`:${taken}`);
95
+ expect(spy.mock.calls.length).toBeGreaterThan(1);
96
+ }, DOCKER_BUDGET_MS);
97
+ });
@@ -0,0 +1,122 @@
1
+ /**
2
+ * Cleanup must remove this manager's containers and nothing else.
3
+ *
4
+ * DockerTestManager used to select what to remove with
5
+ * `--filter label=test.cleanup=true`, a label every test container on the
6
+ * machine carries. Under `vitest --pool=forks` each worker builds its own
7
+ * manager, so whichever worker finished first deleted the containers the other
8
+ * workers were still using. The symptom was unhelpfully calm: Redis exits 0 on
9
+ * SIGTERM, so the victim saw "container exited with exit code 0" and read like
10
+ * a flaky test rather than a killed dependency.
11
+ *
12
+ * Every cleanup filter is now scoped by a per-manager `test.manager` label.
13
+ * That is six separate filters, and reverting any one of them restores the
14
+ * old behaviour silently — so this test stands in for the other workers by
15
+ * creating a container labelled as belonging to a different manager, and
16
+ * requires it to survive.
17
+ */
18
+
19
+ import { describe, it, expect, afterAll } from 'vitest';
20
+ import { execFileSync } from 'node:child_process';
21
+
22
+ import { DockerTestManager } from './docker-test-manager.js';
23
+
24
+ /**
25
+ * What a test that starts a real container may take: docker's time, not the
26
+ * behaviour's. Measured 2026-09-25 at a load of ~50 on 16 cores with the host
27
+ * volume nearly full: two runs of three exceeded 120 s starting and removing
28
+ * a `redis:7-alpine`, every inner wait inside its own 30 s. These tests say
29
+ * what docker does — waits, leaves another worker's containers, re-draws a
30
+ * port — never how fast.
31
+ */
32
+ const DOCKER_BUDGET_MS = 300_000;
33
+
34
+ function docker(...args: string[]): string {
35
+ return execFileSync('docker', args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
36
+ }
37
+
38
+ function dockerAvailable(): boolean {
39
+ try {
40
+ docker('version', '--format', '{{.Server.Version}}');
41
+ return true;
42
+ } catch {
43
+ return false;
44
+ }
45
+ }
46
+
47
+ const describeOrSkip = dockerAvailable() ? describe : describe.skip;
48
+ if (!dockerAvailable()) {
49
+ console.log('⏭️ Skipping docker-test-manager.spec.ts - requires Docker');
50
+ }
51
+
52
+ describeOrSkip('DockerTestManager cleanup scope', () => {
53
+ const foreignName = `foreign-worker-probe-${process.pid}`;
54
+
55
+ afterAll(() => {
56
+ try {
57
+ docker('rm', '-f', foreignName);
58
+ } catch {
59
+ // already gone
60
+ }
61
+ });
62
+
63
+ it('can wait for a container that has no healthcheck', async () => {
64
+ // `waitFor.healthcheck: false` means "wait until it is running". It could
65
+ // not work: the inspect template asked for `.State.Health.Status`, Go
66
+ // templates fail on a missing key, and the swallowed error left every
67
+ // healthcheck-less container reported as not running. The rejection named
68
+ // an exit code that did not exist — "Container exited with status
69
+ // 'undefined' and exit code undefined" — for a container that was up.
70
+ const manager = DockerTestManager.getInstance();
71
+
72
+ const container = await manager.createContainer({
73
+ name: `no-healthcheck-probe-${process.pid}`,
74
+ image: 'redis:7-alpine',
75
+ ports: { 6379: 'auto' },
76
+ waitFor: { healthcheck: false, timeout: 30_000 },
77
+ });
78
+
79
+ expect(docker('inspect', '-f', '{{.State.Running}}', container.name)).toBe('true');
80
+
81
+ await manager.cleanupAll();
82
+ }, DOCKER_BUDGET_MS);
83
+
84
+ it('leaves another manager\'s containers alone when the process exits', async () => {
85
+ // The damage was done by the `process.on('exit')` handler, which runs
86
+ // `cleanupSync` — the only path that selects by label rather than by this
87
+ // manager's own registry. `cleanupAll()` iterates `this.containers` and was
88
+ // never the problem, so a test driving it would pass with the bug present.
89
+ // Called directly here because a real process exit cannot be observed from
90
+ // inside the process that is exiting.
91
+ try {
92
+ docker('rm', '-f', foreignName);
93
+ } catch {
94
+ // not there yet
95
+ }
96
+ docker(
97
+ 'run', '-d', '--name', foreignName,
98
+ '--label', 'test.cleanup=true',
99
+ '--label', 'test.manager=some-other-worker',
100
+ 'redis:7-alpine'
101
+ );
102
+
103
+ const manager = DockerTestManager.getInstance();
104
+ const own = await manager.createContainer({
105
+ name: `own-worker-probe-${process.pid}`,
106
+ image: 'redis:7-alpine',
107
+ ports: { 6379: 'auto' },
108
+ waitFor: { healthcheck: false, timeout: 30_000 },
109
+ });
110
+
111
+ expect(docker('ps', '-a', '--filter', `name=${own.name}`, '-q')).not.toBe('');
112
+
113
+ (manager as unknown as { cleanupSync(): void }).cleanupSync();
114
+
115
+ // Ours is gone...
116
+ expect(docker('ps', '-a', '--filter', `name=${own.name}`, '-q')).toBe('');
117
+
118
+ // ...and the other worker's is untouched and still running.
119
+ expect(docker('ps', '--filter', `name=${foreignName}`, '-q')).not.toBe('');
120
+ expect(docker('inspect', '-f', '{{.State.Running}}', foreignName)).toBe('true');
121
+ }, DOCKER_BUDGET_MS);
122
+ });