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.

feat(ts/e2e): runFixtures now handles setup and filename separately, "useFixtures" sets "fixtures" as the cwd

jkomyno2b52b3b75960
diff --git a/ts/e2e-tests/README.md b/ts/e2e-tests/README.md
index 24ca2a602..61b032367 100644
--- a/ts/e2e-tests/README.md
+++ b/ts/e2e-tests/README.md
@@ -13,13 +13,14 @@ ts/e2e-tests/
│ │ └── docker-clean.ts # Remove all e2e Docker images
│ ├── src/ # TypeScript runner utilities
│ │ ├── config.ts # Configuration utilities
-│ │ ├── const.ts # Well-known Node.js versions
+│ │ ├── const.ts # Well-known Node.js versions and timeouts
│ │ ├── e2e.ts # Main e2e test entry point
│ │ ├── image-lifecycle.ts # Docker image build/run utilities
│ │ ├── index.ts # Public exports
│ │ ├── runner.ts # Docker test runner
│ │ ├── sanitize.ts # Output sanitization utilities
-│ │ └── types.ts # TypeScript type definitions
+│ │ ├── types.ts # TypeScript type definitions
+│ │ └── volume.ts # Docker volume management
│ └── README.md # Utils documentation
└── runtimes/
├── node/ # Node.js runtime tests
@@ -27,6 +28,8 @@ ts/e2e-tests/
│ ├── esm-basic/ # ESM compatibility tests
│ ├── json-schema-to-zod-v3/ # @composio/json-schema-to-zod + Zod v3 tests
│ ├── json-schema-to-zod-v4/ # @composio/json-schema-to-zod + Zod v4 tests
+ │ ├── mastra-tool-router-zod-v3/ # @composio/mastra Tool Router + Zod v3 tests
+ │ ├── mastra-tool-router-zod-v4/ # @composio/mastra Tool Router + Zod v4 tests
│ ├── openai-zod4-compat/ # OpenAI + Zod v4 compatibility tests
│ └── typescript-mjs-import-nodenext/ # TypeScript moduleResolution: nodenext tests
└── cloudflare/ # Cloudflare runtime tests
@@ -78,12 +81,12 @@ import { describe, it, expect, beforeAll } from 'bun:test';
e2e(import.meta.url, {
nodeVersions: ['20.18.0', '22.12.0'], // Optional: defaults to current runtime
- env: { MY_VAR: process.env.MY_VAR }, // Optional: env vars
+ env: { MY_VAR: process.env.MY_VAR }, // Optional: env vars (validated at startup)
defineTests: ({ runFixture }) => {
let result: E2ETestResult;
beforeAll(async () => {
- result = await runFixture('fixtures/test.mjs');
+ result = await runFixture({ filename: 'fixtures/test.mjs' });
});
describe('output', () => {
@@ -101,9 +104,98 @@ e2e(import.meta.url, {
5. Add fixture files in a `fixtures/` directory
+### Tests with External Dependencies (npm install)
+
+For tests that need to install npm packages at runtime, use `usesFixtures: true` and the `setup` option:
+
+```typescript
+import { e2e, type E2ETestResultWithSetup } from '@e2e-tests/utils';
+import { describe, it, expect, beforeAll } from 'bun:test';
+
+e2e(import.meta.url, {
+ nodeVersions: ['20.19.0', '22.12.0'],
+ usesFixtures: true, // Sets cwd to fixtures/ directory
+ env: { MY_API_KEY: process.env.MY_API_KEY },
+ defineTests: ({ runFixture }) => {
+ let result: E2ETestResultWithSetup;
+
+ beforeAll(async () => {
+ result = await runFixture({
+ filename: 'index.mjs',
+ setup: 'npm install --legacy-peer-deps', // Runs before fixture
+ });
+ });
+
+ describe('setup', () => {
+ it('npm install completes successfully', () => {
+ expect(result.setup.exitCode).toBe(0);
+ });
+ });
+
+ describe('fixture', () => {
+ it('exits successfully', () => {
+ expect(result.exitCode).toBe(0);
+ });
+ });
+ },
+});
+```
+
### Cloudflare Runtime Tests
1. Create a new directory under `runtimes/cloudflare/` (e.g., `runtimes/cloudflare/my-test`)
2. Add a `package.json` with name `@e2e-tests/cf-my-test`
3. Add `test:e2e` and `test:e2e:cloudflare` scripts
4. Configure vitest with `@cloudflare/vitest-pool-workers`
+
+## Debugging
+
+Each test suite generates an ephemereal `DEBUG.log` file in its directory with structured output:
+
+```
+================================================================================
+E2E Test: my-test
+Started: 2026-01-30T12:18:42.000Z
+Test file: ts/e2e-tests/runtimes/node/my-test/e2e.test.ts
+Node versions: 20.19.0, 22.12.0
+================================================================================
+
+################################################################################
+### Node.js 20.19.0
+################################################################################
+Image: composio-e2e-node:20.19.0
+
+--- Phase 1/2: setup ---
+Container: e2e-my-test-20-19-0-1769775520382-setup
+Command: npm install
+Duration: 2.55s
+Exit Code: 0 (success)
+
+[stdout]
+added 3 packages in 2s
+
+[stderr]
+(empty)
+
+--- Phase 2/2: fixture ---
+Container: e2e-my-test-20-19-0-1769775520382-fixture
+Command: node index.mjs
+Duration: 0.56s
+Exit Code: 0 (success)
+
+[stdout]
+Test passed!
+
+[stderr]
+(empty)
+
+================================================================================
+Summary
+================================================================================
+Node.js 20.19.0: PASS (2 phases, 3.11s total)
+Node.js 22.12.0: SKIPPED
+
+Finished: 2026-01-30T12:18:46.500Z
+Total duration: 4.50s
+================================================================================
+```
diff --git a/ts/e2e-tests/_utils/README.md b/ts/e2e-tests/_utils/README.md
index 177218c71..7196fb895 100644
--- a/ts/e2e-tests/_utils/README.md
+++ b/ts/e2e-tests/_utils/README.md
@@ -4,11 +4,11 @@ Shared infrastructure for running `@composio/core` end-to-end tests in isolated
## What's Here
-| File/Directory | Purpose |
-| ----------------- | ---------------------------------------------------- |
-| `src/` | TypeScript utilities (e2e runner, config, types) |
-| `scripts/` | Docker build and cleanup scripts |
-| `Dockerfile.node` | Multi-stage Dockerfile for Node.js test environments |
+| File/Directory | Purpose |
+| ----------------- | ------------------------------------------------------ |
+| `src/` | TypeScript utilities (e2e runner, config, types) |
+| `scripts/` | Docker build and cleanup scripts |
+| `Dockerfile.node` | Multi-stage Dockerfile for Node.js test environments |
## API
@@ -27,7 +27,7 @@ e2e(import.meta.url, {
let result: E2ETestResult;
beforeAll(async () => {
- result = await runFixture('fixtures/test.mjs');
+ result = await runFixture({ filename: 'fixtures/test.mjs' });
});
describe('output', () => {
@@ -39,14 +39,52 @@ e2e(import.meta.url, {
});
```
+### `E2EConfig`
+
+Configuration object passed to `e2e()`:
+
+| Property | Type | Description |
+| -------------- | ------------------------------------- | ---------------------------------------------------------------- |
+| `nodeVersions` | `readonly NodeVersionFromUser[]` | Node.js versions to test. Defaults to current runtime |
+| `env` | `Record<string, string \| undefined>` | Environment variables for Docker. Validated at startup |
+| `usesFixtures` | `boolean` | When true, sets cwd to `{testDir}/fixtures`. Default: `false` |
+| `defineTests` | `(ctx: DefineTestsContext) => void` | Callback to define tests using bun:test primitives |
+
### `DefineTestsContext`
The context passed to the `defineTests` callback:
-| Function | Description |
-| -------------------------------- | ----------------------------------------------------------- |
-| `runCmd(command: string)` | Run arbitrary command in Docker container |
-| `runFixture(fixturePath: string)` | Run a fixture file with Node.js (equivalent to `runCmd(\`node ${path}\`)`) |
+| Function | Signature | Description |
+| ------------ | ---------------------------------------------------------------- | ---------------------------------------------- |
+| `runCmd` | `(command: string) => Promise<E2ETestResult>` | Run arbitrary command in Docker container |
+| `runFixture` | `(options: RunFixtureOptions) => Promise<E2ETestResult \| E2ETestResultWithSetup>` | Run fixture with optional setup phase |
+
+### `RunFixtureOptions`
+
+Options for `runFixture()`:
+
+| Property | Type | Description |
+| ---------- | -------- | --------------------------------------------------------------------- |
+| `filename` | `string` | Fixture file path relative to cwd (e.g., `'index.mjs'`) |
+| `setup` | `string` | Optional setup command (e.g., `'npm install'`). Enables volume mode |
+
+**Behavior:**
+
+- **Without `setup`**: Runs `node <filename>` directly. Returns `E2ETestResult`.
+- **With `setup`**: Creates a Docker volume, runs setup with volume mounted read-write, then runs fixture with volume mounted read-only. Returns `E2ETestResultWithSetup`.
+
+```typescript
+// Simple fixture (no dependencies to install)
+const result = await runFixture({ filename: 'test.mjs' });
+
+// Fixture with setup phase (uses Docker volumes)
+const result = await runFixture({
+ filename: 'index.mjs',
+ setup: 'npm install --legacy-peer-deps',
+});
+expect(result.setup.exitCode).toBe(0); // Check setup phase
+expect(result.exitCode).toBe(0); // Check fixture phase
+```
### `E2ETestResult`
@@ -60,6 +98,22 @@ interface E2ETestResult {
}
```
+### `E2ETestResultWithSetup`
+
+Extended result when `runFixture` is called with a `setup` option:
+
+```typescript
+interface E2ETestResultWithSetup extends E2ETestResult {
+ setup: {
+ exitCode: number;
+ stdout: string;
+ stderr: string;
+ };
+}
+```
+
+Top-level fields (`exitCode`, `stdout`, `stderr`) reflect the fixture result. The `setup` object contains the setup command result.
+
### `sanitizeOutput`
Utility for stable test comparisons. Removes ANSI escape codes, normalizes line endings, and trims whitespace.
@@ -70,6 +124,24 @@ import { sanitizeOutput } from '@e2e-tests/utils';
const clean = sanitizeOutput(result.stdout);
```
+### `TIMEOUTS`
+
+Predefined timeout constants for tests (in milliseconds):
+
+```typescript
+import { TIMEOUTS } from '@e2e-tests/utils/const';
+
+it('calls LLM', async () => {
+ // test code
+}, { timeout: TIMEOUTS.LLM_SHORT });
+```
+
+| Constant | Value | Use Case |
+| ----------- | --------- | ---------------------------------- |
+| `DEFAULT` | `5_000` | Standard test operations |
+| `LLM_SHORT` | `15_000` | Quick LLM calls |
+| `LLM_LONG` | `60_000` | Complex LLM operations |
+
## Node Version Resolution
Node.js versions to test are resolved in this order:
@@ -87,6 +159,42 @@ The following versions are pre-defined in `const.ts`:
- `22.12.0`
- `current` (resolves to current Node runtime version)
+## Environment Variable Validation
+
+Environment variables passed to `E2EConfig.env` are validated at test startup. If any variable has an `undefined` value, the test fails fast with a clear error message:
+
+```
+[my-test] Missing required environment variables: COMPOSIO_API_KEY, OPENAI_API_KEY
+Set these variables before running the tests, or remove them from E2EConfig.env if not required.
+```
+
+This prevents silent failures from missing credentials.
+
+## The `usesFixtures` Option
+
+When `usesFixtures: true` is set:
+
+- Working directory changes to `{testDir}/fixtures/`
+- Docker volume mounts at `fixtures/node_modules`
+- Fixture paths in `runFixture({ filename })` are relative to `fixtures/`
+
+Use this for tests that have their own `package.json` and need to run `npm install`:
+
+```typescript
+e2e(import.meta.url, {
+ usesFixtures: true,
+ defineTests: ({ runFixture }) => {
+ beforeAll(async () => {
+ // Both commands run in fixtures/ directory
+ result = await runFixture({
+ filename: 'index.mjs', // Resolves to fixtures/index.mjs
+ setup: 'npm install', // Runs in fixtures/
+ });
+ });
+ },
+});
+```
+
## Scripts
```bash
@@ -97,6 +205,76 @@ pnpm docker:build
pnpm docker:clean
```
+## DEBUG.log Output
+
+Each test suite generates a `DEBUG.log` file with structured output grouped by Node version:
+
+```
+================================================================================
+E2E Test: openai-zod4-compat
+Started: 2026-01-30T12:18:42.000Z
+Test file: ts/e2e-tests/runtimes/node/openai-zod4-compat/e2e.test.ts
+Node versions: 20.19.0, 22.12.0
+================================================================================
+
+################################################################################
+### Node.js 20.19.0
+################################################################################
+Image: composio-e2e-node:20.19.0
+
+--- Phase 1/2: setup ---
+Container: e2e-openai-zod4-compat-20-19-0-1769775520382-setup
+Command: npm install --legacy-peer-deps
+Duration: 2.55s
+Exit Code: 0 (success)
+
+[stdout]
+added 3 packages, and audited 5 packages in 2s
+
+[stderr]
+(empty)
+
+--- Phase 2/2: fixture ---
+Container: e2e-openai-zod4-compat-20-19-0-1769775520382-fixture
+Command: node index.mjs
+Duration: 0.56s
+Exit Code: 0 (success)
+
+[stdout]
+zod@4 works
+openai@5 works
+All packages work together!
+
+[stderr]
+(empty)
+
+################################################################################
+### Node.js 22.12.0 (SKIPPED)
+################################################################################
+Reason: Not selected via COMPOSIO_E2E_NODE_VERSION
+
+================================================================================
+Summary
+================================================================================
+Node.js 20.19.0: PASS (2 phases, 3.11s total)
+Node.js 22.12.0: SKIPPED
+
+Finished: 2026-01-30T12:18:46.500Z
+Total duration: 4.50s
+================================================================================
+```
+
+**Features:**
+
+- File cleared at start of each test run (no stale data)
+- Phases grouped by Node version for easy scanning
+- Visual hierarchy: `===` for file boundaries, `###` for versions, `---` for phases
+- Empty stdout/stderr shown as `(empty)`
+- Summary with pass/fail/skip status and timing
+
## Behavior
-Builds an isolated Docker container and runs the test command inside it. Docker is required.
+- Builds an isolated Docker container and runs the test command inside it
+- Docker is required
+- Tests run sequentially per Node version
+- Volume cleanup is best-effort (doesn't fail tests on cleanup errors)
diff --git a/ts/e2e-tests/_utils/package.json b/ts/e2e-tests/_utils/package.json
index 3bd45ecd4..73585257d 100644
--- a/ts/e2e-tests/_utils/package.json
+++ b/ts/e2e-tests/_utils/package.json
@@ -21,7 +21,8 @@
},
"scripts": {
"docker:build": "bun run scripts/docker-build.ts",
- "docker:clean": "bun run scripts/docker-clean.ts"
+ "docker:clean": "bun run scripts/docker-clean.ts",
+ "typecheck": "tsc --noEmit"
},
"devDependencies": {
"typescript": "catalog:"
diff --git a/ts/e2e-tests/_utils/src/runner.ts b/ts/e2e-tests/_utils/src/runner.ts
index 165e8917f..9e14a7756 100644
--- a/ts/e2e-tests/_utils/src/runner.ts
+++ b/ts/e2e-tests/_utils/src/runner.ts
@@ -1,7 +1,7 @@
import { describe, beforeAll, afterAll, it } from 'bun:test';
import { appendFile, writeFile } from 'node:fs/promises';
import { resolve } from 'node:path';
-import type { E2EConfig, E2ETestResult, E2ETestResultWithSetup, NodeVersionMeta, RunFixtureOptions } from './types';
+import type { DefineTestsContext, 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';
@@ -352,7 +352,9 @@ function createDockerExecutors(
* 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> => {
+ function runFixture(options: { filename: string }): Promise<E2ETestResult>;
+ function runFixture(options: { filename: string; setup: string }): Promise<E2ETestResultWithSetup>;
+ async function runFixture(options: RunFixtureOptions): Promise<E2ETestResult | E2ETestResultWithSetup> {
const { filename, setup } = options;
// Smart mode: no setup (or empty string) = no volumes, just run directly
@@ -443,7 +445,7 @@ function createDockerExecutors(
// 6. Always cleanup volume (best-effort, doesn't throw)
await removeVolume(volumeName);
}
- };
+ }
/**
* Finalize this version's log output.
@@ -545,7 +547,7 @@ export function runE2E(config: RunE2EInternalConfig): void {
// Call user's defineTests with bun:test functions and Docker utilities
defineTests({
runCmd: (cmd) => executors.runCmd(cmd),
- runFixture: (opts) => executors.runFixture(opts),
+ runFixture: ((opts) => executors.runFixture(opts)) as DefineTestsContext['runFixture'],
});
// Write version section after all tests for this version complete
diff --git a/ts/e2e-tests/_utils/src/types.ts b/ts/e2e-tests/_utils/src/types.ts
index f723df261..9445f2607 100644
--- a/ts/e2e-tests/_utils/src/types.ts
+++ b/ts/e2e-tests/_utils/src/types.ts
@@ -76,10 +76,13 @@ export interface DefineTestsContext {
* 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>;
+ runFixture: {
+ (options: { filename: string }): Promise<E2ETestResult>;
+ (options: { filename: string; setup: string }): Promise<E2ETestResultWithSetup>;
+ };
}
/**
diff --git a/ts/e2e-tests/runtimes/node/cjs-basic/README.md b/ts/e2e-tests/runtimes/node/cjs-basic/README.md
index 40369f6a5..d83fb6ecf 100644
--- a/ts/e2e-tests/runtimes/node/cjs-basic/README.md
+++ b/ts/e2e-tests/runtimes/node/cjs-basic/README.md
@@ -24,11 +24,23 @@ Many Node.js projects still use CommonJS. This suite ensures:
| constants | Constants namespace is accessible |
| logger | Logger instance is exported |
-## Isolation Tool
+## Fixture
+
+```
+fixtures/
+└── test.cjs # CommonJS test script using require()
+```
-**Docker** with Node.js versions: 20.18.0, 20.19.0, 22.12.0
+The fixture is a standalone `.cjs` file that:
+
+- Uses `require('@composio/core')` to import the package
+- Verifies each export exists and has the correct type
+- Attempts to instantiate `OpenAIProvider` to catch runtime errors
+- Outputs test results to stdout with pass/fail markers
+
+## Isolation Tool
-This ensures tests run against exact Node.js versions independent of the developer's local setup, catching version-specific module resolution issues.
+**Docker** with Node.js versions: 20.18.0, 20.19.0, 22.12.0.
## Running
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 d894d69b6..2b50a319c 100644
--- a/ts/e2e-tests/runtimes/node/cjs-basic/e2e.test.ts
+++ b/ts/e2e-tests/runtimes/node/cjs-basic/e2e.test.ts
@@ -15,11 +15,12 @@ e2e(import.meta.url, {
'20.19.0',
'22.12.0',
],
+ usesFixtures: true,
defineTests: ({ runFixture }) => {
let result: E2ETestResult;
beforeAll(async () => {
- result = await runFixture({ filename: 'fixtures/test.cjs' });
+ result = await runFixture({ filename: 'test.cjs' });
});
describe('CommonJS compatibility', () => {
diff --git a/ts/e2e-tests/runtimes/node/esm-basic/README.md b/ts/e2e-tests/runtimes/node/esm-basic/README.md
index 719507192..5a9be9445 100644
--- a/ts/e2e-tests/runtimes/node/esm-basic/README.md
+++ b/ts/e2e-tests/runtimes/node/esm-basic/README.md
@@ -25,11 +25,24 @@ ESM is the modern JavaScript module standard. This suite ensures:
| logger | Logger instance is exported |
| Named imports | Destructuring imports work correctly |
-## Isolation Tool
+## Fixture
+
+```
+fixtures/
+└── test.mjs # ESM test script using import()
+```
-**Docker** with Node.js versions: 20.18.0, 20.19.0, 22.12.0
+The fixture is a standalone `.mjs` file that:
+
+- Uses `import('@composio/core')` to dynamically import the package
+- Verifies each export exists and has the correct type
+- Tests destructured named imports (`{ Composio, OpenAIProvider }`)
+- Attempts to instantiate `OpenAIProvider` to catch runtime errors
+- Outputs test results to stdout with pass/fail markers
+
+## Isolation Tool
-This ensures tests run against exact Node.js versions independent of the developer's local setup, catching version-specific ESM resolution issues.
+**Docker** with Node.js versions: 20.18.0, 20.19.0, 22.12.0.
## Running
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 161510831..12c098ab9 100644
--- a/ts/e2e-tests/runtimes/node/esm-basic/e2e.test.ts
+++ b/ts/e2e-tests/runtimes/node/esm-basic/e2e.test.ts
@@ -15,11 +15,12 @@ e2e(import.meta.url, {
'20.19.0',
'22.12.0',
],
+ usesFixtures: true,
defineTests: ({ runFixture }) => {
let result: E2ETestResult;
beforeAll(async () => {
- result = await runFixture({ filename: 'fixtures/test.mjs' });
+ result = await runFixture({ filename: 'test.mjs' });
});
describe('ESM compatibility', () => {
diff --git a/ts/e2e-tests/runtimes/node/json-schema-to-zod-v3/README.md b/ts/e2e-tests/runtimes/node/json-schema-to-zod-v3/README.md
index c928e9c47..05fd87c1f 100644
--- a/ts/e2e-tests/runtimes/node/json-schema-to-zod-v3/README.md
+++ b/ts/e2e-tests/runtimes/node/json-schema-to-zod-v3/README.md
@@ -23,6 +23,21 @@ The `@composio/json-schema-to-zod` package must support both Zod v3 and v4. This
| anyOf schemas | Union type conversion |
| Round-trip conversion | JSON Schema -> Zod -> JSON Schema preserves `additionalProperties` |
+## Test Setup
+
+This test runs **directly in Bun** (no Docker fixtures). The test file imports `@composio/json-schema-to-zod` and `zod-to-json-schema` from the monorepo workspace:
+
+```typescript
+import { jsonSchemaToZod, type JsonSchema } from '@composio/json-schema-to-zod';
+import zodToJsonSchema from 'zod-to-json-schema';
+```
+
+Tests use `bun:test` assertions to verify schema conversion and round-trip behavior.
+
+## Isolation Tool
+
+**Docker** with Node.js versions: current (as specified in `.nvmrc`).
+
## Running
```bash
diff --git a/ts/e2e-tests/runtimes/node/json-schema-to-zod-v4/README.md b/ts/e2e-tests/runtimes/node/json-schema-to-zod-v4/README.md
index 4fa0dcb66..9196d13f9 100644
--- a/ts/e2e-tests/runtimes/node/json-schema-to-zod-v4/README.md
+++ b/ts/e2e-tests/runtimes/node/json-schema-to-zod-v4/README.md
@@ -25,6 +25,20 @@ The `@composio/json-schema-to-zod` package must support both Zod v3 and v4. This
| Complex nested arrays | Arrays of objects with nested arrays |
| Union with constraints | anyOf with minLength, minimum, and required fields |
+## Test Setup
+
+This test runs **directly in Bun** (no Docker fixtures). The test file imports `@composio/json-schema-to-zod` from the monorepo workspace:
+
+```typescript
+import { jsonSchemaToZod, type JsonSchema } from '@composio/json-schema-to-zod';
+```
+
+Tests use `bun:test` assertions to verify schema conversion and parsing behavior.
+
+## Isolation Tool
+
+**Docker** with Node.js versions: current (as specified in `.nvmrc`).
+
## Running
```bash
diff --git a/ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v3/README.md b/ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v3/README.md
index 9e9fdee13..da970ad11 100644
--- a/ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v3/README.md
+++ b/ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v3/README.md
@@ -13,10 +13,32 @@ Issue [#2109](https://github.com/ComposioHQ/composio/issues/2109) tracks Mastra
## What It Tests
-| Test | Description |
-| -------------------- | -------------------------------------------------------- |
+| Test | Description |
+| -------------------- | ------------------------------------------------------------ |
| Tool Router workflow | Creates session, connects MCP, runs agent with Zod v3 schema |
+## Test Setup
+
+This test runs **directly in Bun** (no Docker fixtures). It imports packages from the monorepo workspace and makes real API calls:
+
+```typescript
+import { Composio } from '@composio/core';
+import { MastraProvider } from '@composio/mastra';
+import { MCPClient } from '@mastra/mcp';
+import { Agent } from '@mastra/core/agent';
+import { createOpenAI } from '@ai-sdk/openai';
+import { z } from 'zod';
+```
+
+**Required environment variables:**
+
+- `COMPOSIO_API_KEY` - Composio API key for Tool Router
+- `OPENAI_API_KEY` - OpenAI API key for agent LLM calls
+
+## Isolation Tool
+
+**Docker** with Node.js versions: 22.12.0.
+
## Running
```bash
diff --git a/ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v4/README.md b/ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v4/README.md
index 9cd6c78ca..404a89a98 100644
--- a/ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v4/README.md
+++ b/ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v4/README.md
@@ -13,10 +13,32 @@ Issue [#2109](https://github.com/ComposioHQ/composio/issues/2109) tracks Mastra
## What It Tests
-| Test | Description |
-| -------------------- | -------------------------------------------------------- |
+| Test | Description |
+| -------------------- | ------------------------------------------------------------ |
| Tool Router workflow | Creates session, connects MCP, runs agent with Zod v4 schema |
+## Test Setup
+
+This test runs **directly in Bun** (no Docker fixtures). It imports packages from the monorepo workspace and makes real API calls:
+
+```typescript
+import { Composio } from '@composio/core';
+import { MastraProvider } from '@composio/mastra';
+import { MCPClient } from '@mastra/mcp';
+import { Agent } from '@mastra/core/agent';
+import { createOpenAI } from '@ai-sdk/openai';
+import { z } from 'zod';
+```
+
+**Required environment variables:**
+
+- `COMPOSIO_API_KEY` - Composio API key for Tool Router
+- `OPENAI_API_KEY` - OpenAI API key for agent LLM calls
+
+## Isolation Tool
+
+**Docker** with Node.js versions: 22.12.0.
+
## Running
```bash
diff --git a/ts/e2e-tests/runtimes/node/openai-zod4-compat/README.md b/ts/e2e-tests/runtimes/node/openai-zod4-compat/README.md
index 61a40b884..9c85022b4 100644
--- a/ts/e2e-tests/runtimes/node/openai-zod4-compat/README.md
+++ b/ts/e2e-tests/runtimes/node/openai-zod4-compat/README.md
@@ -8,17 +8,33 @@ Issue [#2336](https://github.com/ComposioHQ/composio/issues/2336) reported peer
## What It Tests
-| Test | Description |
-| ------------------- | ------------------------------------------------------ |
-| npm install | Installs `@composio/core`, `openai`, and `zod@4` |
-| Package integration | Verifies all packages work together without conflicts |
-| wrapTool | Confirms OpenAI provider tool wrapping works |
+| Test | Description |
+| ------------------- | ----------------------------------------------------- |
+| npm install | Installs `@composio/core`, `openai`, and `zod@4` |
+| Package integration | Verifies all packages work together without conflicts |
+| wrapTool | Confirms OpenAI provider tool wrapping works |
-## Isolation Tool
+## Fixture
+
+```
+fixtures/
+├── index.mjs # Test script that imports and uses all packages
+└── package.json # Declares dependencies: @composio/core, openai@^6.16.0, zod@^4.3.5
+```
+
+The fixture uses `usesFixtures: true` with a setup phase to install dependencies at runtime:
-**Docker** with Node.js versions: 20.19.0, 22.12.0
+- `package.json` declares `@composio/core` (linked from monorepo), `openai`, and `zod@4`
+- `index.mjs` imports all three packages and verifies they work together
+- Tests `wrapTool` to ensure schema conversion works with Zod v4
+
+## Setup
+
+The `setup` phase runs `npm install --legacy-peer-deps` in a Docker volume, then the fixture runs with the installed `node_modules` mounted read-only.
+
+## Isolation Tool
-This ensures tests run against exact Node.js versions independent of the developer's local setup.
+**Docker** with Node.js versions: 20.19.0, 22.12.0.
## Running
diff --git a/ts/e2e-tests/runtimes/node/typescript-mjs-import-nodenext/README.md b/ts/e2e-tests/runtimes/node/typescript-mjs-import-nodenext/README.md
index 1115298f8..c0666efe7 100644
--- a/ts/e2e-tests/runtimes/node/typescript-mjs-import-nodenext/README.md
+++ b/ts/e2e-tests/runtimes/node/typescript-mjs-import-nodenext/README.md
@@ -22,11 +22,40 @@ This causes `TS2307: Cannot find module './foo.mjs'` errors.
| File existence | Verifies generated .ts files exist |
| TypeScript compilation | Runs `tsc --noEmit` to check import resolution |
-## Isolation Tool
+## Fixture
+
+```
+fixtures/
+├── index.mjs # Test runner script that generates and compiles TypeScript
+└── tsconfig.json # TypeScript config with moduleResolution: "nodenext"
+```
+
+The fixture script:
-**Docker** with Node.js version: current runtime
+1. Cleans up any previous generated files
+2. Runs `composio ts generate --toolkits entelligence --output-dir ./generated`
+3. Verifies generated `.ts` files exist
+4. Runs `npx tsc --noEmit` to check TypeScript compilation
+5. Fails if TS2307 errors occur (indicating `.mjs` import bug)
+
+**tsconfig.json:**
+
+```json
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "NodeNext",
+ "moduleResolution": "nodenext",
+ "strict": true,
+ "noEmit": true
+ },
+ "include": ["generated/**/*.ts"]
+}
+```
+
+## Isolation Tool
-This test uses the current Node.js runtime version for simplicity.
+**Docker** with Node.js versions: current (as specified in `.nvmrc`).
## Running