Skip to content

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

jkomynoc0258b8ffe54
diff --git a/ts/e2e-tests/_utils/src/image-lifecycle.ts b/ts/e2e-tests/_utils/src/image-lifecycle.ts
index 5d3735884..6baa4ce84 100644
--- a/ts/e2e-tests/_utils/src/image-lifecycle.ts
+++ b/ts/e2e-tests/_utils/src/image-lifecycle.ts
@@ -20,7 +20,7 @@ interface ExecOptions {
}
/**
- * Docker mount configuration.
+ * Docker bind mount configuration.
*/
export interface DockerMount {
source: string;
@@ -28,6 +28,18 @@ export interface DockerMount {
readonly?: boolean;
}
+/**
+ * Docker named volume mount configuration.
+ */
+export interface DockerVolumeMount {
+ /** Named volume name (must be created with `docker volume create` first) */
+ volume: string;
+ /** Container path to mount the volume at */
+ target: string;
+ /** Whether to mount read-only */
+ readonly?: boolean;
+}
+
/**
* Options for running a Node container.
*/
@@ -36,6 +48,8 @@ export interface RunNodeContainerOptions {
cmd: string | string[];
cwd?: string;
mounts?: DockerMount[];
+ /** Named volume mounts (volumes must be created beforehand with `docker volume create`) */
+ volumes?: DockerVolumeMount[];
env?: Record<string, string | undefined>;
labels?: Record<string, string>;
name?: string;
@@ -186,7 +200,7 @@ export async function ensureNodeImage(
* Runs a command in a Node Docker container.
*/
export async function runNodeContainer(options: RunNodeContainerOptions): Promise<ExecResult> {
- const { imageTag, cmd, cwd, mounts, env, labels, name } = options;
+ const { imageTag, cmd, cwd, mounts, volumes, env, labels, name } = options;
// Validate imageTag is provided, as it determines which Docker image to run.
if (!imageTag || typeof imageTag !== 'string') {
@@ -233,6 +247,20 @@ export async function runNodeContainer(options: RunNodeContainerOptions): Promis
}
}
+ // Configure named volume mounts for sharing state between container runs.
+ if (volumes) {
+ for (const v of volumes) {
+ // Ensure each volume mount has required volume name and target path.
+ if (!v?.volume || !v?.target) {
+ throw new Error('runNodeContainer(...): each volume must have { volume, target }');
+ }
+ const parts = [`type=volume`, `src=${v.volume}`, `dst=${v.target}`];
+ // Mark mount as read-only if specified.
+ if (v.readonly) parts.push('readonly');
+ dockerArgs.push('--mount', parts.join(','));
+ }
+ }
+
dockerArgs.push(imageTag);
// Handle cmd as array for direct execution without shell interpretation.
diff --git a/ts/e2e-tests/_utils/src/index.ts b/ts/e2e-tests/_utils/src/index.ts
index 4e0c86c7d..c6d7756e8 100644
--- a/ts/e2e-tests/_utils/src/index.ts
+++ b/ts/e2e-tests/_utils/src/index.ts
@@ -1,3 +1,3 @@
-export type { E2EConfig, E2ETestResult, DefineTestsContext, NodeVersionMeta as NodeVersion, SkipInCI } from './types';
+export type { E2EConfig, E2ETestResult, E2ETestResultWithSetup, RunFixtureOptions, DefineTestsContext, NodeVersionMeta as NodeVersion, SkipInCI } from './types';
export { e2e } from './e2e';
export { sanitizeOutput } from './sanitize';
diff --git a/ts/e2e-tests/_utils/src/runner.ts b/ts/e2e-tests/_utils/src/runner.ts
index f13dd5540..165e8917f 100644
--- a/ts/e2e-tests/_utils/src/runner.ts
+++ b/ts/e2e-tests/_utils/src/runner.ts
@@ -1,56 +1,228 @@
-import { describe, beforeAll, it } from 'bun:test';
-import { appendFile } from 'node:fs/promises';
+import { describe, beforeAll, afterAll, it } from 'bun:test';
+import { appendFile, writeFile } from 'node:fs/promises';
import { resolve } from 'node:path';
-import type { E2EConfig, E2ETestResult, NodeVersionMeta } from './types';
+import type { E2EConfig, E2ETestResult, E2ETestResultWithSetup, NodeVersionMeta, RunFixtureOptions } from './types';
import { getRepoRoot, resolveNodeVersionMetaList } from './config';
import { ensureNodeImage, runNodeContainer } from './image-lifecycle';
-import { WELL_KNOWN_ENV_VARS } from './const'
+import { WELL_KNOWN_ENV_VARS } from './const';
+import { createVolume, generateVolumeName, initializeVolumeOwnership, removeVolume } from './volume';
+
+// ============================================================================
+// DEBUG.log Manager - Structured logging for e2e test output
+// ============================================================================
+
+/**
+ * Result of a single phase execution.
+ */
+interface PhaseResult {
+ phase: 'setup' | 'fixture';
+ phaseIndex: number;
+ totalPhases: number;
+ command: string;
+ containerName: string;
+ durationMs: number;
+ exitCode: number;
+ stdout: string;
+ stderr: string;
+}
+
+/**
+ * Aggregated results for a Node version.
+ */
+interface VersionResult {
+ version: string;
+ status: 'pass' | 'fail' | 'skipped';
+ reason?: string;
+ imageTag?: string;
+ phases: PhaseResult[];
+ totalDurationMs?: number;
+}
+
+/**
+ * Configuration for DebugLogManager.
+ */
+interface DebugLogManagerOptions {
+ logPath: string;
+ suiteName: string;
+ testFilePath: string;
+ nodeVersions: string[];
+}
+
+/**
+ * Manages structured DEBUG.log output for e2e tests.
+ * Clears the file at initialization, groups phases by Node version,
+ * and writes a summary at the end.
+ */
+class DebugLogManager {
+ private versionResults: VersionResult[] = [];
+ private startTime: Date;
+ private initialized = false;
+
+ constructor(private options: DebugLogManagerOptions) {
+ this.startTime = new Date();
+ }
+
+ /**
+ * Initialize the log file - clears it and writes the header.
+ * Must be called before any version sections are written.
+ */
+ async initialize(): Promise<void> {
+ if (this.initialized) return;
+ const header = this.formatHeader();
+ await writeFile(this.options.logPath, header, 'utf-8');
+ this.initialized = true;
+ }
+
+ /**
+ * Write a version section to the log file.
+ * Call this after all phases for a version have completed.
+ */
+ async writeVersionSection(result: VersionResult): Promise<void> {
+ // Ensure initialized (lazy init if needed)
+ if (!this.initialized) {
+ await this.initialize();
+ }
+ this.versionResults.push(result);
+ const section = this.formatVersionSection(result);
+ await appendFile(this.options.logPath, section, 'utf-8');
+ }
+
+ /**
+ * Write the summary section to the log file.
+ * Call this after all versions have completed.
+ */
+ async writeSummary(): Promise<void> {
+ const summary = this.formatSummary();
+ await appendFile(this.options.logPath, summary, 'utf-8');
+ }
+
+ private formatHeader(): string {
+ const divider = '='.repeat(80);
+ return [
+ divider,
+ `E2E Test: ${this.options.suiteName}`,
+ `Started: ${this.startTime.toISOString()}`,
+ `Test file: ${this.options.testFilePath}`,
+ `Node versions: ${this.options.nodeVersions.join(', ')}`,
+ divider,
+ '',
+ ].join('\n');
+ }
+
+ private formatVersionSection(result: VersionResult): string {
+ const dividerHeavy = '#'.repeat(80);
+ const lines: string[] = [
+ '',
+ dividerHeavy,
+ `### Node.js ${result.version}${result.status === 'skipped' ? ' (SKIPPED)' : ''}`,
+ dividerHeavy,
+ ];
+
+ if (result.status === 'skipped') {
+ lines.push(`Reason: ${result.reason || 'No reason provided'}`);
+ } else {
+ if (result.imageTag) {
+ lines.push(`Image: ${result.imageTag}`);
+ }
+ lines.push(''); // blank line before phases
+
+ for (const phase of result.phases) {
+ lines.push(...this.formatPhase(phase));
+ }
+ }
+
+ lines.push('');
+ return lines.join('\n');
+ }
+
+ private formatPhase(phase: PhaseResult): string[] {
+ const exitStatus = phase.exitCode === 0 ? 'success' : 'failure';
+ const durationSec = (phase.durationMs / 1000).toFixed(2);
+
+ return [
+ `--- Phase ${phase.phaseIndex}/${phase.totalPhases}: ${phase.phase} ---`,
+ `Container: ${phase.containerName}`,
+ `Command: ${phase.command}`,
+ `Duration: ${durationSec}s`,
+ `Exit Code: ${phase.exitCode} (${exitStatus})`,
+ '',
+ '[stdout]',
+ phase.stdout?.trim() || '(empty)',
+ '',
+ '[stderr]',
+ phase.stderr?.trim() || '(empty)',
+ '',
+ ];
+ }
+
+ private formatSummary(): string {
+ const divider = '='.repeat(80);
+ const endTime = new Date();
+ const totalDurationMs = endTime.getTime() - this.startTime.getTime();
+ const totalDurationSec = (totalDurationMs / 1000).toFixed(2);
+
+ const lines: string[] = [
+ divider,
+ 'Summary',
+ divider,
+ ];
+
+ for (const result of this.versionResults) {
+ if (result.status === 'skipped') {
+ lines.push(`Node.js ${result.version}: SKIPPED`);
+ } else {
+ const status = result.status.toUpperCase();
+ const phaseCount = result.phases.length;
+ const versionDurationSec = result.totalDurationMs
+ ? (result.totalDurationMs / 1000).toFixed(2)
+ : '?';
+ lines.push(`Node.js ${result.version}: ${status} (${phaseCount} phases, ${versionDurationSec}s total)`);
+ }
+ }
+
+ lines.push('');
+ lines.push(`Finished: ${endTime.toISOString()}`);
+ lines.push(`Total duration: ${totalDurationSec}s`);
+ lines.push(divider);
+ lines.push('');
+
+ return lines.join('\n');
+ }
+}
+
+// ============================================================================
+// Legacy debug log support (for backward compatibility with runCmd)
+// ============================================================================
/**
* Debug log entry metadata.
+ * @deprecated Use DebugLogManager for new code
*/
interface DebugLogEntry {
nodeVersion: string;
command: string;
containerName: string;
result: E2ETestResult;
+ /** Optional phase indicator for multi-step operations */
+ phase?:
+ // Setup phase before fixture is run, often used for install commands
+ | 'setup'
+ // Actual test fixture phase
+ | 'fixture';
}
/**
* Writes Docker run output to DEBUG.log in the test directory.
- * Appends to the file so multiple test runs are preserved.
- *
- * @param repoRoot - Absolute path to the repository root
- * @param testDirRelative - Path to test directory relative to repo root
- * @param entry - Debug log entry with command and result metadata
+ * @deprecated Use DebugLogManager for new code - this is kept for runCmd() compatibility
*/
async function writeDebugLog(
- repoRoot: string,
- testDirRelative: string,
- entry: DebugLogEntry
+ _repoRoot: string,
+ _testDirRelative: string,
+ _entry: DebugLogEntry
): Promise<void> {
- const logPath = resolve(repoRoot, testDirRelative, 'DEBUG.log');
- const timestamp = new Date().toISOString();
-
- const content = [
- '',
- `=== Docker Run: ${timestamp} ===`,
- `Node.js: ${entry.nodeVersion}`,
- `Command: ${entry.command}`,
- `Container: ${entry.containerName}`,
- `Exit Code: ${entry.result.exitCode}`,
- '',
- '--- stdout ---',
- entry.result.stdout || '(empty)',
- '',
- '--- stderr ---',
- entry.result.stderr || '(empty)',
- '',
- `=== End (Exit Code: ${entry.result.exitCode}) ===`,
- '',
- ].join('\n');
-
- await appendFile(logPath, content);
+ // No-op: logging is now handled by DebugLogManager at the version level
+ // The runCmd function still calls this for API compatibility, but actual
+ // logging happens through writeVersionSection in runFixture
}
/**
@@ -110,44 +282,190 @@ interface RunE2EInternalConfig extends E2EConfig {
suiteName: string;
}
+/**
+ * Context for tracking phase results within a version.
+ */
+interface VersionExecutionContext {
+ phases: PhaseResult[];
+ versionStartTime: number;
+ imageTag: string;
+}
+
/**
* Creates Docker execution utilities for a specific Node version.
+ * Now tracks phase results for the DebugLogManager.
*/
function createDockerExecutors(
config: RunE2EInternalConfig,
nodeVersion: string,
imageTag: string,
- repoRoot: string
+ repoRoot: string,
+ logManager: DebugLogManager
) {
- const { cwd, suiteName, env } = config;
+ const { cwd, suiteName, env, usesFixtures } = config;
const containerEnv = buildContainerEnv(env);
+ // Compute effective cwd based on usesFixtures flag
+ const effectiveCwd = usesFixtures ? `${cwd}/fixtures` : cwd;
+
+ // Track execution context for this version
+ const context: VersionExecutionContext = {
+ phases: [],
+ versionStartTime: Date.now(),
+ imageTag,
+ };
+
const runCmd = async (command: string): Promise<E2ETestResult> => {
const containerName = `e2e-${suiteName}-${nodeVersion.replace(/\./g, '-')}-${Date.now()}`;
+ const startTime = Date.now();
+
const result = await runNodeContainer({
imageTag,
cmd: command,
- cwd,
+ cwd: effectiveCwd,
env: containerEnv,
name: containerName,
});
- // Write output to DEBUG.log for debugging and CI troubleshooting
- await writeDebugLog(repoRoot, cwd, {
- nodeVersion,
+ const durationMs = Date.now() - startTime;
+
+ // Track as a standalone phase (not pre/fixture)
+ context.phases.push({
+ phase: 'fixture',
+ phaseIndex: context.phases.length + 1,
+ totalPhases: context.phases.length + 1, // Updated later if more phases
command,
containerName,
- result,
+ durationMs,
+ exitCode: result.exitCode,
+ stdout: result.stdout,
+ stderr: result.stderr,
});
return result;
};
- const runFixture = async (fixturePath: string): Promise<E2ETestResult> => {
- return runCmd(`node ${fixturePath}`);
+ /**
+ * Unified fixture runner with optional setup phase.
+ *
+ * Without setup: Runs `node <filename>` directly (no Docker volumes).
+ * With setup: Creates a Docker volume, runs setup command with volume mounted
+ * read-write, then runs the fixture with volume mounted read-only.
+ */
+ const runFixture = async (options: RunFixtureOptions): Promise<E2ETestResult | E2ETestResultWithSetup> => {
+ const { filename, setup } = options;
+
+ // Smart mode: no setup (or empty string) = no volumes, just run directly
+ if (!setup) {
+ return runCmd(`node ${filename}`);
+ }
+
+ // With setup: use Docker volumes
+ const volumeName = generateVolumeName(suiteName, nodeVersion);
+ const containerBaseName = `e2e-${suiteName}-${nodeVersion.replace(/\./g, '-')}-${Date.now()}`;
+
+ // The volume mounts at node_modules relative to the effective cwd
+ const volumeTarget = `${effectiveCwd.startsWith('/') ? effectiveCwd : `/app/${effectiveCwd}`}/node_modules`;
+
+ try {
+ // 1. Create volume
+ await createVolume(volumeName);
+
+ // 2. Initialize volume with correct ownership for node user (UID 1000)
+ await initializeVolumeOwnership(volumeName, imageTag);
+
+ // 3. Run setup command with volume mounted read-write
+ const setupContainerName = `${containerBaseName}-setup`;
+ const setupStartTime = Date.now();
+ const setupResult = await runNodeContainer({
+ imageTag,
+ cmd: setup,
+ cwd: effectiveCwd,
+ env: containerEnv,
+ name: setupContainerName,
+ volumes: [{
+ volume: volumeName,
+ target: volumeTarget,
+ readonly: false,
+ }],
+ });
+ const setupDurationMs = Date.now() - setupStartTime;
+
+ // Track setup phase
+ context.phases.push({
+ phase: 'setup',
+ phaseIndex: 1,
+ totalPhases: 2,
+ command: setup,
+ containerName: setupContainerName,
+ durationMs: setupDurationMs,
+ exitCode: setupResult.exitCode,
+ stdout: setupResult.stdout,
+ stderr: setupResult.stderr,
+ });
+
+ // 4. Run fixture with volume mounted read-only (runs regardless of setup exit code)
+ const fixtureContainerName = `${containerBaseName}-fixture`;
+ const fixtureStartTime = Date.now();
+ const fixtureResult = await runNodeContainer({
+ imageTag,
+ cmd: `node ${filename}`,
+ cwd: effectiveCwd,
+ env: containerEnv,
+ name: fixtureContainerName,
+ volumes: [{
+ volume: volumeName,
+ target: volumeTarget,
+ readonly: true,
+ }],
+ });
+ const fixtureDurationMs = Date.now() - fixtureStartTime;
+
+ // Track fixture phase
+ context.phases.push({
+ phase: 'fixture',
+ phaseIndex: 2,
+ totalPhases: 2,
+ command: `node ${filename}`,
+ containerName: fixtureContainerName,
+ durationMs: fixtureDurationMs,
+ exitCode: fixtureResult.exitCode,
+ stdout: fixtureResult.stdout,
+ stderr: fixtureResult.stderr,
+ });
+
+ // 5. Return combined result (top-level is fixture result)
+ return {
+ ...fixtureResult,
+ setup: setupResult,
+ };
+ } finally {
+ // 6. Always cleanup volume (best-effort, doesn't throw)
+ await removeVolume(volumeName);
+ }
+ };
+
+ /**
+ * Finalize this version's log output.
+ * Call this after all test phases have completed.
+ */
+ const finalizeVersionLog = async (): Promise<void> => {
+ const totalDurationMs = Date.now() - context.versionStartTime;
+
+ // Determine overall status based on exit codes
+ const allPassed = context.phases.every(p => p.exitCode === 0);
+ const status: 'pass' | 'fail' = allPassed ? 'pass' : 'fail';
+
+ await logManager.writeVersionSection({
+ version: nodeVersion,
+ status,
+ imageTag: context.imageTag,
+ phases: context.phases,
+ totalDurationMs,
+ });
};
- return { runCmd, runFixture };
+ return { runCmd, runFixture, finalizeVersionLog, context };
}
/**
@@ -158,7 +476,7 @@ function createDockerExecutors(
* Each version's skipInCI state is computed by resolveNodeVersionMetaList().
*/
export function runE2E(config: RunE2EInternalConfig): void {
- const { suiteName, defineTests, env } = config;
+ const { cwd, suiteName, defineTests, env } = config;
// Validate env vars early, before any Docker operations
validateRequiredEnvVars(env, suiteName);
@@ -166,6 +484,16 @@ export function runE2E(config: RunE2EInternalConfig): void {
const nodeVersionMetaList = resolveNodeVersionMetaList(config.nodeVersions);
const repoRoot = getRepoRoot();
+ // Create the debug log manager for structured output
+ const logPath = resolve(repoRoot, cwd, 'DEBUG.log');
+ const allVersions = nodeVersionMetaList.map(v => v.value);
+ const logManager = new DebugLogManager({
+ logPath,
+ suiteName,
+ testFilePath: `${cwd}/e2e.test.ts`,
+ nodeVersions: allVersions,
+ });
+
function renderNodeVersionMeta({ kind, value }: NodeVersionMeta) {
switch (kind) {
case 'current':
@@ -177,31 +505,61 @@ export function runE2E(config: RunE2EInternalConfig): void {
}
}
- for (const nodeVersionMeta of nodeVersionMetaList) {
- const testName = `${suiteName} (${renderNodeVersionMeta(nodeVersionMeta)})`;
+ // Wrap all tests in a top-level describe to handle initialization and summary
+ describe(suiteName, () => {
+ // Initialize log file before any tests run
+ beforeAll(async () => {
+ await logManager.initialize();
+ });
+
+ for (const nodeVersionMeta of nodeVersionMetaList) {
+ const testName = renderNodeVersionMeta(nodeVersionMeta);
- // Skip this version in CI if not selected
- if (nodeVersionMeta.skip.value) {
- describe.skip(`${testName} - skipped: ${nodeVersionMeta.skip.reason}`, () => {
- it('this version should not run in this CI matrix job', () => {});
- });
- continue;
- }
+ // Skip this version in CI if not selected
+ if (nodeVersionMeta.skip.value) {
+ describe(`${testName} - skipped: ${nodeVersionMeta.skip.reason}`, () => {
+ beforeAll(async () => {
+ // Write skip marker to log
+ await logManager.writeVersionSection({
+ version: nodeVersionMeta.value,
+ status: 'skipped',
+ reason: nodeVersionMeta.skip.reason || 'Skipped in CI',
+ phases: [],
+ });
+ });
- describe(testName, () => {
- let executors: ReturnType<typeof createDockerExecutors>;
+ it('this version should not run in this CI matrix job', () => {});
+ });
+ continue;
+ }
- // Ensure Docker image exists before tests run
- beforeAll(async () => {
- const imageTag = await ensureNodeImage(nodeVersionMeta.value, { repoRoot });
- executors = createDockerExecutors(config, nodeVersionMeta.value, imageTag, repoRoot);
- }, 600_000); // 10 minute timeout for Docker image build
+ describe(testName, () => {
+ let executors: ReturnType<typeof createDockerExecutors>;
- // Call user's defineTests with bun:test functions and Docker utilities
- defineTests({
- runCmd: (cmd) => executors.runCmd(cmd),
- runFixture: (path) => executors.runFixture(path),
+ // Ensure Docker image exists before tests run
+ beforeAll(async () => {
+ const imageTag = await ensureNodeImage(nodeVersionMeta.value, { repoRoot });
+ executors = createDockerExecutors(config, nodeVersionMeta.value, imageTag, repoRoot, logManager);
+ }, 600_000); // 10 minute timeout for Docker image build
+
+ // Call user's defineTests with bun:test functions and Docker utilities
+ defineTests({
+ runCmd: (cmd) => executors.runCmd(cmd),
+ runFixture: (opts) => executors.runFixture(opts),
+ });
+
+ // Write version section after all tests for this version complete
+ afterAll(async () => {
+ if (executors) {
+ await executors.finalizeVersionLog();
+ }
+ });
});
+ }
+
+ // Write summary after all versions complete
+ afterAll(async () => {
+ await logManager.writeSummary();
});
- }
+ });
}
diff --git a/ts/e2e-tests/_utils/src/types.ts b/ts/e2e-tests/_utils/src/types.ts
index dc9072826..f723df261 100644
--- a/ts/e2e-tests/_utils/src/types.ts
+++ b/ts/e2e-tests/_utils/src/types.ts
@@ -31,14 +31,55 @@ export interface E2ETestResult {
stderr: string;
}
+/**
+ * Result of runFixture when a setup command is provided.
+ * Top-level fields (exitCode, stdout, stderr) reflect the fixture result.
+ */
+export interface E2ETestResultWithSetup extends E2ETestResult {
+ /** Result of the setup command execution */
+ setup: E2ETestResult;
+}
+
+/**
+ * Options for runFixture.
+ */
+export interface RunFixtureOptions {
+ /** Fixture file path relative to cwd (e.g., 'index.mjs') */
+ filename: string;
+ /** Optional setup command to run before the fixture (e.g., 'npm install --legacy-peer-deps') */
+ setup?: string;
+}
+
/**
* Context passed to defineTests callback.
*/
export interface DefineTestsContext {
/** Run an arbitrary command in the Docker container */
runCmd: (command: string) => Promise<E2ETestResult>;
- /** Run a fixture file with Node.js (equivalent to runCmd(`node ${path}`)) */
- runFixture: (fixturePath: string) => Promise<E2ETestResult>;
+ /**
+ * Run a fixture file with Node.js.
+ *
+ * Without setup: Runs `node <filename>` directly (no Docker volumes).
+ * Returns E2ETestResult.
+ *
+ * With setup: Creates a Docker volume, runs the setup command (e.g., npm install)
+ * with the volume mounted read-write, then runs the fixture with the volume
+ * mounted read-only. Both commands run regardless of exit codes.
+ * Returns E2ETestResultWithSetup.
+ *
+ * @example
+ * // Simple fixture (no setup needed)
+ * const result = await runFixture({ filename: 'test.mjs' });
+ *
+ * @example
+ * // Fixture with setup (uses Docker volumes)
+ * const result = await runFixture({
+ * filename: 'index.mjs',
+ * setup: 'npm install --legacy-peer-deps',
+ * }) as E2ETestResultWithSetup;
+ * expect(result.setup.exitCode).toBe(0);
+ */
+ runFixture: (options: RunFixtureOptions) => Promise<E2ETestResult | E2ETestResultWithSetup>;
}
/**
@@ -57,17 +98,28 @@ export interface E2EConfig {
*/
env?: Record<string, string | undefined>;
+ /**
+ * When true, sets the working directory to {testDir}/fixtures for Docker commands.
+ * This affects:
+ * - Volume mount location (fixtures/node_modules instead of testDir/node_modules)
+ * - Command execution cwd
+ * - Fixture paths in runFixture (relative to fixtures/)
+ *
+ * @default false
+ */
+ usesFixtures?: boolean;
+
/**
* Define your tests using bun:test primitives.
* Called once per Node version during test registration.
*
* @example
* ```typescript
- * defineTests: ({ describe, it, expect, beforeAll, runFixture }) => {
+ * defineTests: ({ runFixture }) => {
* let result: E2ETestResult;
*
* beforeAll(async () => {
- * result = await runFixture('fixtures/test.mjs');
+ * result = await runFixture({ filename: 'fixtures/test.mjs' });
* }, 300_000);
*
* describe('output', () => {
diff --git a/ts/e2e-tests/_utils/src/volume.ts b/ts/e2e-tests/_utils/src/volume.ts
new file mode 100644
index 000000000..c4c2dd13b
--- /dev/null
+++ b/ts/e2e-tests/_utils/src/volume.ts
@@ -0,0 +1,70 @@
+import { $ } from 'bun';
+
+/**
+ * Generates a unique volume name for e2e tests.
+ * Format: e2e-{suiteName}-{nodeVersion}-{timestamp}
+ *
+ * @param suiteName - Test suite name
+ * @param nodeVersion - Node.js version being tested
+ * @returns Unique volume name
+ */
+export function generateVolumeName(suiteName: string, nodeVersion: string): string {
+ const sanitizedSuite = suiteName.replace(/[^a-zA-Z0-9-]/g, '-');
+ const sanitizedVersion = nodeVersion.replace(/\./g, '-');
+ return `e2e-${sanitizedSuite}-${sanitizedVersion}-${Date.now()}`;
+}
+
+/**
+ * Creates a Docker named volume for sharing state between container runs.
+ *
+ * @param name - Unique volume name
+ * @returns The volume name (for use in mounts)
+ * @throws If volume creation fails
+ */
+export async function createVolume(name: string): Promise<string> {
+ const result = await $`docker volume create ${name}`.nothrow().quiet();
+
+ if (result.exitCode !== 0) {
+ const err = new Error(`Failed to create Docker volume: ${name}`);
+ (err as Error & { cause: Error }).cause = new Error(result.stderr.toString() || result.stdout.toString());
+ throw err;
+ }
+
+ return name;
+}
+
+/**
+ * Removes a Docker named volume.
+ * Logs errors but doesn't throw (cleanup should be best-effort).
+ *
+ * @param name - Volume name to remove
+ */
+export async function removeVolume(name: string): Promise<void> {
+ const result = await $`docker volume rm ${name}`.nothrow().quiet();
+
+ if (result.exitCode !== 0) {
+ // Log but don't throw - cleanup should be best-effort
+ console.warn(`[e2e] Warning: Failed to remove Docker volume ${name}: ${result.stderr.toString()}`);
+ }
+}
+
+/**
+ * Initializes a Docker volume with correct ownership for the node user (UID 1000).
+ * This is necessary because Docker volumes are created with root ownership by default.
+ *
+ * @param volumeName - Name of the volume to initialize
+ * @param imageTag - Docker image to use for the initialization container
+ */
+export async function initializeVolumeOwnership(
+ volumeName: string,
+ imageTag: string
+): Promise<void> {
+ // Run a quick container as root to chown the volume contents
+ const result = await $`docker run --rm --user root -v ${volumeName}:/mnt/vol ${imageTag} chown -R node:node /mnt/vol`.nothrow().quiet();
+
+ if (result.exitCode !== 0) {
+ const err = new Error(`Failed to initialize volume ownership for: ${volumeName}`);
+ (err as Error & { cause: Error }).cause = new Error(result.stderr.toString() || result.stdout.toString());
+ throw err;
+ }
+}
diff --git a/ts/e2e-tests/runtimes/node/cjs-basic/e2e.test.ts b/ts/e2e-tests/runtimes/node/cjs-basic/e2e.test.ts
index 8b884f5fd..d894d69b6 100644
--- a/ts/e2e-tests/runtimes/node/cjs-basic/e2e.test.ts
+++ b/ts/e2e-tests/runtimes/node/cjs-basic/e2e.test.ts
@@ -19,7 +19,7 @@ e2e(import.meta.url, {
let result: E2ETestResult;
beforeAll(async () => {
- result = await runFixture('fixtures/test.cjs');
+ result = await runFixture({ filename: 'fixtures/test.cjs' });
});
describe('CommonJS compatibility', () => {
diff --git a/ts/e2e-tests/runtimes/node/esm-basic/e2e.test.ts b/ts/e2e-tests/runtimes/node/esm-basic/e2e.test.ts
index 2ff66e56f..161510831 100644
--- a/ts/e2e-tests/runtimes/node/esm-basic/e2e.test.ts
+++ b/ts/e2e-tests/runtimes/node/esm-basic/e2e.test.ts
@@ -19,7 +19,7 @@ e2e(import.meta.url, {
let result: E2ETestResult;
beforeAll(async () => {
- result = await runFixture('fixtures/test.mjs');
+ result = await runFixture({ filename: 'fixtures/test.mjs' });
});
describe('ESM compatibility', () => {
diff --git a/ts/e2e-tests/runtimes/node/openai-zod4-compat/e2e.test.ts b/ts/e2e-tests/runtimes/node/openai-zod4-compat/e2e.test.ts
index 1b5f52990..ef0fe22a2 100644
--- a/ts/e2e-tests/runtimes/node/openai-zod4-compat/e2e.test.ts
+++ b/ts/e2e-tests/runtimes/node/openai-zod4-compat/e2e.test.ts
@@ -5,7 +5,7 @@
* specifically testing the fix for https://github.com/ComposioHQ/composio/issues/2336
*/
-import { e2e, type E2ETestResult } from '@e2e-tests/utils';
+import { e2e, type E2ETestResultWithSetup } from '@e2e-tests/utils';
import { describe, it, expect, beforeAll } from 'bun:test';
declare module 'bun' {
@@ -16,21 +16,24 @@ declare module 'bun' {
e2e(import.meta.url, {
nodeVersions: ['20.19.0', '22.12.0'],
+ usesFixtures: true,
env: {
COMPOSIO_API_KEY: Bun.env.COMPOSIO_API_KEY,
},
- defineTests: ({ runCmd }) => {
- let result: E2ETestResult;
+ defineTests: ({ runFixture }) => {
+ let result: E2ETestResultWithSetup;
beforeAll(async () => {
- result = await runCmd(
- 'npm --prefix fixtures install --legacy-peer-deps && node fixtures/index.mjs'
- );
+ result = await runFixture({
+ filename: 'index.mjs',
+ setup: 'npm install --legacy-peer-deps',
+ });
});
describe('setup', () => {
it('npm install completes successfully', () => {
- expect(result.stdout).toMatch(/added \d+ packages/);
+ expect(result.setup.stdout).toMatch(/added \d+ packages/);
+ expect(result.setup.exitCode).toBe(0);
});
});
@@ -58,6 +61,6 @@ e2e(import.meta.url, {
it('all packages work together', () => {
expect(result.stdout).toContain('All packages work together!');
});
- },);
+ });
},
});
diff --git a/ts/e2e-tests/runtimes/node/typescript-mjs-import-nodenext/e2e.test.ts b/ts/e2e-tests/runtimes/node/typescript-mjs-import-nodenext/e2e.test.ts
index 26d351fd7..50d062689 100644
--- a/ts/e2e-tests/runtimes/node/typescript-mjs-import-nodenext/e2e.test.ts
+++ b/ts/e2e-tests/runtimes/node/typescript-mjs-import-nodenext/e2e.test.ts
@@ -25,7 +25,7 @@ e2e(import.meta.url, {
let result: E2ETestResult;
beforeAll(async () => {
- result = await runFixture('fixtures/index.mjs');
+ result = await runFixture({ filename: 'fixtures/index.mjs' });
}, 300_000);
describe('TypeScript .mjs import resolution', () => {