@omnitron-dev/testing 0.4.5 → 0.4.8

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 (116) hide show
  1. package/README.md +36 -0
  2. package/dist/async/events.js.map +1 -1
  3. package/dist/async/retry.js.map +1 -1
  4. package/dist/async/wait.js.map +1 -1
  5. package/dist/docker/database-manager.js +13 -15
  6. package/dist/docker/database-manager.js.map +1 -1
  7. package/dist/docker/docker-test-manager.d.ts +12 -3
  8. package/dist/docker/docker-test-manager.js +286 -255
  9. package/dist/docker/docker-test-manager.js.map +1 -1
  10. package/dist/docker/redis-manager.js +68 -94
  11. package/dist/docker/redis-manager.js.map +1 -1
  12. package/dist/docker/types.d.ts +7 -2
  13. package/dist/env.d.ts +11 -0
  14. package/dist/env.js +21 -0
  15. package/dist/env.js.map +1 -0
  16. package/dist/errors.js.map +1 -1
  17. package/dist/helpers/assertions.js +3 -3
  18. package/dist/helpers/assertions.js.map +1 -1
  19. package/dist/index.d.ts +1 -1
  20. package/dist/runtime/bun-adapter.d.ts +23 -1
  21. package/dist/runtime/bun-adapter.js +14 -1
  22. package/dist/runtime/bun-adapter.js.map +1 -1
  23. package/dist/runtime/deno-adapter.d.ts +72 -15
  24. package/dist/runtime/deno-adapter.js +93 -78
  25. package/dist/runtime/deno-adapter.js.map +1 -1
  26. package/dist/runtime/node-adapter.d.ts +15 -3
  27. package/dist/runtime/node-adapter.js +1 -1
  28. package/dist/runtime/node-adapter.js.map +1 -1
  29. package/dist/runtime/test-adapter.d.ts +1 -1
  30. package/dist/runtime/test-adapter.js +12 -14
  31. package/dist/runtime/test-adapter.js.map +1 -1
  32. package/dist/titan/database/database-testing.module.d.ts +7 -6
  33. package/dist/titan/database/database-testing.module.js +39 -18
  34. package/dist/titan/database/database-testing.module.js.map +1 -1
  35. package/dist/titan/database/index.d.ts +1 -1
  36. package/dist/titan/database/index.js +1 -1
  37. package/dist/titan/database/index.js.map +1 -1
  38. package/dist/titan/database/test-utilities.d.ts +2 -2
  39. package/dist/titan/database/test-utilities.js +3 -2
  40. package/dist/titan/database/test-utilities.js.map +1 -1
  41. package/dist/titan/index.d.ts +4 -4
  42. package/dist/titan/index.js +3 -3
  43. package/dist/titan/index.js.map +1 -1
  44. package/dist/titan/nexus/mock-provider.js +6 -6
  45. package/dist/titan/nexus/mock-provider.js.map +1 -1
  46. package/dist/titan/nexus/test-container.js +10 -10
  47. package/dist/titan/nexus/test-container.js.map +1 -1
  48. package/dist/titan/nexus/test-utilities.js +9 -9
  49. package/dist/titan/nexus/test-utilities.js.map +1 -1
  50. package/dist/titan/pm/mock-process-spawner.d.ts +4 -3
  51. package/dist/titan/pm/mock-process-spawner.js +33 -14
  52. package/dist/titan/pm/mock-process-spawner.js.map +1 -1
  53. package/dist/titan/pm/mock-spawner.d.ts +2 -1
  54. package/dist/titan/pm/mock-spawner.js +3 -1
  55. package/dist/titan/pm/mock-spawner.js.map +1 -1
  56. package/dist/titan/pm/test-process-manager.d.ts +4 -4
  57. package/dist/titan/pm/test-process-manager.js +7 -3
  58. package/dist/titan/pm/test-process-manager.js.map +1 -1
  59. package/dist/titan/redis-test-utils.d.ts +8 -2
  60. package/dist/titan/redis-test-utils.js +147 -92
  61. package/dist/titan/redis-test-utils.js.map +1 -1
  62. package/dist/titan/test-application.d.ts +1 -1
  63. package/dist/titan/test-application.js +1 -1
  64. package/dist/titan/test-application.js.map +1 -1
  65. package/dist/titan/test-fixtures.js.map +1 -1
  66. package/dist/titan/test-mocks.d.ts +12 -11
  67. package/dist/titan/test-mocks.js +49 -49
  68. package/dist/titan/test-mocks.js.map +1 -1
  69. package/dist/titan/test-module.js.map +1 -1
  70. package/package.json +66 -40
  71. package/src/async/README.md +18 -328
  72. package/src/async/events.ts +1 -1
  73. package/src/docker/a-port-the-network-could-reach.spec.ts +66 -0
  74. package/src/docker/database-manager.ts +13 -15
  75. package/src/docker/docker-orphan-reaper.spec.ts +175 -0
  76. package/src/docker/docker-port-collision.spec.ts +97 -0
  77. package/src/docker/docker-test-manager.spec.ts +122 -0
  78. package/src/docker/docker-test-manager.ts +420 -326
  79. package/src/docker/docker-volume-cleanup.spec.ts +113 -0
  80. package/src/docker/redis-cluster-creation.spec.ts +52 -0
  81. package/src/docker/redis-manager.ts +80 -115
  82. package/src/docker/types.ts +11 -4
  83. package/src/env.spec.ts +20 -0
  84. package/src/env.ts +33 -0
  85. package/src/globals.d.ts +2 -2
  86. package/src/helpers/assertions.ts +3 -3
  87. package/src/index.ts +1 -1
  88. package/src/runtime/adapter-surface.spec.ts +83 -0
  89. package/src/runtime/bun-adapter.ts +36 -5
  90. package/src/runtime/deno-adapter.ts +167 -108
  91. package/src/runtime/node-adapter.ts +5 -5
  92. package/src/runtime/test-adapter.test.ts +1 -1
  93. package/src/runtime/test-adapter.ts +15 -17
  94. package/src/titan/database/database-testing.module.ts +63 -22
  95. package/src/titan/database/index.ts +2 -2
  96. package/src/titan/database/test-utilities.ts +6 -3
  97. package/src/titan/index.ts +8 -1
  98. package/src/titan/nexus/mock-provider.ts +12 -12
  99. package/src/titan/nexus/test-container.ts +12 -12
  100. package/src/titan/nexus/test-utilities.ts +13 -11
  101. package/src/titan/pm/mock-process-spawner.ts +74 -26
  102. package/src/titan/pm/mock-spawner.ts +10 -4
  103. package/src/titan/pm/test-process-manager.ts +26 -9
  104. package/src/titan/redis-test-utils.test.ts +102 -0
  105. package/src/titan/redis-test-utils.ts +191 -109
  106. package/src/titan/test-application.ts +2 -2
  107. package/src/titan/test-fixtures.ts +0 -1
  108. package/src/titan/test-mocks.ts +50 -50
  109. package/runtime/bun.d.ts +0 -2
  110. package/runtime/bun.js +0 -5
  111. package/runtime/bun.ts +0 -7
  112. package/runtime/deno.d.ts +0 -2
  113. package/runtime/deno.js +0 -4
  114. package/runtime/jest.d.ts +0 -2
  115. package/runtime/jest.js +0 -16
  116. package/runtime/jest.ts +0 -7
@@ -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
+ });