@omnitron-dev/testing 0.4.0 → 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.
Files changed (89) 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/package.json +28 -2
  62. package/src/async/README.md +336 -0
  63. package/src/async/deferred.ts +98 -0
  64. package/src/async/events.ts +386 -0
  65. package/src/async/index.ts +48 -0
  66. package/src/async/mock-timer.ts +220 -0
  67. package/src/async/retry.ts +118 -0
  68. package/src/async/wait.ts +151 -0
  69. package/src/docker/database-manager.ts +242 -0
  70. package/src/docker/docker-test-manager.ts +1186 -0
  71. package/src/docker/index.ts +48 -0
  72. package/src/docker/redis-manager.ts +738 -0
  73. package/src/docker/types.ts +216 -0
  74. package/src/errors.ts +31 -0
  75. package/src/helpers/assertions.ts +171 -0
  76. package/src/helpers/console.ts +74 -0
  77. package/src/helpers/index.ts +15 -0
  78. package/src/helpers/temp-dir.ts +50 -0
  79. package/src/index.ts +2 -0
  80. package/src/performance/index.ts +11 -0
  81. package/src/performance/memory-detector.ts +166 -0
  82. package/src/performance/perf-timer.ts +146 -0
  83. package/src/titan/container-utils.ts +128 -0
  84. package/src/titan/index.ts +59 -0
  85. package/src/titan/redis-test-utils.ts +566 -0
  86. package/src/titan/test-application.ts +154 -0
  87. package/src/titan/test-fixtures.ts +304 -0
  88. package/src/titan/test-mocks.ts +336 -0
  89. package/src/titan/test-module.ts +231 -0
