Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
refactor(ts/e2e): unify runFixture and runFixtureWith into single API
- Replace runFixture(path) and runFixtureWith({ pre, fixture }) with unified runFixture({ filename, setup? }) - Rename 'pre' to 'setup' for clarity - Make setup optional - when omitted, runs fixture directly without Docker volumes (smart mode) - Rename E2ETestResultWithPre to E2ETestResultWithSetup - Update PhaseResult.phase type from 'pre' | 'fixture' to 'setup' | 'fixture' - Migrate all test files to new API - Add Docker volume management utilities
jkomyno committed
Jan 30, 2026 at 18:24 UTC
c0258b8ffe54d0c1572a1975e513122464933101
9 files changed
+595
-84
ts/e2e-tests/_utils/src/image-lifecycle.ts
+30
-2
@@ -20,7 +20,7 @@ interface ExecOptions {
20
}
21
22
/**
23
- * Docker mount configuration.
23
+ * Docker bind mount configuration.
24
*/
25
export interface DockerMount {
26
source: string;
@@ -28,6 +28,18 @@ export interface DockerMount {
28
readonly?: boolean;
29
}
30
31
+/**
32
+ * Docker named volume mount configuration.
33
+ */
34
+export interface DockerVolumeMount {
35
+ /** Named volume name (must be created with `docker volume create` first) */
36
+ volume: string;
37
+ /** Container path to mount the volume at */
38
+ target: string;
39
+ /** Whether to mount read-only */
40
+ readonly?: boolean;
41
+}
42
+
43
/**
44
* Options for running a Node container.
45
*/
@@ -36,6 +48,8 @@ export interface RunNodeContainerOptions {
48
cmd: string | string[];
49
cwd?: string;
50
mounts?: DockerMount[];
51
+ /** Named volume mounts (volumes must be created beforehand with `docker volume create`) */
52
+ volumes?: DockerVolumeMount[];
53
env?: Record<string, string | undefined>;
54
labels?: Record<string, string>;
55
name?: string;
@@ -186,7 +200,7 @@ export async function ensureNodeImage(
200
* Runs a command in a Node Docker container.
201
*/
202
export async function runNodeContainer(options: RunNodeContainerOptions): Promise<ExecResult> {
189
- const { imageTag, cmd, cwd, mounts, env, labels, name } = options;
203
+ const { imageTag, cmd, cwd, mounts, volumes, env, labels, name } = options;
204
205
// Validate imageTag is provided, as it determines which Docker image to run.
206
if (!imageTag || typeof imageTag !== 'string') {
@@ -233,6 +247,20 @@ export async function runNodeContainer(options: RunNodeContainerOptions): Promis
247
}
248
}
249
250
+ // Configure named volume mounts for sharing state between container runs.
251
+ if (volumes) {
252
+ for (const v of volumes) {
253
+ // Ensure each volume mount has required volume name and target path.
254
+ if (!v?.volume || !v?.target) {
255
+ throw new Error('runNodeContainer(...): each volume must have { volume, target }');
256
+ }
257
+ const parts = [`type=volume`, `src=${v.volume}`, `dst=${v.target}`];
258
+ // Mark mount as read-only if specified.
259
+ if (v.readonly) parts.push('readonly');
260
+ dockerArgs.push('--mount', parts.join(','));
261
+ }
262
+ }
263
+
264
dockerArgs.push(imageTag);
265
266
// Handle cmd as array for direct execution without shell interpretation.
ts/e2e-tests/_utils/src/index.ts
+1
-1
@@ -1,3 +1,3 @@
1
-export type { E2EConfig, E2ETestResult, DefineTestsContext, NodeVersionMeta as NodeVersion, SkipInCI } from './types';
1
+export type { E2EConfig, E2ETestResult, E2ETestResultWithSetup, RunFixtureOptions, DefineTestsContext, NodeVersionMeta as NodeVersion, SkipInCI } from './types';
2
export { e2e } from './e2e';
3
export { sanitizeOutput } from './sanitize';
ts/e2e-tests/_utils/src/runner.ts
+424
-66
@@ -1,56 +1,228 @@
1
-import { describe, beforeAll, it } from 'bun:test';
2
-import { appendFile } from 'node:fs/promises';
1
+import { describe, beforeAll, afterAll, it } from 'bun:test';
2
+import { appendFile, writeFile } from 'node:fs/promises';
3
import { resolve } from 'node:path';
4
-import type { E2EConfig, E2ETestResult, NodeVersionMeta } from './types';
4
+import type { E2EConfig, E2ETestResult, E2ETestResultWithSetup, NodeVersionMeta, RunFixtureOptions } from './types';
5
import { getRepoRoot, resolveNodeVersionMetaList } from './config';
6
import { ensureNodeImage, runNodeContainer } from './image-lifecycle';
7
-import { WELL_KNOWN_ENV_VARS } from './const'
7
+import { WELL_KNOWN_ENV_VARS } from './const';
8
+import { createVolume, generateVolumeName, initializeVolumeOwnership, removeVolume } from './volume';
9
+
10
+// ============================================================================
11
+// DEBUG.log Manager - Structured logging for e2e test output
12
+// ============================================================================
13
+
14
+/**
15
+ * Result of a single phase execution.
16
+ */
17
+interface PhaseResult {
18
+ phase: 'setup' | 'fixture';
19
+ phaseIndex: number;
20
+ totalPhases: number;
21
+ command: string;
22
+ containerName: string;
23
+ durationMs: number;
24
+ exitCode: number;
25
+ stdout: string;
26
+ stderr: string;
27
+}
28
+
29
+/**
30
+ * Aggregated results for a Node version.
31
+ */
32
+interface VersionResult {
33
+ version: string;
34
+ status: 'pass' | 'fail' | 'skipped';
35
+ reason?: string;
36
+ imageTag?: string;
37
+ phases: PhaseResult[];
38
+ totalDurationMs?: number;
39
+}
40
+
41
+/**
42
+ * Configuration for DebugLogManager.
43
+ */
44
+interface DebugLogManagerOptions {
45
+ logPath: string;
46
+ suiteName: string;
47
+ testFilePath: string;
48
+ nodeVersions: string[];
49
+}
50
+
51
+/**
52
+ * Manages structured DEBUG.log output for e2e tests.
53
+ * Clears the file at initialization, groups phases by Node version,
54
+ * and writes a summary at the end.
55
+ */
56
+class DebugLogManager {
57
+ private versionResults: VersionResult[] = [];
58
+ private startTime: Date;
59
+ private initialized = false;
60
+
61
+ constructor(private options: DebugLogManagerOptions) {
62
+ this.startTime = new Date();
63
+ }
64
+
65
+ /**
66
+ * Initialize the log file - clears it and writes the header.
67
+ * Must be called before any version sections are written.
68
+ */
69
+ async initialize(): Promise<void> {
70
+ if (this.initialized) return;
71
+ const header = this.formatHeader();
72
+ await writeFile(this.options.logPath, header, 'utf-8');
73
+ this.initialized = true;
74
+ }
75
+
76
+ /**
77
+ * Write a version section to the log file.
78
+ * Call this after all phases for a version have completed.
79
+ */
80
+ async writeVersionSection(result: VersionResult): Promise<void> {
81
+ // Ensure initialized (lazy init if needed)
82
+ if (!this.initialized) {
83
+ await this.initialize();
84
+ }
85
+ this.versionResults.push(result);
86
+ const section = this.formatVersionSection(result);
87
+ await appendFile(this.options.logPath, section, 'utf-8');
88
+ }
89
+
90
+ /**
91
+ * Write the summary section to the log file.
92
+ * Call this after all versions have completed.
93
+ */
94
+ async writeSummary(): Promise<void> {
95
+ const summary = this.formatSummary();
96
+ await appendFile(this.options.logPath, summary, 'utf-8');
97
+ }
98
+
99
+ private formatHeader(): string {
100
+ const divider = '='.repeat(80);
101
+ return [
102
+ divider,
103
+ `E2E Test: ${this.options.suiteName}`,
104
+ `Started: ${this.startTime.toISOString()}`,
105
+ `Test file: ${this.options.testFilePath}`,
106
+ `Node versions: ${this.options.nodeVersions.join(', ')}`,
107
+ divider,
108
+ '',
109
+ ].join('\n');
110
+ }
111
+
112
+ private formatVersionSection(result: VersionResult): string {
113
+ const dividerHeavy = '#'.repeat(80);
114
+ const lines: string[] = [
115
+ '',
116
+ dividerHeavy,
117
+ `### Node.js ${result.version}${result.status === 'skipped' ? ' (SKIPPED)' : ''}`,
118
+ dividerHeavy,
119
+ ];
120
+
121
+ if (result.status === 'skipped') {
122
+ lines.push(`Reason: ${result.reason || 'No reason provided'}`);
123
+ } else {
124
+ if (result.imageTag) {
125
+ lines.push(`Image: ${result.imageTag}`);
126
+ }
127
+ lines.push(''); // blank line before phases
128
+
129
+ for (const phase of result.phases) {
130
+ lines.push(...this.formatPhase(phase));
131
+ }
132
+ }
133
+
134
+ lines.push('');
135
+ return lines.join('\n');
136
+ }
137
+
138
+ private formatPhase(phase: PhaseResult): string[] {
139
+ const exitStatus = phase.exitCode === 0 ? 'success' : 'failure';
140
+ const durationSec = (phase.durationMs / 1000).toFixed(2);
141
+
142
+ return [
143
+ `--- Phase ${phase.phaseIndex}/${phase.totalPhases}: ${phase.phase} ---`,
144
+ `Container: ${phase.containerName}`,
145
+ `Command: ${phase.command}`,
146
+ `Duration: ${durationSec}s`,
147
+ `Exit Code: ${phase.exitCode} (${exitStatus})`,
148
+ '',
149
+ '[stdout]',
150
+ phase.stdout?.trim() || '(empty)',
151
+ '',
152
+ '[stderr]',
153
+ phase.stderr?.trim() || '(empty)',
154
+ '',
155
+ ];
156
+ }
157
+
158
+ private formatSummary(): string {
159
+ const divider = '='.repeat(80);
160
+ const endTime = new Date();
161
+ const totalDurationMs = endTime.getTime() - this.startTime.getTime();
162
+ const totalDurationSec = (totalDurationMs / 1000).toFixed(2);
163
+
164
+ const lines: string[] = [
165
+ divider,
166
+ 'Summary',
167
+ divider,
168
+ ];
169
+
170
+ for (const result of this.versionResults) {
171
+ if (result.status === 'skipped') {
172
+ lines.push(`Node.js ${result.version}: SKIPPED`);
173
+ } else {
174
+ const status = result.status.toUpperCase();
175
+ const phaseCount = result.phases.length;
176
+ const versionDurationSec = result.totalDurationMs
177
+ ? (result.totalDurationMs / 1000).toFixed(2)
178
+ : '?';
179
+ lines.push(`Node.js ${result.version}: ${status} (${phaseCount} phases, ${versionDurationSec}s total)`);
180
+ }
181
+ }
182
+
183
+ lines.push('');
184
+ lines.push(`Finished: ${endTime.toISOString()}`);
185
+ lines.push(`Total duration: ${totalDurationSec}s`);
186
+ lines.push(divider);
187
+ lines.push('');
188
+
189
+ return lines.join('\n');
190
+ }
191
+}
192
+
193
+// ============================================================================
194
+// Legacy debug log support (for backward compatibility with runCmd)
195
+// ============================================================================
196
197
/**
198
* Debug log entry metadata.
199
+ * @deprecated Use DebugLogManager for new code
200
*/
201
interface DebugLogEntry {
202
nodeVersion: string;
203
command: string;
204
containerName: string;
205
result: E2ETestResult;
206
+ /** Optional phase indicator for multi-step operations */
207
+ phase?:
208
+ // Setup phase before fixture is run, often used for install commands
209
+ | 'setup'
210
+ // Actual test fixture phase
211
+ | 'fixture';
212
}
213
214
/**
215
* Writes Docker run output to DEBUG.log in the test directory.
21
- * Appends to the file so multiple test runs are preserved.
22
- *
23
- * @param repoRoot - Absolute path to the repository root
24
- * @param testDirRelative - Path to test directory relative to repo root
25
- * @param entry - Debug log entry with command and result metadata
216
+ * @deprecated Use DebugLogManager for new code - this is kept for runCmd() compatibility
217
*/
218
async function writeDebugLog(
28
- repoRoot: string,
29
- testDirRelative: string,
30
- entry: DebugLogEntry
219
+ _repoRoot: string,
220
+ _testDirRelative: string,
221
+ _entry: DebugLogEntry
222
): Promise<void> {
32
- const logPath = resolve(repoRoot, testDirRelative, 'DEBUG.log');
33
- const timestamp = new Date().toISOString();
34
-
35
- const content = [
36
- '',
37
- `=== Docker Run: ${timestamp} ===`,
38
- `Node.js: ${entry.nodeVersion}`,
39
- `Command: ${entry.command}`,
40
- `Container: ${entry.containerName}`,
41
- `Exit Code: ${entry.result.exitCode}`,
42
- '',
43
- '--- stdout ---',
44
- entry.result.stdout || '(empty)',
45
- '',
46
- '--- stderr ---',
47
- entry.result.stderr || '(empty)',
48
- '',
49
- `=== End (Exit Code: ${entry.result.exitCode}) ===`,
50
- '',
51
- ].join('\n');
52
-
53
- await appendFile(logPath, content);
223
+ // No-op: logging is now handled by DebugLogManager at the version level
224
+ // The runCmd function still calls this for API compatibility, but actual
225
+ // logging happens through writeVersionSection in runFixture
226
}
227
228
/**
@@ -110,44 +282,190 @@ interface RunE2EInternalConfig extends E2EConfig {
282
suiteName: string;
283
}
284
285
+/**
286
+ * Context for tracking phase results within a version.
287
+ */
288
+interface VersionExecutionContext {
289
+ phases: PhaseResult[];
290
+ versionStartTime: number;
291
+ imageTag: string;
292
+}
293
+
294
/**
295
* Creates Docker execution utilities for a specific Node version.
296
+ * Now tracks phase results for the DebugLogManager.
297
*/
298
function createDockerExecutors(
299
config: RunE2EInternalConfig,
300
nodeVersion: string,
301
imageTag: string,
120
- repoRoot: string
302
+ repoRoot: string,
303
+ logManager: DebugLogManager
304
) {
122
- const { cwd, suiteName, env } = config;
305
+ const { cwd, suiteName, env, usesFixtures } = config;
306
const containerEnv = buildContainerEnv(env);
307
308
+ // Compute effective cwd based on usesFixtures flag
309
+ const effectiveCwd = usesFixtures ? `${cwd}/fixtures` : cwd;
310
+
311
+ // Track execution context for this version
312
+ const context: VersionExecutionContext = {
313
+ phases: [],
314
+ versionStartTime: Date.now(),
315
+ imageTag,
316
+ };
317
+
318
const runCmd = async (command: string): Promise<E2ETestResult> => {
319
const containerName = `e2e-${suiteName}-${nodeVersion.replace(/\./g, '-')}-${Date.now()}`;
320
+ const startTime = Date.now();
321
+
322
const result = await runNodeContainer({
323
imageTag,
324
cmd: command,
130
- cwd,
325
+ cwd: effectiveCwd,
326
env: containerEnv,
327
name: containerName,
328
});
329
135
- // Write output to DEBUG.log for debugging and CI troubleshooting
136
- await writeDebugLog(repoRoot, cwd, {
137
- nodeVersion,
330
+ const durationMs = Date.now() - startTime;
331
+
332
+ // Track as a standalone phase (not pre/fixture)
333
+ context.phases.push({
334
+ phase: 'fixture',
335
+ phaseIndex: context.phases.length + 1,
336
+ totalPhases: context.phases.length + 1, // Updated later if more phases
337
command,
338
containerName,
140
- result,
339
+ durationMs,
340
+ exitCode: result.exitCode,
341
+ stdout: result.stdout,
342
+ stderr: result.stderr,
343
});
344
345
return result;
346
};
347
146
- const runFixture = async (fixturePath: string): Promise<E2ETestResult> => {
147
- return runCmd(`node ${fixturePath}`);
348
+ /**
349
+ * Unified fixture runner with optional setup phase.
350
+ *
351
+ * Without setup: Runs `node <filename>` directly (no Docker volumes).
352
+ * With setup: Creates a Docker volume, runs setup command with volume mounted
353
+ * read-write, then runs the fixture with volume mounted read-only.
354
+ */
355
+ const runFixture = async (options: RunFixtureOptions): Promise<E2ETestResult | E2ETestResultWithSetup> => {
356
+ const { filename, setup } = options;
357
+
358
+ // Smart mode: no setup (or empty string) = no volumes, just run directly
359
+ if (!setup) {
360
+ return runCmd(`node ${filename}`);
361
+ }
362
+
363
+ // With setup: use Docker volumes
364
+ const volumeName = generateVolumeName(suiteName, nodeVersion);
365
+ const containerBaseName = `e2e-${suiteName}-${nodeVersion.replace(/\./g, '-')}-${Date.now()}`;
366
+
367
+ // The volume mounts at node_modules relative to the effective cwd
368
+ const volumeTarget = `${effectiveCwd.startsWith('/') ? effectiveCwd : `/app/${effectiveCwd}`}/node_modules`;
369
+
370
+ try {
371
+ // 1. Create volume
372
+ await createVolume(volumeName);
373
+
374
+ // 2. Initialize volume with correct ownership for node user (UID 1000)
375
+ await initializeVolumeOwnership(volumeName, imageTag);
376
+
377
+ // 3. Run setup command with volume mounted read-write
378
+ const setupContainerName = `${containerBaseName}-setup`;
379
+ const setupStartTime = Date.now();
380
+ const setupResult = await runNodeContainer({
381
+ imageTag,
382
+ cmd: setup,
383
+ cwd: effectiveCwd,
384
+ env: containerEnv,
385
+ name: setupContainerName,
386
+ volumes: [{
387
+ volume: volumeName,
388
+ target: volumeTarget,
389
+ readonly: false,
390
+ }],
391
+ });
392
+ const setupDurationMs = Date.now() - setupStartTime;
393
+
394
+ // Track setup phase
395
+ context.phases.push({
396
+ phase: 'setup',
397
+ phaseIndex: 1,
398
+ totalPhases: 2,
399
+ command: setup,
400
+ containerName: setupContainerName,
401
+ durationMs: setupDurationMs,
402
+ exitCode: setupResult.exitCode,
403
+ stdout: setupResult.stdout,
404
+ stderr: setupResult.stderr,
405
+ });
406
+
407
+ // 4. Run fixture with volume mounted read-only (runs regardless of setup exit code)
408
+ const fixtureContainerName = `${containerBaseName}-fixture`;
409
+ const fixtureStartTime = Date.now();
410
+ const fixtureResult = await runNodeContainer({
411
+ imageTag,
412
+ cmd: `node ${filename}`,
413
+ cwd: effectiveCwd,
414
+ env: containerEnv,
415
+ name: fixtureContainerName,
416
+ volumes: [{
417
+ volume: volumeName,
418
+ target: volumeTarget,
419
+ readonly: true,
420
+ }],
421
+ });
422
+ const fixtureDurationMs = Date.now() - fixtureStartTime;
423
+
424
+ // Track fixture phase
425
+ context.phases.push({
426
+ phase: 'fixture',
427
+ phaseIndex: 2,
428
+ totalPhases: 2,
429
+ command: `node ${filename}`,
430
+ containerName: fixtureContainerName,
431
+ durationMs: fixtureDurationMs,
432
+ exitCode: fixtureResult.exitCode,
433
+ stdout: fixtureResult.stdout,
434
+ stderr: fixtureResult.stderr,
435
+ });
436
+
437
+ // 5. Return combined result (top-level is fixture result)
438
+ return {
439
+ ...fixtureResult,
440
+ setup: setupResult,
441
+ };
442
+ } finally {
443
+ // 6. Always cleanup volume (best-effort, doesn't throw)
444
+ await removeVolume(volumeName);
445
+ }
446
+ };
447
+
448
+ /**
449
+ * Finalize this version's log output.
450
+ * Call this after all test phases have completed.
451
+ */
452
+ const finalizeVersionLog = async (): Promise<void> => {
453
+ const totalDurationMs = Date.now() - context.versionStartTime;
454
+
455
+ // Determine overall status based on exit codes
456
+ const allPassed = context.phases.every(p => p.exitCode === 0);
457
+ const status: 'pass' | 'fail' = allPassed ? 'pass' : 'fail';
458
+
459
+ await logManager.writeVersionSection({
460
+ version: nodeVersion,
461
+ status,
462
+ imageTag: context.imageTag,
463
+ phases: context.phases,
464
+ totalDurationMs,
465
+ });
466
};
467
150
- return { runCmd, runFixture };
468
+ return { runCmd, runFixture, finalizeVersionLog, context };
469
}
470
471
/**
@@ -158,7 +476,7 @@ function createDockerExecutors(
476
* Each version's skipInCI state is computed by resolveNodeVersionMetaList().
477
*/
478
export function runE2E(config: RunE2EInternalConfig): void {
161
- const { suiteName, defineTests, env } = config;
479
+ const { cwd, suiteName, defineTests, env } = config;
480
481
// Validate env vars early, before any Docker operations
482
validateRequiredEnvVars(env, suiteName);
@@ -166,6 +484,16 @@ export function runE2E(config: RunE2EInternalConfig): void {
484
const nodeVersionMetaList = resolveNodeVersionMetaList(config.nodeVersions);
485
const repoRoot = getRepoRoot();
486
487
+ // Create the debug log manager for structured output
488
+ const logPath = resolve(repoRoot, cwd, 'DEBUG.log');
489
+ const allVersions = nodeVersionMetaList.map(v => v.value);
490
+ const logManager = new DebugLogManager({
491
+ logPath,
492
+ suiteName,
493
+ testFilePath: `${cwd}/e2e.test.ts`,
494
+ nodeVersions: allVersions,
495
+ });
496
+
497
function renderNodeVersionMeta({ kind, value }: NodeVersionMeta) {
498
switch (kind) {
499
case 'current':
@@ -177,31 +505,61 @@ export function runE2E(config: RunE2EInternalConfig): void {
505
}
506
}
507
180
- for (const nodeVersionMeta of nodeVersionMetaList) {
181
- const testName = `${suiteName} (${renderNodeVersionMeta(nodeVersionMeta)})`;
508
+ // Wrap all tests in a top-level describe to handle initialization and summary
509
+ describe(suiteName, () => {
510
+ // Initialize log file before any tests run
511
+ beforeAll(async () => {
512
+ await logManager.initialize();
513
+ });
514
+
515
+ for (const nodeVersionMeta of nodeVersionMetaList) {
516
+ const testName = renderNodeVersionMeta(nodeVersionMeta);
517
183
- // Skip this version in CI if not selected
184
- if (nodeVersionMeta.skip.value) {
185
- describe.skip(`${testName} - skipped: ${nodeVersionMeta.skip.reason}`, () => {
186
- it('this version should not run in this CI matrix job', () => {});
187
- });
188
- continue;
189
- }
518
+ // Skip this version in CI if not selected
519
+ if (nodeVersionMeta.skip.value) {
520
+ describe(`${testName} - skipped: ${nodeVersionMeta.skip.reason}`, () => {
521
+ beforeAll(async () => {
522
+ // Write skip marker to log
523
+ await logManager.writeVersionSection({
524
+ version: nodeVersionMeta.value,
525
+ status: 'skipped',
526
+ reason: nodeVersionMeta.skip.reason || 'Skipped in CI',
527
+ phases: [],
528
+ });
529
+ });
530
191
- describe(testName, () => {
192
- let executors: ReturnType<typeof createDockerExecutors>;
531
+ it('this version should not run in this CI matrix job', () => {});
532
+ });
533
+ continue;
534
+ }
535
194
- // Ensure Docker image exists before tests run
195
- beforeAll(async () => {
196
- const imageTag = await ensureNodeImage(nodeVersionMeta.value, { repoRoot });
197
- executors = createDockerExecutors(config, nodeVersionMeta.value, imageTag, repoRoot);
198
- }, 600_000); // 10 minute timeout for Docker image build
536
+ describe(testName, () => {
537
+ let executors: ReturnType<typeof createDockerExecutors>;
538
200
- // Call user's defineTests with bun:test functions and Docker utilities
201
- defineTests({
202
- runCmd: (cmd) => executors.runCmd(cmd),
203
- runFixture: (path) => executors.runFixture(path),
539
+ // Ensure Docker image exists before tests run
540
+ beforeAll(async () => {
541
+ const imageTag = await ensureNodeImage(nodeVersionMeta.value, { repoRoot });
542
+ executors = createDockerExecutors(config, nodeVersionMeta.value, imageTag, repoRoot, logManager);
543
+ }, 600_000); // 10 minute timeout for Docker image build
544
+
545
+ // Call user's defineTests with bun:test functions and Docker utilities
546
+ defineTests({
547
+ runCmd: (cmd) => executors.runCmd(cmd),
548
+ runFixture: (opts) => executors.runFixture(opts),
549
+ });
550
+
551
+ // Write version section after all tests for this version complete
552
+ afterAll(async () => {
553
+ if (executors) {
554
+ await executors.finalizeVersionLog();
555
+ }
556
+ });
557
});
558
+ }
559
+
560
+ // Write summary after all versions complete
561
+ afterAll(async () => {
562
+ await logManager.writeSummary();
563
});
206
- }
564
+ });
565
}
ts/e2e-tests/_utils/src/types.ts
+56
-4
@@ -31,14 +31,55 @@ export interface E2ETestResult {
31
stderr: string;
32
}
33
34
+/**
35
+ * Result of runFixture when a setup command is provided.
36
+ * Top-level fields (exitCode, stdout, stderr) reflect the fixture result.
37
+ */
38
+export interface E2ETestResultWithSetup extends E2ETestResult {
39
+ /** Result of the setup command execution */
40
+ setup: E2ETestResult;
41
+}
42
+
43
+/**
44
+ * Options for runFixture.
45
+ */
46
+export interface RunFixtureOptions {
47
+ /** Fixture file path relative to cwd (e.g., 'index.mjs') */
48
+ filename: string;
49
+ /** Optional setup command to run before the fixture (e.g., 'npm install --legacy-peer-deps') */
50
+ setup?: string;
51
+}
52
+
53
/**
54
* Context passed to defineTests callback.
55
*/
56
export interface DefineTestsContext {
57
/** Run an arbitrary command in the Docker container */
58
runCmd: (command: string) => Promise<E2ETestResult>;
40
- /** Run a fixture file with Node.js (equivalent to runCmd(`node ${path}`)) */
41
- runFixture: (fixturePath: string) => Promise<E2ETestResult>;
59
+ /**
60
+ * Run a fixture file with Node.js.
61
+ *
62
+ * Without setup: Runs `node <filename>` directly (no Docker volumes).
63
+ * Returns E2ETestResult.
64
+ *
65
+ * With setup: Creates a Docker volume, runs the setup command (e.g., npm install)
66
+ * with the volume mounted read-write, then runs the fixture with the volume
67
+ * mounted read-only. Both commands run regardless of exit codes.
68
+ * Returns E2ETestResultWithSetup.
69
+ *
70
+ * @example
71
+ * // Simple fixture (no setup needed)
72
+ * const result = await runFixture({ filename: 'test.mjs' });
73
+ *
74
+ * @example
75
+ * // Fixture with setup (uses Docker volumes)
76
+ * const result = await runFixture({
77
+ * filename: 'index.mjs',
78
+ * setup: 'npm install --legacy-peer-deps',
79
+ * }) as E2ETestResultWithSetup;
80
+ * expect(result.setup.exitCode).toBe(0);
81
+ */
82
+ runFixture: (options: RunFixtureOptions) => Promise<E2ETestResult | E2ETestResultWithSetup>;
83
}
84
85
/**
@@ -57,17 +98,28 @@ export interface E2EConfig {
98
*/
99
env?: Record<string, string | undefined>;
100
101
+ /**
102
+ * When true, sets the working directory to {testDir}/fixtures for Docker commands.
103
+ * This affects:
104
+ * - Volume mount location (fixtures/node_modules instead of testDir/node_modules)
105
+ * - Command execution cwd
106
+ * - Fixture paths in runFixture (relative to fixtures/)
107
+ *
108
+ * @default false
109
+ */
110
+ usesFixtures?: boolean;
111
+
112
/**
113
* Define your tests using bun:test primitives.
114
* Called once per Node version during test registration.
115
*
116
* @example
117
* ```typescript
66
- * defineTests: ({ describe, it, expect, beforeAll, runFixture }) => {
118
+ * defineTests: ({ runFixture }) => {
119
* let result: E2ETestResult;
120
*
121
* beforeAll(async () => {
70
- * result = await runFixture('fixtures/test.mjs');
122
+ * result = await runFixture({ filename: 'fixtures/test.mjs' });
123
* }, 300_000);
124
*
125
* describe('output', () => {
ts/e2e-tests/_utils/src/volume.ts
new
+70
@@ -0,0 +1,70 @@
1
+import { $ } from 'bun';
2
+
3
+/**
4
+ * Generates a unique volume name for e2e tests.
5
+ * Format: e2e-{suiteName}-{nodeVersion}-{timestamp}
6
+ *
7
+ * @param suiteName - Test suite name
8
+ * @param nodeVersion - Node.js version being tested
9
+ * @returns Unique volume name
10
+ */
11
+export function generateVolumeName(suiteName: string, nodeVersion: string): string {
12
+ const sanitizedSuite = suiteName.replace(/[^a-zA-Z0-9-]/g, '-');
13
+ const sanitizedVersion = nodeVersion.replace(/\./g, '-');
14
+ return `e2e-${sanitizedSuite}-${sanitizedVersion}-${Date.now()}`;
15
+}
16
+
17
+/**
18
+ * Creates a Docker named volume for sharing state between container runs.
19
+ *
20
+ * @param name - Unique volume name
21
+ * @returns The volume name (for use in mounts)
22
+ * @throws If volume creation fails
23
+ */
24
+export async function createVolume(name: string): Promise<string> {
25
+ const result = await $`docker volume create ${name}`.nothrow().quiet();
26
+
27
+ if (result.exitCode !== 0) {
28
+ const err = new Error(`Failed to create Docker volume: ${name}`);
29
+ (err as Error & { cause: Error }).cause = new Error(result.stderr.toString() || result.stdout.toString());
30
+ throw err;
31
+ }
32
+
33
+ return name;
34
+}
35
+
36
+/**
37
+ * Removes a Docker named volume.
38
+ * Logs errors but doesn't throw (cleanup should be best-effort).
39
+ *
40
+ * @param name - Volume name to remove
41
+ */
42
+export async function removeVolume(name: string): Promise<void> {
43
+ const result = await $`docker volume rm ${name}`.nothrow().quiet();
44
+
45
+ if (result.exitCode !== 0) {
46
+ // Log but don't throw - cleanup should be best-effort
47
+ console.warn(`[e2e] Warning: Failed to remove Docker volume ${name}: ${result.stderr.toString()}`);
48
+ }
49
+}
50
+
51
+/**
52
+ * Initializes a Docker volume with correct ownership for the node user (UID 1000).
53
+ * This is necessary because Docker volumes are created with root ownership by default.
54
+ *
55
+ * @param volumeName - Name of the volume to initialize
56
+ * @param imageTag - Docker image to use for the initialization container
57
+ */
58
+export async function initializeVolumeOwnership(
59
+ volumeName: string,
60
+ imageTag: string
61
+): Promise<void> {
62
+ // Run a quick container as root to chown the volume contents
63
+ const result = await $`docker run --rm --user root -v ${volumeName}:/mnt/vol ${imageTag} chown -R node:node /mnt/vol`.nothrow().quiet();
64
+
65
+ if (result.exitCode !== 0) {
66
+ const err = new Error(`Failed to initialize volume ownership for: ${volumeName}`);
67
+ (err as Error & { cause: Error }).cause = new Error(result.stderr.toString() || result.stdout.toString());
68
+ throw err;
69
+ }
70
+}
ts/e2e-tests/runtimes/node/cjs-basic/e2e.test.ts
+1
-1
@@ -19,7 +19,7 @@ e2e(import.meta.url, {
19
let result: E2ETestResult;
20
21
beforeAll(async () => {
22
- result = await runFixture('fixtures/test.cjs');
22
+ result = await runFixture({ filename: 'fixtures/test.cjs' });
23
});
24
25
describe('CommonJS compatibility', () => {
ts/e2e-tests/runtimes/node/esm-basic/e2e.test.ts
+1
-1
@@ -19,7 +19,7 @@ e2e(import.meta.url, {
19
let result: E2ETestResult;
20
21
beforeAll(async () => {
22
- result = await runFixture('fixtures/test.mjs');
22
+ result = await runFixture({ filename: 'fixtures/test.mjs' });
23
});
24
25
describe('ESM compatibility', () => {
ts/e2e-tests/runtimes/node/openai-zod4-compat/e2e.test.ts
+11
-8
@@ -5,7 +5,7 @@
5
* specifically testing the fix for https://github.com/ComposioHQ/composio/issues/2336
6
*/
7
8
-import { e2e, type E2ETestResult } from '@e2e-tests/utils';
8
+import { e2e, type E2ETestResultWithSetup } from '@e2e-tests/utils';
9
import { describe, it, expect, beforeAll } from 'bun:test';
10
11
declare module 'bun' {
@@ -16,21 +16,24 @@ declare module 'bun' {
16
17
e2e(import.meta.url, {
18
nodeVersions: ['20.19.0', '22.12.0'],
19
+ usesFixtures: true,
20
env: {
21
COMPOSIO_API_KEY: Bun.env.COMPOSIO_API_KEY,
22
},
22
- defineTests: ({ runCmd }) => {
23
- let result: E2ETestResult;
23
+ defineTests: ({ runFixture }) => {
24
+ let result: E2ETestResultWithSetup;
25
26
beforeAll(async () => {
26
- result = await runCmd(
27
- 'npm --prefix fixtures install --legacy-peer-deps && node fixtures/index.mjs'
28
- );
27
+ result = await runFixture({
28
+ filename: 'index.mjs',
29
+ setup: 'npm install --legacy-peer-deps',
30
+ });
31
});
32
33
describe('setup', () => {
34
it('npm install completes successfully', () => {
33
- expect(result.stdout).toMatch(/added \d+ packages/);
35
+ expect(result.setup.stdout).toMatch(/added \d+ packages/);
36
+ expect(result.setup.exitCode).toBe(0);
37
});
38
});
39
@@ -58,6 +61,6 @@ e2e(import.meta.url, {
61
it('all packages work together', () => {
62
expect(result.stdout).toContain('All packages work together!');
63
});
61
- },);
64
+ });
65
},
66
});
ts/e2e-tests/runtimes/node/typescript-mjs-import-nodenext/e2e.test.ts
+1
-1
@@ -25,7 +25,7 @@ e2e(import.meta.url, {
25
let result: E2ETestResult;
26
27
beforeAll(async () => {
28
- result = await runFixture('fixtures/index.mjs');
28
+ result = await runFixture({ filename: 'fixtures/index.mjs' });
29
}, 300_000);
30
31
describe('TypeScript .mjs import resolution', () => {