@devries-cameron20 / composio-1 / commits / c0258b8ff
Fork 0

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', () => {