@@ -0,0 +1,118 @@
1
+ /**
2
+ * Retry and timeout utilities for async testing
3
+ */
4
+
5
+ import { TimeoutError } from '../errors.js';
6
+
7
+ /**
8
+ * Options for retry behavior
9
+ */
10
+ export interface RetryOptions {
11
+ /**
12
+ * Maximum number of retry attempts (default: 3)
13
+ */
14
+ retries?: number;
15
+
16
+ /**
17
+ * Initial delay between retries in milliseconds (default: 100)
18
+ */
19
+ delay?: number;
20
+
21
+ /**
22
+ * Backoff multiplier for exponential backoff (default: 2)
23
+ */
24
+ backoff?: number;
25
+
26
+ /**
27
+ * Callback invoked on each retry attempt
28
+ */
29
+ onRetry?: (error: Error, attempt: number) => void;
30
+ }
31
+
32
+ /**
33
+ * Retry an async operation with exponential backoff
34
+ *
35
+ * Useful for testing operations that may temporarily fail,
36
+ * such as network requests or resource availability checks.
37
+ *
38
+ * @param fn - Async function to retry
39
+ * @param options - Retry configuration options
40
+ * @returns Promise resolving to the function's result
41
+ * @throws Last error if all retries are exhausted
42
+ *
43
+ * @example
44
+ * ```ts
45
+ * const result = await retry(
46
+ * async () => fetchData(),
47
+ * { retries: 5, delay: 200, backoff: 2 }
48
+ * );
49
+ * ```
50
+ */
51
+ export async function retry<T>(
52
+ fn: () => Promise<T>,
53
+ options: RetryOptions = {}
54
+ ): Promise<T> {
55
+ const { retries = 3, delay = 100, backoff = 2, onRetry } = options;
56
+
57
+ let lastError: Error;
58
+
59
+ for (let i = 0; i < retries; i++) {
60
+ try {
61
+ return await fn();
62
+ } catch (error) {
63
+ lastError = error as Error;
64
+
65
+ if (i < retries - 1) {
66
+ if (onRetry) {
67
+ onRetry(lastError, i + 1);
68
+ }
69
+
70
+ const waitTime = delay * Math.pow(backoff, i);
71
+ await new Promise((resolve) => setTimeout(resolve, waitTime));
72
+ }
73
+ }
74
+ }
75
+
76
+ throw lastError!;
77
+ }
78
+
79
+ /**
80
+ * Wait for an async operation with timeout
81
+ *
82
+ * Races the provided promise against a timeout, throwing a TimeoutError
83
+ * if the timeout is reached first.
84
+ *
85
+ * @param promise - Promise to race against timeout
86
+ * @param timeout - Timeout in milliseconds (default: 5000)
87
+ * @param errorMessage - Custom error message for timeout
88
+ * @returns Promise resolving to the original promise's result
89
+ * @throws TimeoutError if timeout is reached
90
+ *
91
+ * @example
92
+ * ```ts
93
+ * const result = await withTimeout(
94
+ * fetchData(),
95
+ * 3000,
96
+ * 'Data fetch timed out'
97
+ * );
98
+ * ```
99
+ */
100
+ export async function withTimeout<T>(
101
+ promise: Promise<T>,
102
+ timeout = 5000,
103
+ errorMessage = 'Operation timed out'
104
+ ): Promise<T> {
105
+ let timeoutId: NodeJS.Timeout;
106
+
107
+ const timeoutPromise = new Promise<never>((_, reject) => {
108
+ timeoutId = setTimeout(() => {
109
+ reject(new TimeoutError(errorMessage, timeout));
110
+ }, timeout);
111
+ });
112
+
113
+ try {
114
+ return await Promise.race([promise, timeoutPromise]);
115
+ } finally {
116
+ clearTimeout(timeoutId!);
117
+ }
118
+ }
@@ -0,0 +1,151 @@
1
+ /**
2
+ * Wait utilities for async testing
3
+ */
4
+
5
+ import { TimeoutError } from '../errors.js';
6
+
7
+ /**
8
+ * Options for wait operations
9
+ */
10
+ export interface WaitOptions {
11
+ /**
12
+ * Timeout in milliseconds (default: 5000)
13
+ */
14
+ timeout?: number;
15
+
16
+ /**
17
+ * Polling interval in milliseconds (default: 50)
18
+ */
19
+ interval?: number;
20
+
21
+ /**
22
+ * Custom error message
23
+ */
24
+ message?: string;
25
+ }
26
+
27
+ /**
28
+ * Wait for a condition to be true
29
+ *
30
+ * Polls the condition function at regular intervals until it returns true
31
+ * or the timeout is reached.
32
+ *
33
+ * @param condition - Function that returns true when condition is met
34
+ * @param options - Wait configuration options
35
+ * @throws TimeoutError if timeout is reached before condition is met
36
+ *
37
+ * @example
38
+ * ```ts
39
+ * await waitFor(
40
+ * () => element.isVisible(),
41
+ * { timeout: 3000, interval: 100 }
42
+ * );
43
+ * ```
44
+ */
45
+ export async function waitFor(
46
+ condition: () => boolean | Promise<boolean>,
47
+ options: WaitOptions = {}
48
+ ): Promise<void> {
49
+ const { timeout = 5000, interval = 50, message = 'Condition not met' } = options;
50
+ const start = Date.now();
51
+
52
+ while (Date.now() - start < timeout) {
53
+ const result = await condition();
54
+ if (result) {
55
+ return;
56
+ }
57
+ await delay(interval);
58
+ }
59
+
60
+ throw new TimeoutError('waitFor: ' + message, timeout);
61
+ }
62
+
63
+ /**
64
+ * Wait for a condition to be true with timeout (alternative naming)
65
+ *
66
+ * This is an alias for waitFor with slightly different parameter signature
67
+ * for backward compatibility.
68
+ *
69
+ * @param condition - Function that returns true when condition is met
70
+ * @param timeout - Timeout in milliseconds (default: 5000)
71
+ * @param interval - Polling interval in milliseconds (default: 50)
72
+ * @throws TimeoutError if timeout is reached before condition is met
73
+ *
74
+ * @example
75
+ * ```ts
76
+ * await waitForCondition(
77
+ * () => counter > 10,
78
+ * 5000,
79
+ * 100
80
+ * );
81
+ * ```
82
+ */
83
+ export async function waitForCondition(
84
+ condition: () => boolean | Promise<boolean>,
85
+ timeout = 5000,
86
+ interval = 50
87
+ ): Promise<void> {
88
+ const start = Date.now();
89
+
90
+ while (Date.now() - start < timeout) {
91
+ const result = await condition();
92
+ if (result) {
93
+ return;
94
+ }
95
+ await new Promise((resolve) => setTimeout(resolve, interval));
96
+ }
97
+
98
+ throw new TimeoutError('waitForCondition', timeout);
99
+ }
100
+
101
+ /**
102
+ * Delay execution for specified milliseconds
103
+ *
104
+ * Simple async sleep utility for introducing delays in tests.
105
+ *
106
+ * @param ms - Milliseconds to delay
107
+ *
108
+ * @example
109
+ * ```ts
110
+ * await delay(1000); // Wait 1 second
111
+ * ```
112
+ */
113
+ export function delay(ms: number): Promise<void> {
114
+ return new Promise((resolve) => setTimeout(resolve, ms));
115
+ }
116
+
117
+ /**
118
+ * Wait for next tick in the event loop
119
+ *
120
+ * Useful for allowing pending async operations to complete
121
+ * before proceeding with test assertions.
122
+ *
123
+ * @example
124
+ * ```ts
125
+ * emitter.emit('event');
126
+ * await nextTick(); // Let handlers execute
127
+ * expect(handlerCalled).toBe(true);
128
+ * ```
129
+ */
130
+ export function nextTick(): Promise<void> {
131
+ return new Promise((resolve) => setImmediate(resolve));
132
+ }
133
+
134
+ /**
135
+ * Flush all pending promises in the event loop
136
+ *
137
+ * Ensures all microtasks and next-tick callbacks are executed
138
+ * before proceeding. Useful for testing promise chains and
139
+ * async operations.
140
+ *
141
+ * @example
142
+ * ```ts
143
+ * Promise.resolve().then(() => { executed = true });
144
+ * await flushPromises();
145
+ * expect(executed).toBe(true);
146
+ * ```
147
+ */
148
+ export async function flushPromises(): Promise<void> {
149
+ await new Promise((resolve) => setImmediate(resolve));
150
+ await new Promise((resolve) => process.nextTick(resolve));
151
+ }
@@ -0,0 +1,242 @@
1
+ /**
2
+ * Database Test Manager
3
+ *
4
+ * Provides specialized helpers for creating and managing database containers
5
+ * in tests. Supports PostgreSQL and MySQL with sensible defaults.
6
+ */
7
+
8
+ import { DockerTestManager } from './docker-test-manager.js';
9
+ import type { DockerContainer } from './types.js';
10
+
11
+ /**
12
+ * Database Test Manager
13
+ *
14
+ * Provides convenient methods for creating PostgreSQL and MySQL containers
15
+ * with proper health checks and connection strings.
16
+ *
17
+ * @example
18
+ * ```typescript
19
+ * // Create a PostgreSQL container
20
+ * const pg = await DatabaseTestManager.createPostgresContainer({
21
+ * database: 'mydb',
22
+ * user: 'myuser',
23
+ * password: 'mypass',
24
+ * });
25
+ *
26
+ * // Use with helper
27
+ * await DatabaseTestManager.withPostgres(async (container, connStr) => {
28
+ * // Run tests with database
29
+ * });
30
+ * ```
31
+ */
32
+ export class DatabaseTestManager {
33
+ private static _dockerManager: DockerTestManager | null = null;
34
+
35
+ /**
36
+ * Get the Docker manager instance
37
+ * @private
38
+ */
39
+ private static getDockerManager(): DockerTestManager {
40
+ if (!DatabaseTestManager._dockerManager) {
41
+ DatabaseTestManager._dockerManager = DockerTestManager.getInstance();
42
+ }
43
+ return DatabaseTestManager._dockerManager;
44
+ }
45
+
46
+ /**
47
+ * Create a PostgreSQL container
48
+ *
49
+ * @param options - PostgreSQL configuration options
50
+ * @returns Promise resolving to DockerContainer
51
+ *
52
+ * @example
53
+ * ```typescript
54
+ * const container = await DatabaseTestManager.createPostgresContainer({
55
+ * database: 'testdb',
56
+ * user: 'testuser',
57
+ * password: 'testpass',
58
+ * });
59
+ *
60
+ * const port = container.ports.get(5432)!;
61
+ * const connStr = `postgresql://testuser:testpass@localhost:${port}/testdb`;
62
+ * ```
63
+ */
64
+ static async createPostgresContainer(options?: {
65
+ /** Container name (auto-generated if not provided) */
66
+ name?: string;
67
+ /** Host port or 'auto' for dynamic allocation (default: 'auto') */
68
+ port?: number | 'auto';
69
+ /** Database name (default: 'testdb') */
70
+ database?: string;
71
+ /** Database user (default: 'testuser') */
72
+ user?: string;
73
+ /** Database password (default: 'testpass') */
74
+ password?: string;
75
+ }): Promise<DockerContainer> {
76
+ const port = options?.port || 'auto';
77
+ const database = options?.database || 'testdb';
78
+ const user = options?.user || 'testuser';
79
+ const password = options?.password || 'testpass';
80
+
81
+ return DatabaseTestManager.getDockerManager().createContainer({
82
+ name: options?.name,
83
+ image: 'postgres:16-alpine',
84
+ ports: { 5432: port },
85
+ environment: {
86
+ POSTGRES_DB: database,
87
+ POSTGRES_USER: user,
88
+ POSTGRES_PASSWORD: password,
89
+ POSTGRES_HOST_AUTH_METHOD: 'trust',
90
+ },
91
+ healthcheck: {
92
+ test: ['CMD-SHELL', `pg_isready -U ${user}`],
93
+ interval: '1s',
94
+ timeout: '3s',
95
+ retries: 5,
96
+ startPeriod: '2s',
97
+ },
98
+ waitFor: {
99
+ healthcheck: true,
100
+ timeout: 30000,
101
+ },
102
+ });
103
+ }
104
+
105
+ /**
106
+ * Create a MySQL container
107
+ *
108
+ * @param options - MySQL configuration options
109
+ * @returns Promise resolving to DockerContainer
110
+ *
111
+ * @example
112
+ * ```typescript
113
+ * const container = await DatabaseTestManager.createMySQLContainer({
114
+ * database: 'testdb',
115
+ * user: 'testuser',
116
+ * password: 'testpass',
117
+ * });
118
+ *
119
+ * const port = container.ports.get(3306)!;
120
+ * const connStr = `mysql://testuser:testpass@localhost:${port}/testdb`;
121
+ * ```
122
+ */
123
+ static async createMySQLContainer(options?: {
124
+ /** Container name (auto-generated if not provided) */
125
+ name?: string;
126
+ /** Host port or 'auto' for dynamic allocation (default: 'auto') */
127
+ port?: number | 'auto';
128
+ /** Database name (default: 'testdb') */
129
+ database?: string;
130
+ /** Database user (default: 'testuser') */
131
+ user?: string;
132
+ /** Database password (default: 'testpass') */
133
+ password?: string;
134
+ /** Root password (default: 'rootpass') */
135
+ rootPassword?: string;
136
+ }): Promise<DockerContainer> {
137
+ const port = options?.port || 'auto';
138
+ const database = options?.database || 'testdb';
139
+ const user = options?.user || 'testuser';
140
+ const password = options?.password || 'testpass';
141
+ const rootPassword = options?.rootPassword || 'rootpass';
142
+
143
+ return DatabaseTestManager.getDockerManager().createContainer({
144
+ name: options?.name,
145
+ image: 'mysql:8.0',
146
+ ports: { 3306: port },
147
+ environment: {
148
+ MYSQL_DATABASE: database,
149
+ MYSQL_USER: user,
150
+ MYSQL_PASSWORD: password,
151
+ MYSQL_ROOT_PASSWORD: rootPassword,
152
+ MYSQL_ALLOW_EMPTY_PASSWORD: 'yes',
153
+ },
154
+ healthcheck: {
155
+ test: ['CMD', 'mysqladmin', 'ping', '-h', 'localhost'],
156
+ interval: '1s',
157
+ timeout: '3s',
158
+ retries: 10,
159
+ startPeriod: '5s',
160
+ },
161
+ waitFor: {
162
+ healthcheck: true,
163
+ timeout: 30000,
164
+ },
165
+ });
166
+ }
167
+
168
+ /**
169
+ * Run tests with a PostgreSQL container
170
+ *
171
+ * Creates a PostgreSQL container, runs the test function, and cleans up.
172
+ *
173
+ * @param testFn - Test function that receives container and connection string
174
+ * @param options - PostgreSQL configuration options
175
+ * @returns Promise resolving to test function result
176
+ *
177
+ * @example
178
+ * ```typescript
179
+ * await DatabaseTestManager.withPostgres(async (container, connectionString) => {
180
+ * const client = new Client({ connectionString });
181
+ * await client.connect();
182
+ * // Run tests...
183
+ * await client.end();
184
+ * });
185
+ * ```
186
+ */
187
+ static async withPostgres<T>(
188
+ testFn: (container: DockerContainer, connectionString: string) => Promise<T>,
189
+ options?: Parameters<typeof DatabaseTestManager.createPostgresContainer>[0]
190
+ ): Promise<T> {
191
+ const container = await DatabaseTestManager.createPostgresContainer(options);
192
+
193
+ const port = container.ports.get(5432)!;
194
+ const database = options?.database || 'testdb';
195
+ const user = options?.user || 'testuser';
196
+ const password = options?.password || 'testpass';
197
+ const connectionString = `postgresql://${user}:${password}@localhost:${port}/${database}`;
198
+
199
+ try {
200
+ return await testFn(container, connectionString);
201
+ } finally {
202
+ await container.cleanup();
203
+ }
204
+ }
205
+
206
+ /**
207
+ * Run tests with a MySQL container
208
+ *
209
+ * Creates a MySQL container, runs the test function, and cleans up.
210
+ *
211
+ * @param testFn - Test function that receives container and connection string
212
+ * @param options - MySQL configuration options
213
+ * @returns Promise resolving to test function result
214
+ *
215
+ * @example
216
+ * ```typescript
217
+ * await DatabaseTestManager.withMySQL(async (container, connectionString) => {
218
+ * const connection = await mysql.createConnection(connectionString);
219
+ * // Run tests...
220
+ * await connection.end();
221
+ * });
222
+ * ```
223
+ */
224
+ static async withMySQL<T>(
225
+ testFn: (container: DockerContainer, connectionString: string) => Promise<T>,
226
+ options?: Parameters<typeof DatabaseTestManager.createMySQLContainer>[0]
227
+ ): Promise<T> {
228
+ const container = await DatabaseTestManager.createMySQLContainer(options);
229
+
230
+ const port = container.ports.get(3306)!;
231
+ const database = options?.database || 'testdb';
232
+ const user = options?.user || 'testuser';
233
+ const password = options?.password || 'testpass';
234
+ const connectionString = `mysql://${user}:${password}@localhost:${port}/${database}`;
235
+
236
+ try {
237
+ return await testFn(container, connectionString);
238
+ } finally {
239
+ await container.cleanup();
240
+ }
241
+ }
242
+ }