@omnitron-dev/testing 0.4.4 → 0.4.6

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 (122) hide show
  1. package/README.md +43 -0
  2. package/dist/async/events.js.map +1 -1
  3. package/dist/async/index.d.ts +5 -5
  4. package/dist/async/index.js +5 -5
  5. package/dist/async/index.js.map +1 -1
  6. package/dist/async/retry.js.map +1 -1
  7. package/dist/async/wait.js.map +1 -1
  8. package/dist/docker/database-manager.js +13 -15
  9. package/dist/docker/database-manager.js.map +1 -1
  10. package/dist/docker/docker-test-manager.d.ts +12 -3
  11. package/dist/docker/docker-test-manager.js +286 -255
  12. package/dist/docker/docker-test-manager.js.map +1 -1
  13. package/dist/docker/redis-manager.js +70 -95
  14. package/dist/docker/redis-manager.js.map +1 -1
  15. package/dist/docker/types.d.ts +7 -2
  16. package/dist/env.d.ts +11 -0
  17. package/dist/env.js +21 -0
  18. package/dist/env.js.map +1 -0
  19. package/dist/errors.js.map +1 -1
  20. package/dist/helpers/assertions.js +3 -3
  21. package/dist/helpers/assertions.js.map +1 -1
  22. package/dist/index.d.ts +1 -1
  23. package/dist/runtime/bun-adapter.d.ts +23 -1
  24. package/dist/runtime/bun-adapter.js +14 -1
  25. package/dist/runtime/bun-adapter.js.map +1 -1
  26. package/dist/runtime/deno-adapter.d.ts +72 -15
  27. package/dist/runtime/deno-adapter.js +93 -78
  28. package/dist/runtime/deno-adapter.js.map +1 -1
  29. package/dist/runtime/node-adapter.d.ts +15 -3
  30. package/dist/runtime/node-adapter.js +1 -1
  31. package/dist/runtime/node-adapter.js.map +1 -1
  32. package/dist/runtime/test-adapter.d.ts +1 -1
  33. package/dist/runtime/test-adapter.js +12 -14
  34. package/dist/runtime/test-adapter.js.map +1 -1
  35. package/dist/titan/database/database-testing.module.d.ts +7 -6
  36. package/dist/titan/database/database-testing.module.js +40 -26
  37. package/dist/titan/database/database-testing.module.js.map +1 -1
  38. package/dist/titan/database/index.d.ts +1 -1
  39. package/dist/titan/database/index.js +1 -1
  40. package/dist/titan/database/index.js.map +1 -1
  41. package/dist/titan/database/test-utilities.d.ts +2 -2
  42. package/dist/titan/database/test-utilities.js +3 -2
  43. package/dist/titan/database/test-utilities.js.map +1 -1
  44. package/dist/titan/index.d.ts +9 -9
  45. package/dist/titan/index.js +6 -6
  46. package/dist/titan/index.js.map +1 -1
  47. package/dist/titan/nexus/mock-provider.js +6 -6
  48. package/dist/titan/nexus/mock-provider.js.map +1 -1
  49. package/dist/titan/nexus/test-container.js +10 -10
  50. package/dist/titan/nexus/test-container.js.map +1 -1
  51. package/dist/titan/nexus/test-utilities.js +9 -9
  52. package/dist/titan/nexus/test-utilities.js.map +1 -1
  53. package/dist/titan/pm/mock-process-spawner.d.ts +4 -3
  54. package/dist/titan/pm/mock-process-spawner.js +37 -15
  55. package/dist/titan/pm/mock-process-spawner.js.map +1 -1
  56. package/dist/titan/pm/mock-spawner.d.ts +2 -1
  57. package/dist/titan/pm/mock-spawner.js +3 -1
  58. package/dist/titan/pm/mock-spawner.js.map +1 -1
  59. package/dist/titan/pm/test-process-manager.d.ts +4 -4
  60. package/dist/titan/pm/test-process-manager.js +7 -3
  61. package/dist/titan/pm/test-process-manager.js.map +1 -1
  62. package/dist/titan/redis-test-utils.d.ts +8 -2
  63. package/dist/titan/redis-test-utils.js +147 -92
  64. package/dist/titan/redis-test-utils.js.map +1 -1
  65. package/dist/titan/test-application.d.ts +1 -1
  66. package/dist/titan/test-application.js +1 -1
  67. package/dist/titan/test-application.js.map +1 -1
  68. package/dist/titan/test-fixtures.js.map +1 -1
  69. package/dist/titan/test-mocks.d.ts +12 -11
  70. package/dist/titan/test-mocks.js +49 -49
  71. package/dist/titan/test-mocks.js.map +1 -1
  72. package/dist/titan/test-module.js.map +1 -1
  73. package/package.json +66 -40
  74. package/src/async/events.ts +1 -1
  75. package/src/async/index.ts +5 -30
  76. package/src/async/retry.ts +1 -4
  77. package/src/async/wait.ts +1 -4
  78. package/src/docker/a-port-the-network-could-reach.spec.ts +66 -0
  79. package/src/docker/database-manager.ts +13 -15
  80. package/src/docker/docker-orphan-reaper.spec.ts +175 -0
  81. package/src/docker/docker-port-collision.spec.ts +97 -0
  82. package/src/docker/docker-test-manager.spec.ts +122 -0
  83. package/src/docker/docker-test-manager.ts +421 -327
  84. package/src/docker/docker-volume-cleanup.spec.ts +113 -0
  85. package/src/docker/redis-cluster-creation.spec.ts +52 -0
  86. package/src/docker/redis-manager.ts +87 -117
  87. package/src/docker/types.ts +11 -4
  88. package/src/env.spec.ts +20 -0
  89. package/src/env.ts +33 -0
  90. package/src/errors.ts +9 -2
  91. package/src/globals.d.ts +2 -2
  92. package/src/helpers/assertions.ts +4 -7
  93. package/src/index.ts +1 -1
  94. package/src/runtime/adapter-surface.spec.ts +83 -0
  95. package/src/runtime/bun-adapter.ts +36 -5
  96. package/src/runtime/deno-adapter.ts +167 -108
  97. package/src/runtime/node-adapter.ts +5 -5
  98. package/src/runtime/test-adapter.test.ts +1 -1
  99. package/src/runtime/test-adapter.ts +15 -17
  100. package/src/titan/database/database-testing.module.ts +73 -53
  101. package/src/titan/database/index.ts +2 -2
  102. package/src/titan/database/test-utilities.ts +6 -3
  103. package/src/titan/index.ts +13 -27
  104. package/src/titan/nexus/mock-provider.ts +12 -12
  105. package/src/titan/nexus/test-container.ts +25 -17
  106. package/src/titan/nexus/test-utilities.ts +13 -11
  107. package/src/titan/pm/mock-process-spawner.ts +80 -27
  108. package/src/titan/pm/mock-spawner.ts +10 -4
  109. package/src/titan/pm/test-process-manager.ts +26 -9
  110. package/src/titan/redis-test-utils.test.ts +102 -0
  111. package/src/titan/redis-test-utils.ts +191 -109
  112. package/src/titan/test-application.ts +2 -2
  113. package/src/titan/test-fixtures.ts +0 -1
  114. package/src/titan/test-mocks.ts +50 -50
  115. package/runtime/bun.d.ts +0 -2
  116. package/runtime/bun.js +0 -5
  117. package/runtime/bun.ts +0 -7
  118. package/runtime/deno.d.ts +0 -2
  119. package/runtime/deno.js +0 -4
  120. package/runtime/jest.d.ts +0 -2
  121. package/runtime/jest.js +0 -16
  122. package/runtime/jest.ts +0 -7
