@omnitron-dev/testing 0.4.1 → 0.4.3

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 (154) hide show
  1. package/dist/async/deferred.d.ts +15 -0
  2. package/dist/async/deferred.js +35 -0
  3. package/dist/async/deferred.js.map +1 -0
  4. package/dist/async/events.d.ts +32 -0
  5. package/dist/async/events.js +176 -0
  6. package/dist/async/events.js.map +1 -0
  7. package/dist/async/index.d.ts +5 -0
  8. package/dist/async/index.js +6 -0
  9. package/dist/async/index.js.map +1 -0
  10. package/dist/async/mock-timer.d.ts +19 -0
  11. package/dist/async/mock-timer.js +87 -0
  12. package/dist/async/mock-timer.js.map +1 -0
  13. package/dist/async/retry.d.ts +8 -0
  14. package/dist/async/retry.js +36 -0
  15. package/dist/async/retry.js.map +1 -0
  16. package/dist/async/wait.d.ts +10 -0
  17. package/dist/async/wait.js +35 -0
  18. package/dist/async/wait.js.map +1 -0
  19. package/dist/docker/database-manager.d.ts +22 -0
  20. package/dist/docker/database-manager.js +97 -0
  21. package/dist/docker/database-manager.js.map +1 -0
  22. package/dist/docker/docker-test-manager.d.ts +44 -0
  23. package/dist/docker/docker-test-manager.js +805 -0
  24. package/dist/docker/docker-test-manager.js.map +1 -0
  25. package/dist/docker/index.d.ts +4 -0
  26. package/dist/docker/index.js +4 -0
  27. package/dist/docker/index.js.map +1 -0
  28. package/dist/docker/redis-manager.d.ts +12 -0
  29. package/dist/docker/redis-manager.js +453 -0
  30. package/dist/docker/redis-manager.js.map +1 -0
  31. package/dist/docker/types.d.ts +103 -0
  32. package/dist/docker/types.js +2 -0
  33. package/dist/docker/types.js.map +1 -0
  34. package/dist/errors.d.ts +15 -0
  35. package/dist/errors.js +28 -0
  36. package/dist/errors.js.map +1 -0
  37. package/dist/helpers/assertions.d.ts +6 -0
  38. package/dist/helpers/assertions.js +37 -0
  39. package/dist/helpers/assertions.js.map +1 -0
  40. package/dist/helpers/console.d.ts +1 -0
  41. package/dist/helpers/console.js +23 -0
  42. package/dist/helpers/console.js.map +1 -0
  43. package/dist/helpers/index.d.ts +3 -0
  44. package/dist/helpers/index.js +4 -0
  45. package/dist/helpers/index.js.map +1 -0
  46. package/dist/helpers/temp-dir.d.ts +2 -0
  47. package/dist/helpers/temp-dir.js +13 -0
  48. package/dist/helpers/temp-dir.js.map +1 -0
  49. package/dist/index.d.ts +2 -0
  50. package/dist/index.js +2 -0
  51. package/dist/index.js.map +1 -1
  52. package/dist/performance/index.d.ts +2 -0
  53. package/dist/performance/index.js +3 -0
  54. package/dist/performance/index.js.map +1 -0
  55. package/dist/performance/memory-detector.d.ts +9 -0
  56. package/dist/performance/memory-detector.js +61 -0
  57. package/dist/performance/memory-detector.js.map +1 -0
  58. package/dist/performance/perf-timer.d.ts +9 -0
  59. package/dist/performance/perf-timer.js +49 -0
  60. package/dist/performance/perf-timer.js.map +1 -0
  61. package/dist/titan/container-utils.d.ts +20 -0
  62. package/dist/titan/container-utils.js +78 -0
  63. package/dist/titan/container-utils.js.map +1 -0
  64. package/dist/titan/database/database-testing.module.d.ts +81 -0
  65. package/dist/titan/database/database-testing.module.js +419 -0
  66. package/dist/titan/database/database-testing.module.js.map +1 -0
  67. package/dist/titan/database/index.d.ts +3 -0
  68. package/dist/titan/database/index.js +4 -0
  69. package/dist/titan/database/index.js.map +1 -0
  70. package/dist/titan/database/test-utilities.d.ts +31 -0
  71. package/dist/titan/database/test-utilities.js +145 -0
  72. package/dist/titan/database/test-utilities.js.map +1 -0
  73. package/dist/titan/index.d.ts +14 -0
  74. package/dist/titan/index.js +10 -0
  75. package/dist/titan/index.js.map +1 -0
  76. package/dist/titan/nexus/index.d.ts +3 -0
  77. package/dist/titan/nexus/index.js +4 -0
  78. package/dist/titan/nexus/index.js.map +1 -0
  79. package/dist/titan/nexus/mock-provider.d.ts +41 -0
  80. package/dist/titan/nexus/mock-provider.js +127 -0
  81. package/dist/titan/nexus/mock-provider.js.map +1 -0
  82. package/dist/titan/nexus/test-container.d.ts +120 -0
  83. package/dist/titan/nexus/test-container.js +559 -0
  84. package/dist/titan/nexus/test-container.js.map +1 -0
  85. package/dist/titan/nexus/test-utilities.d.ts +135 -0
  86. package/dist/titan/nexus/test-utilities.js +484 -0
  87. package/dist/titan/nexus/test-utilities.js.map +1 -0
  88. package/dist/titan/pm/index.d.ts +4 -0
  89. package/dist/titan/pm/index.js +4 -0
  90. package/dist/titan/pm/index.js.map +1 -0
  91. package/dist/titan/pm/mock-process-spawner.d.ts +60 -0
  92. package/dist/titan/pm/mock-process-spawner.js +321 -0
  93. package/dist/titan/pm/mock-process-spawner.js.map +1 -0
  94. package/dist/titan/pm/mock-spawner.d.ts +27 -0
  95. package/dist/titan/pm/mock-spawner.js +99 -0
  96. package/dist/titan/pm/mock-spawner.js.map +1 -0
  97. package/dist/titan/pm/test-process-manager.d.ts +49 -0
  98. package/dist/titan/pm/test-process-manager.js +188 -0
  99. package/dist/titan/pm/test-process-manager.js.map +1 -0
  100. package/dist/titan/redis-test-utils.d.ts +33 -0
  101. package/dist/titan/redis-test-utils.js +414 -0
  102. package/dist/titan/redis-test-utils.js.map +1 -0
  103. package/dist/titan/test-application.d.ts +21 -0
  104. package/dist/titan/test-application.js +90 -0
  105. package/dist/titan/test-application.js.map +1 -0
  106. package/dist/titan/test-fixtures.d.ts +97 -0
  107. package/dist/titan/test-fixtures.js +223 -0
  108. package/dist/titan/test-fixtures.js.map +1 -0
  109. package/dist/titan/test-mocks.d.ts +29 -0
  110. package/dist/titan/test-mocks.js +262 -0
  111. package/dist/titan/test-mocks.js.map +1 -0
  112. package/dist/titan/test-module.d.ts +46 -0
  113. package/dist/titan/test-module.js +120 -0
  114. package/dist/titan/test-module.js.map +1 -0
  115. package/package.json +41 -4
  116. package/src/async/README.md +336 -0
  117. package/src/async/deferred.ts +98 -0
  118. package/src/async/events.ts +386 -0
  119. package/src/async/index.ts +48 -0
  120. package/src/async/mock-timer.ts +220 -0
  121. package/src/async/retry.ts +118 -0
  122. package/src/async/wait.ts +151 -0
  123. package/src/docker/database-manager.ts +242 -0
  124. package/src/docker/docker-test-manager.ts +1186 -0
  125. package/src/docker/index.ts +48 -0
  126. package/src/docker/redis-manager.ts +738 -0
  127. package/src/docker/types.ts +216 -0
  128. package/src/errors.ts +31 -0
  129. package/src/helpers/assertions.ts +171 -0
  130. package/src/helpers/console.ts +74 -0
  131. package/src/helpers/index.ts +15 -0
  132. package/src/helpers/temp-dir.ts +50 -0
  133. package/src/index.ts +2 -0
  134. package/src/performance/index.ts +11 -0
  135. package/src/performance/memory-detector.ts +166 -0
  136. package/src/performance/perf-timer.ts +146 -0
  137. package/src/titan/container-utils.ts +128 -0
  138. package/src/titan/database/database-testing.module.ts +831 -0
  139. package/src/titan/database/index.ts +30 -0
  140. package/src/titan/database/test-utilities.ts +337 -0
  141. package/src/titan/index.ts +147 -0
  142. package/src/titan/nexus/index.ts +3 -0
  143. package/src/titan/nexus/mock-provider.ts +189 -0
  144. package/src/titan/nexus/test-container.ts +887 -0
  145. package/src/titan/nexus/test-utilities.ts +796 -0
  146. package/src/titan/pm/index.ts +22 -0
  147. package/src/titan/pm/mock-process-spawner.ts +481 -0
  148. package/src/titan/pm/mock-spawner.ts +156 -0
  149. package/src/titan/pm/test-process-manager.ts +345 -0
  150. package/src/titan/redis-test-utils.ts +566 -0
  151. package/src/titan/test-application.ts +154 -0
  152. package/src/titan/test-fixtures.ts +304 -0
  153. package/src/titan/test-mocks.ts +336 -0
  154. package/src/titan/test-module.ts +232 -0
@@ -0,0 +1,336 @@
1
+ # Async Testing Utilities
2
+
3
+ Comprehensive utilities for testing asynchronous code in JavaScript/TypeScript.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ pnpm add -D @omnitron-dev/testing
9
+ ```
10
+
11
+ ## Usage
12
+
13
+ Import from the main package or the async submodule:
14
+
15
+ ```typescript
16
+ // Import from main package
17
+ import { defer, waitFor, retry } from '@omnitron-dev/testing';
18
+
19
+ // Or import from async submodule
20
+ import { defer, waitFor, retry } from '@omnitron-dev/testing/async';
21
+ ```
22
+
23
+ ## API Reference
24
+
25
+ ### Deferred Promises
26
+
27
+ #### `DeferredPromise<T>`
28
+ Class for creating a promise with external control over resolution/rejection.
29
+
30
+ ```typescript
31
+ const deferred = new DeferredPromise<string>();
32
+ setTimeout(() => deferred.resolve('done'), 1000);
33
+ await deferred.promise; // 'done'
34
+ console.log(deferred.isSettled); // true
35
+ ```
36
+
37
+ #### `createDeferred<T>()`
38
+ Factory function for creating deferred promises.
39
+
40
+ ```typescript
41
+ const deferred = createDeferred<number>();
42
+ deferred.resolve(42);
43
+ ```
44
+
45
+ #### `defer<T>()`
46
+ Lightweight deferred promise (backward compatible).
47
+
48
+ ```typescript
49
+ const deferred = defer<string>();
50
+ deferred.resolve('success');
51
+ await deferred.promise;
52
+ ```
53
+
54
+ ### Retry and Timeout
55
+
56
+ #### `retry<T>(fn, options?)`
57
+ Retry an async operation with exponential backoff.
58
+
59
+ ```typescript
60
+ const result = await retry(
61
+ async () => fetchData(),
62
+ {
63
+ retries: 5,
64
+ delay: 100,
65
+ backoff: 2,
66
+ onRetry: (error, attempt) => console.log(`Retry ${attempt}`)
67
+ }
68
+ );
69
+ ```
70
+
71
+ **Options:**
72
+ - `retries`: Maximum retry attempts (default: 3)
73
+ - `delay`: Initial delay in ms (default: 100)
74
+ - `backoff`: Backoff multiplier (default: 2)
75
+ - `onRetry`: Callback on each retry
76
+
77
+ #### `withTimeout<T>(promise, timeout?, errorMessage?)`
78
+ Race a promise against a timeout.
79
+
80
+ ```typescript
81
+ const result = await withTimeout(
82
+ fetchData(),
83
+ 5000,
84
+ 'Data fetch timed out'
85
+ );
86
+ ```
87
+
88
+ ### Wait Utilities
89
+
90
+ #### `waitFor(condition, options?)`
91
+ Wait for a condition to become true.
92
+
93
+ ```typescript
94
+ await waitFor(
95
+ () => element.isVisible(),
96
+ { timeout: 3000, interval: 100, message: 'Element not visible' }
97
+ );
98
+ ```
99
+
100
+ #### `waitForCondition(condition, timeout?, interval?)`
101
+ Alternative API for waiting on conditions.
102
+
103
+ ```typescript
104
+ await waitForCondition(
105
+ () => counter > 10,
106
+ 5000,
107
+ 100
108
+ );
109
+ ```
110
+
111
+ #### `delay(ms)`
112
+ Simple async sleep utility.
113
+
114
+ ```typescript
115
+ await delay(1000); // Wait 1 second
116
+ ```
117
+
118
+ #### `nextTick()`
119
+ Wait for the next event loop tick.
120
+
121
+ ```typescript
122
+ emitter.emit('event');
123
+ await nextTick();
124
+ // Event handlers have now executed
125
+ ```
126
+
127
+ #### `flushPromises()`
128
+ Flush all pending promises in the event loop.
129
+
130
+ ```typescript
131
+ Promise.resolve().then(() => { executed = true });
132
+ await flushPromises();
133
+ expect(executed).toBe(true);
134
+ ```
135
+
136
+ ### Event Utilities
137
+
138
+ #### `EventListenerTracker`
139
+ Track event listeners for automatic cleanup.
140
+
141
+ ```typescript
142
+ const tracker = new EventListenerTracker();
143
+ tracker.on(emitter, 'data', handler);
144
+ tracker.once(emitter, 'error', errorHandler);
145
+
146
+ // In cleanup
147
+ tracker.cleanup(); // Removes all tracked listeners
148
+ ```
149
+
150
+ #### `EventCollector<T>`
151
+ Collect events for inspection and assertions.
152
+
153
+ ```typescript
154
+ const collector = new EventCollector(emitter);
155
+ collector.collect('data');
156
+
157
+ // Trigger events...
158
+
159
+ const events = collector.getEvents('data');
160
+ expect(events).toHaveLength(3);
161
+
162
+ collector.assertEmitted('data', 3);
163
+ collector.clear();
164
+ collector.stop();
165
+ ```
166
+
167
+ #### `waitForEvents(target, events, timeout?)`
168
+ Wait for multiple events to be emitted.
169
+
170
+ ```typescript
171
+ const [userData, profileData] = await waitForEvents(
172
+ emitter,
173
+ ['user', 'profile'],
174
+ 3000
175
+ );
176
+ ```
177
+
178
+ #### `collectEvents<T>(target, event, condition, timeout?)`
179
+ Collect events until a condition is met.
180
+
181
+ ```typescript
182
+ const events = await collectEvents(
183
+ emitter,
184
+ 'data',
185
+ (events) => events.length >= 5,
186
+ 3000
187
+ );
188
+ ```
189
+
190
+ #### `createEventSpy(target, event)`
191
+ Create a spy to record events.
192
+
193
+ ```typescript
194
+ const spy = createEventSpy(emitter, 'data');
195
+ // Trigger events...
196
+ expect(spy.events).toHaveLength(3);
197
+ spy.clear();
198
+ ```
199
+
200
+ ### Mock Timers
201
+
202
+ #### `MockTimerController`
203
+ Manual control over timers for deterministic testing.
204
+
205
+ ```typescript
206
+ const timer = new MockTimerController();
207
+ timer.install();
208
+
209
+ let executed = false;
210
+ setTimeout(() => { executed = true }, 1000);
211
+
212
+ timer.tick(500); // executed is still false
213
+ timer.tick(500); // executed is now true
214
+
215
+ timer.restore();
216
+ ```
217
+
218
+ **Methods:**
219
+ - `install()`: Replace native timers
220
+ - `restore()`: Restore native timers
221
+ - `tick(ms)`: Advance time by ms
222
+ - `getCurrentTime()`: Get current mock time
223
+ - `getPendingCount()`: Get number of pending timers
224
+ - `clearAll()`: Clear all pending timers
225
+ - `reset()`: Reset to initial state
226
+
227
+ #### `createMockTimer()`
228
+ Factory function for creating mock timers.
229
+
230
+ ```typescript
231
+ const timer = createMockTimer();
232
+ timer.install();
233
+ // ... test code ...
234
+ timer.restore();
235
+ ```
236
+
237
+ ## Error Handling
238
+
239
+ All async utilities use typed errors from `@omnitron-dev/testing/errors`:
240
+
241
+ - `TimeoutError`: Thrown when operations timeout
242
+ - `TestingError`: Base class for testing errors
243
+
244
+ ```typescript
245
+ import { TimeoutError } from '@omnitron-dev/testing';
246
+
247
+ try {
248
+ await waitFor(() => false, { timeout: 100 });
249
+ } catch (error) {
250
+ if (error instanceof TimeoutError) {
251
+ console.log('Operation timed out');
252
+ }
253
+ }
254
+ ```
255
+
256
+ ## Examples
257
+
258
+ ### Testing Event Sequences
259
+
260
+ ```typescript
261
+ import { EventCollector, delay } from '@omnitron-dev/testing/async';
262
+
263
+ test('event sequence', async () => {
264
+ const emitter = new EventEmitter();
265
+ const collector = new EventCollector(emitter);
266
+
267
+ collector.collect('start');
268
+ collector.collect('data');
269
+ collector.collect('end');
270
+
271
+ // Trigger events
272
+ await processData(emitter);
273
+
274
+ collector.assertEmitted('start', 1);
275
+ collector.assertEmitted('data', 5);
276
+ collector.assertEmitted('end', 1);
277
+
278
+ collector.stop();
279
+ });
280
+ ```
281
+
282
+ ### Retrying Flaky Operations
283
+
284
+ ```typescript
285
+ import { retry } from '@omnitron-dev/testing/async';
286
+
287
+ test('retry flaky operation', async () => {
288
+ const result = await retry(
289
+ async () => {
290
+ const response = await fetch('/api/data');
291
+ if (!response.ok) throw new Error('Failed');
292
+ return response.json();
293
+ },
294
+ {
295
+ retries: 3,
296
+ delay: 100,
297
+ backoff: 2,
298
+ onRetry: (error, attempt) => {
299
+ console.log(`Retry ${attempt}: ${error.message}`);
300
+ }
301
+ }
302
+ );
303
+
304
+ expect(result).toBeDefined();
305
+ });
306
+ ```
307
+
308
+ ### Testing Time-Dependent Code
309
+
310
+ ```typescript
311
+ import { MockTimerController } from '@omnitron-dev/testing/async';
312
+
313
+ test('debounce function', () => {
314
+ const timer = new MockTimerController();
315
+ timer.install();
316
+
317
+ let count = 0;
318
+ const debounced = debounce(() => { count++; }, 100);
319
+
320
+ debounced();
321
+ debounced();
322
+ debounced();
323
+
324
+ timer.tick(50);
325
+ expect(count).toBe(0);
326
+
327
+ timer.tick(50);
328
+ expect(count).toBe(1);
329
+
330
+ timer.restore();
331
+ });
332
+ ```
333
+
334
+ ## License
335
+
336
+ MIT
@@ -0,0 +1,98 @@
1
+ /**
2
+ * Deferred promise utilities for async testing
3
+ */
4
+
5
+ /**
6
+ * Promise with deferred resolution/rejection
7
+ *
8
+ * Allows external control of promise resolution, useful for testing
9
+ * async flows and coordinating multiple asynchronous operations.
10
+ *
11
+ * @example
12
+ * ```ts
13
+ * const deferred = new DeferredPromise<string>();
14
+ * setTimeout(() => deferred.resolve('done'), 1000);
15
+ * const result = await deferred.promise; // 'done'
16
+ * ```
17
+ */
18
+ export class DeferredPromise<T> {
19
+ public promise: Promise<T>;
20
+ public resolve!: (value: T) => void;
21
+ public reject!: (error: Error) => void;
22
+ private settled = false;
23
+
24
+ constructor() {
25
+ this.promise = new Promise<T>((resolve, reject) => {
26
+ this.resolve = (value: T) => {
27
+ if (!this.settled) {
28
+ this.settled = true;
29
+ resolve(value);
30
+ }
31
+ };
32
+
33
+ this.reject = (error: Error) => {
34
+ if (!this.settled) {
35
+ this.settled = true;
36
+ reject(error);
37
+ }
38
+ };
39
+ });
40
+ }
41
+
42
+ /**
43
+ * Check if the promise has been settled (resolved or rejected)
44
+ */
45
+ get isSettled(): boolean {
46
+ return this.settled;
47
+ }
48
+ }
49
+
50
+ /**
51
+ * Create a deferred promise (factory function)
52
+ *
53
+ * @example
54
+ * ```ts
55
+ * const deferred = createDeferred<number>();
56
+ * deferred.resolve(42);
57
+ * ```
58
+ */
59
+ export function createDeferred<T>(): DeferredPromise<T> {
60
+ return new DeferredPromise<T>();
61
+ }
62
+
63
+ /**
64
+ * Deferred interface (lightweight version)
65
+ *
66
+ * Provides external control over promise resolution without
67
+ * the overhead of a class instance.
68
+ */
69
+ export interface Deferred<T> {
70
+ promise: Promise<T>;
71
+ resolve: (value: T) => void;
72
+ reject: (reason?: any) => void;
73
+ }
74
+
75
+ /**
76
+ * Create a deferred promise with minimal overhead
77
+ *
78
+ * This is a lightweight alternative to DeferredPromise class,
79
+ * maintaining backward compatibility with existing code.
80
+ *
81
+ * @example
82
+ * ```ts
83
+ * const deferred = defer<string>();
84
+ * setTimeout(() => deferred.resolve('done'), 100);
85
+ * await deferred.promise;
86
+ * ```
87
+ */
88
+ export function defer<T>(): Deferred<T> {
89
+ let resolve!: (value: T) => void;
90
+ let reject!: (reason?: any) => void;
91
+
92
+ const promise = new Promise<T>((res, rej) => {
93
+ resolve = res;
94
+ reject = rej;
95
+ });
96
+
97
+ return { promise, resolve, reject };
98
+ }