@@ -0,0 +1,113 @@
1
+ /**
2
+ * Removing a test container must remove the anonymous volumes it created.
3
+ *
4
+ * Every `docker rm` here was `rm -f <name>` with no `-v`. The database and
5
+ * cache images this manager starts all declare `VOLUME` in their Dockerfiles —
6
+ * postgres `/var/lib/postgresql/data`, mysql `/var/lib/mysql`, redis `/data` —
7
+ * so each container came with an anonymous volume, and `rm` without `-v` leaves
8
+ * it behind with nothing pointing at it. One per container, forever.
9
+ *
10
+ * Measured on this machine before the fix: 4940 dangling volumes out of 5012,
11
+ * 188 GB in `Local Volumes` with 72 in use. A leak that fired sometimes would
12
+ * leave an intermediate ratio; 98.6% is a missing flag. It filled the Docker
13
+ * VM's disk and took the user's Postgres down with it.
14
+ *
15
+ * `-v` removes only the container's own ANONYMOUS volumes. Named volumes are
16
+ * untouched, which is why this is safe to do unconditionally: it removes
17
+ * exactly what the container created.
18
+ */
19
+ import { describe, it, expect, vi, beforeEach } from 'vitest';
20
+
21
+ const execFileSyncMock = vi.fn(() => '');
22
+
23
+ vi.mock('node:child_process', async (importOriginal) => {
24
+ const actual = await importOriginal<typeof import('node:child_process')>();
25
+ return { ...actual, execFileSync: (...args: unknown[]) => execFileSyncMock(...args),
26
+ execFile: (...args: unknown[]) => {
27
+ const callback = args.pop() as (error: unknown, stdout: string, stderr: string) => void;
28
+ queueMicrotask(() => {
29
+ try { callback(null, execFileSyncMock(...args), ''); }
30
+ catch (error) {
31
+ const failure = error as { status?: number; stdout?: string; stderr?: string };
32
+ callback({ code: failure.status ?? 1 }, failure.stdout ?? '', failure.stderr ?? '');
33
+ }
34
+ });
35
+ },
36
+ };
37
+ });
38
+
39
+ const { DockerTestManager } = await import('./docker-test-manager.js');
40
+
41
+ describe('DockerTestManager container removal', () => {
42
+ beforeEach(() => {
43
+ execFileSyncMock.mockReset();
44
+ execFileSyncMock.mockReturnValue('');
45
+ });
46
+
47
+ it('removes anonymous volumes using the immutable ID returned by Docker', async () => {
48
+ const dockerId = 'a'.repeat(64);
49
+ execFileSyncMock.mockImplementation((_exe, args) => args[0] === 'run' ? dockerId : '');
50
+ const manager = DockerTestManager.getInstance({ dockerPath: 'docker', cleanup: false });
51
+ const container = await manager.createContainer({ name: 'volume-flag-probe', image: 'redis:7-alpine' });
52
+ await container.cleanup();
53
+ const removals = execFileSyncMock.mock.calls.map(call => call[1]).filter(args => args[0] === 'rm');
54
+ expect(removals).toEqual([['rm', '-f', '-v', dockerId]]);
55
+ });
56
+
57
+ it('leaves existing containers and networks owned by another caller alone', async () => {
58
+ const collision = Object.assign(new Error('fixture'), { status: 125, stderr: 'The container name "/foreign" is already in use' });
59
+ execFileSyncMock.mockImplementation((_exe, args) => {
60
+ if (args[0] === 'network' && args[1] === 'create') throw Object.assign(new Error('fixture'), { stderr: 'network already exists' });
61
+ if (args[0] === 'run') throw collision;
62
+ return '';
63
+ });
64
+ const manager = DockerTestManager.getInstance({ dockerPath: 'docker', cleanup: false });
65
+ await expect(manager.createContainer({ name: 'foreign', image: 'redis:7-alpine', networks: ['shared'] })).rejects.toThrow('name conflict');
66
+ await manager.cleanupAll();
67
+ expect(execFileSyncMock.mock.calls.map(call => call[1]).filter(args => args.includes('rm') || args.includes('stop'))).toEqual([]);
68
+ });
69
+
70
+ it.skipIf(process.platform === 'win32')('keeps CMD input literal and reserves owner labels', async () => {
71
+ const id = 'b'.repeat(64);
72
+ let run: string[] = [];
73
+ execFileSyncMock.mockImplementation((_exe, args) => {
74
+ if (args[0] === 'run') { run = args; return id; }
75
+ return '';
76
+ });
77
+ const manager = DockerTestManager.getInstance({ dockerPath: 'docker', cleanup: false });
78
+ const literal = "a' b; $(echo INJECTED)";
79
+ const container = await manager.createContainer({ image: 'fixture', labels: { 'test.id': 'foreign' },
80
+ healthcheck: { test: ['CMD', 'printf', '%s', literal] } });
81
+ expect(container.labels['test.id']).toBe(container.id);
82
+ const command = run[run.indexOf('--health-cmd') + 1];
83
+ const { execFileSync } = await vi.importActual<typeof import('node:child_process')>('node:child_process');
84
+ expect(execFileSync('/bin/sh', ['-c', command], { encoding: 'utf8' })).toBe(literal);
85
+ await container.cleanup();
86
+ });
87
+
88
+ it('passes command argv without losing empty arguments or evaluating shell syntax', async () => {
89
+ const id = 'c'.repeat(64);
90
+ let run: string[] = [];
91
+ execFileSyncMock.mockImplementation((_exe, args) => {
92
+ if (args[0] === 'run') { run = args; return id; }
93
+ return '';
94
+ });
95
+ const manager = DockerTestManager.getInstance({ dockerPath: 'docker', cleanup: false });
96
+ const command = ['redis-server', '--save', '', '--requirepass', "a' b; $(echo INJECTED)"];
97
+ const container = await manager.createContainer({ image: 'fixture', command });
98
+ expect(run.slice(run.indexOf('fixture') + 1)).toEqual(command);
99
+ await container.cleanup();
100
+ });
101
+
102
+ it('never passes -v to a network removal', () => {
103
+ // `docker network rm` has no such flag; the blanket edit must not have
104
+ // reached it.
105
+ const source = readFileSync(
106
+ new URL('./docker-test-manager.ts', import.meta.url),
107
+ 'utf-8'
108
+ );
109
+ expect(source).not.toMatch(/\['network', 'rm', '-v'/);
110
+ });
111
+ });
112
+
113
+ import { readFileSync } from 'node:fs';
@@ -0,0 +1,52 @@
1
+ import { afterEach, expect, it, vi } from 'vitest';
2
+ import { RedisTestManager } from './redis-manager.js';
3
+
4
+ const original = Reflect.get(RedisTestManager, '_dockerManager');
5
+ afterEach(() => Reflect.set(RedisTestManager, '_dockerManager', original));
6
+
7
+ it('drains delayed container creation and cleans every returned peer before its network', async () => {
8
+ const failure = Error('first node refused');
9
+ const events: string[] = [];
10
+ let release!: () => void;
11
+ const delayed = new Promise<void>(resolve => { release = resolve; });
12
+ const manager = {
13
+ usedPorts: new Set<number>(),
14
+ ensureNetwork: vi.fn(async () => {}),
15
+ findAvailablePort: vi.fn(async () => 24000 + manager.findAvailablePort.mock.calls.length),
16
+ createContainer: vi.fn(async (options) => {
17
+ const number = manager.createContainer.mock.calls.length;
18
+ if (number === 1) throw failure;
19
+ if (number === 6) await delayed;
20
+ events.push('created-' + number);
21
+ return { name: options.name, host: '127.0.0.1', ports: new Map([[6379, options.ports[6379]]]),
22
+ cleanup: vi.fn(async () => { events.push('removed-' + number); }) };
23
+ }),
24
+ removeNetwork: vi.fn(async () => { events.push('network-removed'); }),
25
+ };
26
+ Reflect.set(RedisTestManager, '_dockerManager', manager);
27
+ const result = RedisTestManager.createRedisCluster().catch(error => error);
28
+ await vi.waitFor(() => expect(manager.createContainer).toHaveBeenCalledTimes(6));
29
+ expect(manager.removeNetwork).not.toHaveBeenCalled();
30
+ expect(events.every(event => event.startsWith('created-'))).toBe(true);
31
+ release();
32
+ const error = await result;
33
+ expect(error).toBeInstanceOf(AggregateError);
34
+ expect(error.errors).toEqual([failure]);
35
+ expect(events.slice(-6)).toEqual(['removed-2', 'removed-3', 'removed-4', 'removed-5', 'removed-6', 'network-removed']);
36
+ for (const [options] of manager.createContainer.mock.calls) {
37
+ expect(options.command.slice(options.command.indexOf('--save'), options.command.indexOf('--save') + 2)).toEqual(['--save', '']);
38
+ }
39
+ });
40
+
41
+ it('keeps startup and cleanup failures visible together', async () => {
42
+ const startup = Error('node refused'), cleanup = Error('network still owned');
43
+ Reflect.set(RedisTestManager, '_dockerManager', {
44
+ usedPorts: new Set(), ensureNetwork: vi.fn(async () => {}), findAvailablePort: vi.fn(async () => 24001),
45
+ createContainer: vi.fn(async () => { throw startup; }),
46
+ removeNetwork: vi.fn(async () => { throw cleanup; }),
47
+ });
48
+ const error = await RedisTestManager.createRedisCluster({ masterCount: 1, replicasPerMaster: 0 }).catch(error => error);
49
+ expect(error).toBeInstanceOf(AggregateError);
50
+ expect(error.errors[0].errors).toEqual([startup]);
51
+ expect(error.errors[1].errors).toEqual([cleanup]);
52
+ });
@@ -75,7 +75,7 @@ export class RedisTestManager {
75
75
  static async createRedisContainer(options?: RedisContainerOptions): Promise<DockerContainer> {
76
76
  const port = options?.port || 'auto';
77
77
  const password = options?.password;
78
- const database = options?.database ?? 0;
78
+ const _database = options?.database ?? 0;
79
79
  const maxMemory = options?.maxMemory || '256mb';
80
80
  const requirePass = options?.requirePass ?? Boolean(password);
81
81
 
@@ -97,12 +97,12 @@ export class RedisTestManager {
97
97
  image: 'redis:7-alpine',
98
98
  ports: { 6379: port },
99
99
  environment,
100
- command: command.join(' '),
100
+ command,
101
101
  healthcheck: {
102
102
  test: password ? ['CMD', 'redis-cli', '-a', password, 'ping'] : ['CMD', 'redis-cli', 'ping'],
103
103
  interval: '1s',
104
104
  timeout: '3s',
105
- retries: 5,
105
+ retries: 20,
106
106
  startPeriod: '2s',
107
107
  },
108
108
  waitFor: {
@@ -140,24 +140,39 @@ export class RedisTestManager {
140
140
  const networkName = options?.network || `redis-cluster-${randomBytes(8).toString('hex')}`;
141
141
 
142
142
  // Create network
143
- await RedisTestManager.getDockerManager()['ensureNetwork'](networkName);
143
+ await RedisTestManager.getDockerManager().ensureNetwork(networkName);
144
144
 
145
145
  const masters: DockerContainer[] = [];
146
146
  const replicas: DockerContainer[] = [];
147
147
  const nodes: Array<{ host: string; port: number }> = [];
148
148
  const allocatedPorts: number[] = [];
149
149
 
150
+ const cleanup = async () => {
151
+ const settled = await Promise.allSettled([...masters, ...replicas].map(container => container.cleanup()));
152
+ const errors = settled.filter(result => result.status === 'rejected').map(result => result.reason);
153
+ try { await RedisTestManager.getDockerManager().removeNetwork(networkName); }
154
+ catch (error) { errors.push(error); }
155
+ if (errors.length) throw new AggregateError(errors, 'Redis cluster cleanup was not confirmed');
156
+ };
157
+
150
158
  // Extract unique ID from network name to ensure container names are unique
151
159
  const networkId = networkName.split('-').pop() || randomBytes(4).toString('hex');
152
160
 
153
161
  try {
154
- // Create master nodes with dynamically allocated ports
155
- for (let i = 0; i < masterCount; i++) {
156
- // Use dynamic port allocation instead of fixed basePort to avoid conflicts
157
- const port = await RedisTestManager.getDockerManager()['findAvailablePort']();
158
- allocatedPorts.push(port);
159
- const name = `redis-cluster-${networkId}-master-${i}`;
160
-
162
+ // Containers are created in PARALLEL.
163
+ //
164
+ // They were created one at a time, each waiting on a healthcheck whose
165
+ // startPeriod is 10s, so a 3-master/3-replica cluster could not finish
166
+ // in under sixty seconds of start periods alone — and the tests that
167
+ // call this allow exactly sixty. They did not fail because the machine
168
+ // was slow; they could not pass as written. Nothing orders these
169
+ // containers against each other: the cluster is formed afterwards, by
170
+ // `redis-cli --cluster create`, once they are all up.
171
+ //
172
+ // Ports are still allocated one at a time, before any container starts:
173
+ // findAvailablePort() binds, reads the port and releases, so two
174
+ // concurrent calls can be handed the same one.
175
+ const spec = (kind: 'master' | 'replica', index: number, port: number) => {
161
176
  const command = [
162
177
  'redis-server',
163
178
  '--cluster-enabled',
@@ -179,79 +194,61 @@ export class RedisTestManager {
179
194
  command.push('--masterauth', password);
180
195
  }
181
196
 
182
- const container = await RedisTestManager.getDockerManager().createContainer({
183
- name,
197
+ return {
198
+ name: `redis-cluster-${networkId}-${kind}-${index}`,
184
199
  image: 'redis:7-alpine',
185
200
  ports: { 6379: port },
186
201
  networks: [networkName],
187
- command: command.join(' '),
202
+ command,
188
203
  healthcheck: {
189
- test: password ? ['CMD', 'redis-cli', '-a', password, 'ping'] : ['CMD', 'redis-cli', 'ping'],
204
+ test: password
205
+ ? (['CMD', 'redis-cli', '-a', password, 'ping'] as string[])
206
+ : (['CMD', 'redis-cli', 'ping'] as string[]),
190
207
  interval: '1s',
191
- timeout: '3s',
192
- retries: 5,
193
- startPeriod: '2s',
208
+ timeout: '5s',
209
+ retries: 30,
210
+ startPeriod: '10s',
194
211
  },
195
212
  waitFor: {
196
213
  healthcheck: true,
197
- timeout: 30000,
214
+ timeout: 60000,
198
215
  },
199
- });
216
+ };
217
+ };
200
218
 
201
- masters.push(container);
202
- nodes.push({ host: container.host, port });
219
+ const replicaCount = masterCount * replicasPerMaster;
220
+ const plan: Array<{ kind: 'master' | 'replica'; index: number; port: number }> = [];
221
+ for (let i = 0; i < masterCount; i++) {
222
+ const port = await RedisTestManager.getDockerManager()['findAvailablePort']();
223
+ allocatedPorts.push(port);
224
+ plan.push({ kind: 'master', index: i, port });
203
225
  }
204
-
205
- // Create replica nodes with dynamically allocated ports
206
- for (let i = 0; i < masterCount * replicasPerMaster; i++) {
207
- // Use dynamic port allocation
226
+ for (let i = 0; i < replicaCount; i++) {
208
227
  const port = await RedisTestManager.getDockerManager()['findAvailablePort']();
209
228
  allocatedPorts.push(port);
210
- const name = `redis-cluster-${networkId}-replica-${i}`;
211
-
212
- const command = [
213
- 'redis-server',
214
- '--cluster-enabled',
215
- 'yes',
216
- '--cluster-config-file',
217
- 'nodes.conf',
218
- '--cluster-node-timeout',
219
- '5000',
220
- '--appendonly',
221
- 'no',
222
- '--save',
223
- '',
224
- '--port',
225
- '6379',
226
- ];
227
-
228
- if (password) {
229
- command.push('--requirepass', password);
230
- command.push('--masterauth', password);
231
- }
229
+ plan.push({ kind: 'replica', index: i, port });
230
+ }
232
231
 
233
- const container = await RedisTestManager.getDockerManager().createContainer({
234
- name,
235
- image: 'redis:7-alpine',
236
- ports: { 6379: port },
237
- networks: [networkName],
238
- command: command.join(' '),
239
- healthcheck: {
240
- test: password ? ['CMD', 'redis-cli', '-a', password, 'ping'] : ['CMD', 'redis-cli', 'ping'],
241
- interval: '1s',
242
- timeout: '3s',
243
- retries: 5,
244
- startPeriod: '2s',
245
- },
246
- waitFor: {
247
- healthcheck: true,
248
- timeout: 30000,
249
- },
250
- });
232
+ // Drain every creation before cleanup: an early rejection must not lose
233
+ // ownership of peers that finish starting after that rejection.
234
+ const created = await Promise.allSettled(
235
+ plan.map(async ({ kind, index, port }) => ({
236
+ kind,
237
+ port,
238
+ container: await RedisTestManager.getDockerManager().createContainer(
239
+ spec(kind, index, port) as never
240
+ ),
241
+ }))
242
+ );
251
243
 
252
- replicas.push(container);
244
+ for (const result of created) {
245
+ if (result.status !== 'fulfilled') continue;
246
+ const { kind, port, container } = result.value;
247
+ (kind === 'master' ? masters : replicas).push(container);
253
248
  nodes.push({ host: container.host, port });
254
249
  }
250
+ const failures = created.filter(result => result.status === 'rejected').map(result => result.reason);
251
+ if (failures.length) throw new AggregateError(failures, 'Could not start every Redis cluster node');
255
252
 
256
253
  // Wait for all containers to be fully ready and connected to network
257
254
  const preInitDelay = options?.preInitDelay ?? 5000;
@@ -271,7 +268,9 @@ export class RedisTestManager {
271
268
  break;
272
269
  } catch {
273
270
  if (i === maxPingRetries - 1) {
274
- throw new Error(`Container ${container.name} not responding to redis-cli ping after ${maxPingRetries} attempts`);
271
+ throw new Error(
272
+ `Container ${container.name} not responding to redis-cli ping after ${maxPingRetries} attempts`
273
+ );
275
274
  }
276
275
  await new Promise((r) => setTimeout(r, 1000));
277
276
  }
@@ -300,44 +299,16 @@ export class RedisTestManager {
300
299
  network: networkName,
301
300
  nodes,
302
301
  natMap,
303
- cleanup: async () => {
304
- // Clean up containers first
305
- await Promise.allSettled([...masters.map((c) => c.cleanup()), ...replicas.map((c) => c.cleanup())]);
306
- // Then remove the network
307
- try {
308
- await RedisTestManager.getDockerManager()['removeNetwork'](networkName);
309
- } catch (error) {
310
- // Log but don't throw - network cleanup is best effort
311
- console.warn(`Failed to remove network ${networkName}:`, error);
312
- }
313
- },
302
+ cleanup,
314
303
  };
315
304
  } catch (error) {
316
- // Cleanup on failure - release allocated ports and clean up containers
305
+ // A container releases its own reservation only after confirmed cleanup.
306
+ const ownedPorts = new Set([...masters, ...replicas].flatMap(container => [...container.ports.values()]));
317
307
  allocatedPorts.forEach((port) => {
318
- RedisTestManager.getDockerManager()['usedPorts'].delete(port);
308
+ if (!ownedPorts.has(port)) RedisTestManager.getDockerManager()['usedPorts'].delete(port);
319
309
  });
320
- await Promise.allSettled([
321
- ...masters.map((c) =>
322
- c.cleanup().catch((cleanupError) => {
323
- // Log cleanup errors but don't fail the error flow - we're already handling a failure
324
- console.error(`Failed to cleanup master container ${c.name}:`, cleanupError);
325
- })
326
- ),
327
- ...replicas.map((c) =>
328
- c.cleanup().catch((cleanupError) => {
329
- // Log cleanup errors but don't fail the error flow - we're already handling a failure
330
- console.error(`Failed to cleanup replica container ${c.name}:`, cleanupError);
331
- })
332
- ),
333
- ]);
334
- // Try to remove network on failure too
335
- try {
336
- await RedisTestManager.getDockerManager()['removeNetwork'](networkName);
337
- } catch (networkError) {
338
- // Log network cleanup errors but don't fail - network might be in use or already removed
339
- console.error(`Failed to remove network ${networkName} during failure cleanup:`, networkError);
340
- }
310
+ try { await cleanup(); }
311
+ catch (cleanupError) { throw new AggregateError([error, cleanupError], 'Redis cluster startup and cleanup failed', { cause: cleanupError }); }
341
312
  throw error;
342
313
  }
343
314
  }
@@ -373,7 +344,7 @@ export class RedisTestManager {
373
344
  const networkName = options?.network || `redis-sentinel-${randomBytes(8).toString('hex')}`;
374
345
 
375
346
  // Create network
376
- await RedisTestManager.getDockerManager()['ensureNetwork'](networkName);
347
+ await RedisTestManager.getDockerManager().ensureNetwork(networkName);
377
348
 
378
349
  let master: DockerContainer | undefined;
379
350
  const replicas: DockerContainer[] = [];
@@ -397,7 +368,7 @@ export class RedisTestManager {
397
368
  image: 'redis:7-alpine',
398
369
  ports: { 6379: masterPort },
399
370
  networks: [networkName],
400
- command: command.join(' '),
371
+ command,
401
372
  healthcheck: {
402
373
  test: password ? ['CMD', 'redis-cli', '-a', password, 'ping'] : ['CMD', 'redis-cli', 'ping'],
403
374
  interval: '1s',
@@ -425,7 +396,7 @@ export class RedisTestManager {
425
396
  image: 'redis:7-alpine',
426
397
  ports: { 6379: replicaPort },
427
398
  networks: [networkName],
428
- command: replicaCommand.join(' '),
399
+ command: replicaCommand,
429
400
  healthcheck: {
430
401
  test: password ? ['CMD', 'redis-cli', '-a', password, 'ping'] : ['CMD', 'redis-cli', 'ping'],
431
402
  interval: '1s',
@@ -459,18 +430,16 @@ export class RedisTestManager {
459
430
  sentinelConfig.push(`sentinel auth-pass ${masterName} ${password}`);
460
431
  }
461
432
 
462
- const sentinelCommand = [
463
- 'sh',
464
- '-c',
465
- `echo "${sentinelConfig.join('\\n')}" > /tmp/sentinel.conf && redis-sentinel /tmp/sentinel.conf`,
466
- ];
433
+ const sentinelCommand = ['sh', '-c',
434
+ 'printf "%s\\n" "$1" > /tmp/sentinel.conf && exec redis-sentinel /tmp/sentinel.conf',
435
+ 'sentinel-config', sentinelConfig.join('\n')];
467
436
 
468
437
  const sentinel = await RedisTestManager.getDockerManager().createContainer({
469
438
  name: `redis-sentinel-${i}`,
470
439
  image: 'redis:7-alpine',
471
440
  ports: { 26379: sentinelPort },
472
441
  networks: [networkName],
473
- command: sentinelCommand.join(' '),
442
+ command: sentinelCommand,
474
443
  healthcheck: {
475
444
  test: ['CMD', 'redis-cli', '-p', '26379', 'ping'],
476
445
  interval: '1s',
@@ -547,9 +516,7 @@ export class RedisTestManager {
547
516
  // Note: Use container names as hostnames (not 127.0.0.1) because cluster init runs inside a container
548
517
  // Docker network DNS resolves container names to their IPs, and Redis listens on port 6379 internally
549
518
  const allNodes = [...masters, ...replicas];
550
- const nodeAddresses = allNodes.map((c) => {
551
- return `${c.name}:6379`;
552
- });
519
+ const nodeAddresses = allNodes.map((c) => `${c.name}:6379`);
553
520
 
554
521
  const clusterArgs = [
555
522
  'redis-cli',
@@ -582,7 +549,7 @@ export class RedisTestManager {
582
549
 
583
550
  const output = execFileSync(dockerPath, ['exec', firstMaster.name, ...clusterArgs], {
584
551
  stdio: verbose ? 'inherit' : 'pipe',
585
- timeout: 30000,
552
+ timeout: 60000,
586
553
  encoding: 'utf8',
587
554
  });
588
555
 
@@ -605,7 +572,10 @@ export class RedisTestManager {
605
572
 
606
573
  if (clusterInfo.includes('cluster_state:ok')) {
607
574
  // Verify all slots are assigned
608
- if (clusterInfo.includes('cluster_slots_assigned:16384') && clusterInfo.includes('cluster_slots_ok:16384')) {
575
+ if (
576
+ clusterInfo.includes('cluster_slots_assigned:16384') &&
577
+ clusterInfo.includes('cluster_slots_ok:16384')
578
+ ) {
609
579
  clusterReady = true;
610
580
  if (verbose) {
611
581
  console.log('[RedisCluster] Cluster is ready');
@@ -629,7 +599,7 @@ export class RedisTestManager {
629
599
  }
630
600
  } catch (error) {
631
601
  const errorMsg = error instanceof Error ? error.message : String(error);
632
- throw new Error(`Failed to initialize Redis cluster: ${errorMsg}`);
602
+ throw new Error(`Failed to initialize Redis cluster: ${errorMsg}`, { cause: error });
633
603
  }
634
604
  }
635
605
 
@@ -63,7 +63,7 @@ export interface DockerTestManagerOptions {
63
63
  basePort?: number;
64
64
  /** Maximum retries for port allocation (default: 20) */
65
65
  maxRetries?: number;
66
- /** Timeout in ms for container startup (default: 30000) */
66
+ /** Timeout in ms for the Docker start command and readiness (default: 60000). */
67
67
  startupTimeout?: number;
68
68
  /** Whether to cleanup containers on exit (default: true) */
69
69
  cleanup?: boolean;
@@ -85,8 +85,8 @@ export interface ContainerOptions {
85
85
  name?: string;
86
86
  /** Docker image to use */
87
87
  image: string;
88
- /** Command to run in container */
89
- command?: string;
88
+ /** Literal argv, or an explicitly shell-interpreted command string. */
89
+ command?: string | string[];
90
90
  /** Port mappings: container port -> host port or 'auto' */
91
91
  ports?: Record<number, number | 'auto'>;
92
92
  /** Environment variables */
@@ -95,12 +95,18 @@ export interface ContainerOptions {
95
95
  labels?: Record<string, string>;
96
96
  /** Volume mounts (format: "host:container" or "volume:container") */
97
97
  volumes?: string[];
98
+ /** Docker enforces these limits from container creation, before the entrypoint starts. */
99
+ resources?: {
100
+ memoryBytes?: number;
101
+ cpus?: number;
102
+ pidsLimit?: number;
103
+ };
98
104
  /** Networks to connect to */
99
105
  networks?: string[];
100
106
  /** Health check configuration */
101
107
  healthcheck?: {
102
108
  /** Health check command (array format: ['CMD', 'arg1', ...] or ['CMD-SHELL', 'command']) */
103
- test: string[];
109
+ test: string | string[];
104
110
  /** Interval between checks (e.g., "1s") */
105
111
  interval?: string;
106
112
  /** Timeout for each check (e.g., "3s") */
@@ -154,6 +160,7 @@ export interface RedisClusterOptions {
154
160
  /** Network name (auto-generated if not provided) */
155
161
  network?: string;
156
162
  /** Timeout in ms for cluster to become ready (default: 120000) */
163
+ /** NOT IMPLEMENTED — read by nothing; readiness uses the manager's own wait loop. */
157
164
  readyTimeout?: number;
158
165
  /** Pre-initialization delay in ms after containers start (default: 5000) */
159
166
  preInitDelay?: number;
@@ -0,0 +1,20 @@
1
+ import { afterEach, expect, it, vi } from 'vitest';
2
+
3
+ afterEach(() => { vi.unstubAllEnvs(); vi.resetModules(); });
4
+
5
+ it('keeps an explicit PostgreSQL endpoint when selecting a test database', async () => {
6
+ const endpoint = 'postgresql://tester:encoded%40secret@127.0.0.1:25432/source?sslmode=require';
7
+ vi.stubEnv('TEST_POSTGRES_URL', endpoint);
8
+ vi.stubEnv('TEST_DATABASE_URL', 'postgresql://unused:unused@127.0.0.1:15432/unused');
9
+ const { TEST_POSTGRES_URL, testPostgresUrl } = await import('./env.js');
10
+ expect(TEST_POSTGRES_URL).toBe(endpoint);
11
+ expect(testPostgresUrl()).toBe(endpoint);
12
+ expect(testPostgresUrl('worker/2')).toBe('postgresql://tester:encoded%40secret@127.0.0.1:25432/worker%2F2?sslmode=require');
13
+ });
14
+
15
+ it('resolves the existing CI database variable in the shared environment', async () => {
16
+ vi.stubEnv('TEST_POSTGRES_URL', undefined);
17
+ vi.stubEnv('TEST_DATABASE_URL', 'postgresql://tester:secret@127.0.0.1:35432/ci');
18
+ const { TEST_POSTGRES_URL } = await import('./env.js');
19
+ expect(TEST_POSTGRES_URL).toBe('postgresql://tester:secret@127.0.0.1:35432/ci');
20
+ });
package/src/env.ts ADDED
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Shared test environment configuration.
3
+ *
4
+ * All test infrastructure ports default to docker-compose.test.yml values
5
+ * (non-standard ports to avoid collisions with local services).
6
+ * Override via environment variables.
7
+ */
8
+
9
+ export const TEST_REDIS_HOST = process.env['TEST_REDIS_HOST'] ?? 'localhost';
10
+ export const TEST_REDIS_PORT = Number(process.env['TEST_REDIS_PORT'] ?? 16379);
11
+ export const TEST_REDIS_URL = process.env['TEST_REDIS_URL'] ?? `redis://${TEST_REDIS_HOST}:${TEST_REDIS_PORT}`;
12
+
13
+ export const TEST_POSTGRES_HOST = process.env['TEST_POSTGRES_HOST'] ?? 'localhost';
14
+ export const TEST_POSTGRES_PORT = Number(process.env['TEST_POSTGRES_PORT'] ?? 15432);
15
+ export const TEST_POSTGRES_USER = process.env['TEST_POSTGRES_USER'] ?? 'test';
16
+ export const TEST_POSTGRES_PASSWORD = process.env['TEST_POSTGRES_PASSWORD'] ?? 'test';
17
+ export const TEST_POSTGRES_DB = process.env['TEST_POSTGRES_DB'] ?? 'test';
18
+ export const TEST_POSTGRES_URL =
19
+ process.env['TEST_POSTGRES_URL'] ?? process.env['TEST_DATABASE_URL'] ??
20
+ `postgresql://${TEST_POSTGRES_USER}:${TEST_POSTGRES_PASSWORD}@${TEST_POSTGRES_HOST}:${TEST_POSTGRES_PORT}/${TEST_POSTGRES_DB}`;
21
+
22
+ /** Build a Redis URL for a specific DB index */
23
+ export function testRedisUrl(db = 0): string {
24
+ return `${TEST_REDIS_URL}/${db}`;
25
+ }
26
+
27
+ /** Build a Postgres URL for a specific database name */
28
+ export function testPostgresUrl(database?: string): string {
29
+ if (database === undefined) return TEST_POSTGRES_URL;
30
+ const url = new URL(TEST_POSTGRES_URL);
31
+ url.pathname = '/' + encodeURIComponent(database);
32
+ return url.toString();
33
+ }
package/src/errors.ts CHANGED
@@ -3,7 +3,10 @@
3
3
  */
4
4
 
5
5
  export class TestingError extends Error {
6
- constructor(message: string, public code: string) {
6
+ constructor(
7
+ message: string,
8
+ public code: string
9
+ ) {
7
10
  super(message);
8
11
  this.name = 'TestingError';
9
12
  }
@@ -24,7 +27,11 @@ export class NotFoundError extends TestingError {
24
27
  }
25
28
 
26
29
  export class RetryError extends TestingError {
27
- constructor(message: string, public attempts: number, public lastError?: Error) {
30
+ constructor(
31
+ message: string,
32
+ public attempts: number,
33
+ public lastError?: Error
34
+ ) {
28
35
  super(message, 'RETRY_EXHAUSTED');
29
36
  this.name = 'RetryError';
30
37
  }
package/src/globals.d.ts CHANGED
@@ -9,8 +9,8 @@ declare global {
9
9
  // Deno global
10
10
  const Deno: any;
11
11
 
12
- // Jest globals (for Node.js)
13
- const jest: any;
12
+ // Vitest globals (for Node.js)
13
+ const vi: any;
14
14
  const describe: any;
15
15
  const it: any;
16
16
  const test: any;