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
jkomyno committed
Jan 30, 2026 at 19:53 UTC
2b52b3b7596041f5302a0dcaab39de6c8b69bfdb
15 files changed
+466
-45
ts/e2e-tests/README.md
+96
-4
@@ -13,13 +13,14 @@ ts/e2e-tests/
13
│ │ └── docker-clean.ts # Remove all e2e Docker images
14
│ ├── src/ # TypeScript runner utilities
15
│ │ ├── config.ts # Configuration utilities
16
-│ │ ├── const.ts # Well-known Node.js versions
16
+│ │ ├── const.ts # Well-known Node.js versions and timeouts
17
│ │ ├── e2e.ts # Main e2e test entry point
18
│ │ ├── image-lifecycle.ts # Docker image build/run utilities
19
│ │ ├── index.ts # Public exports
20
│ │ ├── runner.ts # Docker test runner
21
│ │ ├── sanitize.ts # Output sanitization utilities
22
-│ │ └── types.ts # TypeScript type definitions
22
+│ │ ├── types.ts # TypeScript type definitions
23
+│ │ └── volume.ts # Docker volume management
24
│ └── README.md # Utils documentation
25
└── runtimes/
26
├── node/ # Node.js runtime tests
@@ -27,6 +28,8 @@ ts/e2e-tests/
28
│ ├── esm-basic/ # ESM compatibility tests
29
│ ├── json-schema-to-zod-v3/ # @composio/json-schema-to-zod + Zod v3 tests
30
│ ├── json-schema-to-zod-v4/ # @composio/json-schema-to-zod + Zod v4 tests
31
+ │ ├── mastra-tool-router-zod-v3/ # @composio/mastra Tool Router + Zod v3 tests
32
+ │ ├── mastra-tool-router-zod-v4/ # @composio/mastra Tool Router + Zod v4 tests
33
│ ├── openai-zod4-compat/ # OpenAI + Zod v4 compatibility tests
34
│ └── typescript-mjs-import-nodenext/ # TypeScript moduleResolution: nodenext tests
35
└── cloudflare/ # Cloudflare runtime tests
@@ -78,12 +81,12 @@ import { describe, it, expect, beforeAll } from 'bun:test';
81
82
e2e(import.meta.url, {
83
nodeVersions: ['20.18.0', '22.12.0'], // Optional: defaults to current runtime
81
- env: { MY_VAR: process.env.MY_VAR }, // Optional: env vars
84
+ env: { MY_VAR: process.env.MY_VAR }, // Optional: env vars (validated at startup)
85
defineTests: ({ runFixture }) => {
86
let result: E2ETestResult;
87
88
beforeAll(async () => {
86
- result = await runFixture('fixtures/test.mjs');
89
+ result = await runFixture({ filename: 'fixtures/test.mjs' });
90
});
91
92
describe('output', () => {
@@ -101,9 +104,98 @@ e2e(import.meta.url, {
104
105
5. Add fixture files in a `fixtures/` directory
106
107
+### Tests with External Dependencies (npm install)
108
+
109
+For tests that need to install npm packages at runtime, use `usesFixtures: true` and the `setup` option:
110
+
111
+```typescript
112
+import { e2e, type E2ETestResultWithSetup } from '@e2e-tests/utils';
113
+import { describe, it, expect, beforeAll } from 'bun:test';
114
+
115
+e2e(import.meta.url, {
116
+ nodeVersions: ['20.19.0', '22.12.0'],
117
+ usesFixtures: true, // Sets cwd to fixtures/ directory
118
+ env: { MY_API_KEY: process.env.MY_API_KEY },
119
+ defineTests: ({ runFixture }) => {
120
+ let result: E2ETestResultWithSetup;
121
+
122
+ beforeAll(async () => {
123
+ result = await runFixture({
124
+ filename: 'index.mjs',
125
+ setup: 'npm install --legacy-peer-deps', // Runs before fixture
126
+ });
127
+ });
128
+
129
+ describe('setup', () => {
130
+ it('npm install completes successfully', () => {
131
+ expect(result.setup.exitCode).toBe(0);
132
+ });
133
+ });
134
+
135
+ describe('fixture', () => {
136
+ it('exits successfully', () => {
137
+ expect(result.exitCode).toBe(0);
138
+ });
139
+ });
140
+ },
141
+});
142
+```
143
+
144
### Cloudflare Runtime Tests
145
146
1. Create a new directory under `runtimes/cloudflare/` (e.g., `runtimes/cloudflare/my-test`)
147
2. Add a `package.json` with name `@e2e-tests/cf-my-test`
148
3. Add `test:e2e` and `test:e2e:cloudflare` scripts
149
4. Configure vitest with `@cloudflare/vitest-pool-workers`
150
+
151
+## Debugging
152
+
153
+Each test suite generates an ephemereal `DEBUG.log` file in its directory with structured output:
154
+
155
+```
156
+================================================================================
157
+E2E Test: my-test
158
+Started: 2026-01-30T12:18:42.000Z
159
+Test file: ts/e2e-tests/runtimes/node/my-test/e2e.test.ts
160
+Node versions: 20.19.0, 22.12.0
161
+================================================================================
162
+
163
+################################################################################
164
+### Node.js 20.19.0
165
+################################################################################
166
+Image: composio-e2e-node:20.19.0
167
+
168
+--- Phase 1/2: setup ---
169
+Container: e2e-my-test-20-19-0-1769775520382-setup
170
+Command: npm install
171
+Duration: 2.55s
172
+Exit Code: 0 (success)
173
+
174
+[stdout]
175
+added 3 packages in 2s
176
+
177
+[stderr]
178
+(empty)
179
+
180
+--- Phase 2/2: fixture ---
181
+Container: e2e-my-test-20-19-0-1769775520382-fixture
182
+Command: node index.mjs
183
+Duration: 0.56s
184
+Exit Code: 0 (success)
185
+
186
+[stdout]
187
+Test passed!
188
+
189
+[stderr]
190
+(empty)
191
+
192
+================================================================================
193
+Summary
194
+================================================================================
195
+Node.js 20.19.0: PASS (2 phases, 3.11s total)
196
+Node.js 22.12.0: SKIPPED
197
+
198
+Finished: 2026-01-30T12:18:46.500Z
199
+Total duration: 4.50s
200
+================================================================================
201
+```
ts/e2e-tests/_utils/README.md
+189
-11
@@ -4,11 +4,11 @@ Shared infrastructure for running `@composio/core` end-to-end tests in isolated
4
5
## What's Here
6
7
-| File/Directory | Purpose |
8
-| ----------------- | ---------------------------------------------------- |
9
-| `src/` | TypeScript utilities (e2e runner, config, types) |
10
-| `scripts/` | Docker build and cleanup scripts |
11
-| `Dockerfile.node` | Multi-stage Dockerfile for Node.js test environments |
7
+| File/Directory | Purpose |
8
+| ----------------- | ------------------------------------------------------ |
9
+| `src/` | TypeScript utilities (e2e runner, config, types) |
10
+| `scripts/` | Docker build and cleanup scripts |
11
+| `Dockerfile.node` | Multi-stage Dockerfile for Node.js test environments |
12
13
## API
14
@@ -27,7 +27,7 @@ e2e(import.meta.url, {
27
let result: E2ETestResult;
28
29
beforeAll(async () => {
30
- result = await runFixture('fixtures/test.mjs');
30
+ result = await runFixture({ filename: 'fixtures/test.mjs' });
31
});
32
33
describe('output', () => {
@@ -39,14 +39,52 @@ e2e(import.meta.url, {
39
});
40
```
41
42
+### `E2EConfig`
43
+
44
+Configuration object passed to `e2e()`:
45
+
46
+| Property | Type | Description |
47
+| -------------- | ------------------------------------- | ---------------------------------------------------------------- |
48
+| `nodeVersions` | `readonly NodeVersionFromUser[]` | Node.js versions to test. Defaults to current runtime |
49
+| `env` | `Record<string, string \| undefined>` | Environment variables for Docker. Validated at startup |
50
+| `usesFixtures` | `boolean` | When true, sets cwd to `{testDir}/fixtures`. Default: `false` |
51
+| `defineTests` | `(ctx: DefineTestsContext) => void` | Callback to define tests using bun:test primitives |
52
+
53
### `DefineTestsContext`
54
55
The context passed to the `defineTests` callback:
56
46
-| Function | Description |
47
-| -------------------------------- | ----------------------------------------------------------- |
48
-| `runCmd(command: string)` | Run arbitrary command in Docker container |
49
-| `runFixture(fixturePath: string)` | Run a fixture file with Node.js (equivalent to `runCmd(\`node ${path}\`)`) |
57
+| Function | Signature | Description |
58
+| ------------ | ---------------------------------------------------------------- | ---------------------------------------------- |
59
+| `runCmd` | `(command: string) => Promise<E2ETestResult>` | Run arbitrary command in Docker container |
60
+| `runFixture` | `(options: RunFixtureOptions) => Promise<E2ETestResult \| E2ETestResultWithSetup>` | Run fixture with optional setup phase |
61
+
62
+### `RunFixtureOptions`
63
+
64
+Options for `runFixture()`:
65
+
66
+| Property | Type | Description |
67
+| ---------- | -------- | --------------------------------------------------------------------- |
68
+| `filename` | `string` | Fixture file path relative to cwd (e.g., `'index.mjs'`) |
69
+| `setup` | `string` | Optional setup command (e.g., `'npm install'`). Enables volume mode |
70
+
71
+**Behavior:**
72
+
73
+- **Without `setup`**: Runs `node <filename>` directly. Returns `E2ETestResult`.
74
+- **With `setup`**: Creates a Docker volume, runs setup with volume mounted read-write, then runs fixture with volume mounted read-only. Returns `E2ETestResultWithSetup`.
75
+
76
+```typescript
77
+// Simple fixture (no dependencies to install)
78
+const result = await runFixture({ filename: 'test.mjs' });
79
+
80
+// Fixture with setup phase (uses Docker volumes)
81
+const result = await runFixture({
82
+ filename: 'index.mjs',
83
+ setup: 'npm install --legacy-peer-deps',
84
+});
85
+expect(result.setup.exitCode).toBe(0); // Check setup phase
86
+expect(result.exitCode).toBe(0); // Check fixture phase
87
+```
88
89
### `E2ETestResult`
90
@@ -60,6 +98,22 @@ interface E2ETestResult {
98
}
99
```
100
101
+### `E2ETestResultWithSetup`
102
+
103
+Extended result when `runFixture` is called with a `setup` option:
104
+
105
+```typescript
106
+interface E2ETestResultWithSetup extends E2ETestResult {
107
+ setup: {
108
+ exitCode: number;
109
+ stdout: string;
110
+ stderr: string;
111
+ };
112
+}
113
+```
114
+
115
+Top-level fields (`exitCode`, `stdout`, `stderr`) reflect the fixture result. The `setup` object contains the setup command result.
116
+
117
### `sanitizeOutput`
118
119
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';
124
const clean = sanitizeOutput(result.stdout);
125
```
126
127
+### `TIMEOUTS`
128
+
129
+Predefined timeout constants for tests (in milliseconds):
130
+
131
+```typescript
132
+import { TIMEOUTS } from '@e2e-tests/utils/const';
133
+
134
+it('calls LLM', async () => {
135
+ // test code
136
+}, { timeout: TIMEOUTS.LLM_SHORT });
137
+```
138
+
139
+| Constant | Value | Use Case |
140
+| ----------- | --------- | ---------------------------------- |
141
+| `DEFAULT` | `5_000` | Standard test operations |
142
+| `LLM_SHORT` | `15_000` | Quick LLM calls |
143
+| `LLM_LONG` | `60_000` | Complex LLM operations |
144
+
145
## Node Version Resolution
146
147
Node.js versions to test are resolved in this order:
@@ -87,6 +159,42 @@ The following versions are pre-defined in `const.ts`:
159
- `22.12.0`
160
- `current` (resolves to current Node runtime version)
161
162
+## Environment Variable Validation
163
+
164
+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:
165
+
166
+```
167
+[my-test] Missing required environment variables: COMPOSIO_API_KEY, OPENAI_API_KEY
168
+Set these variables before running the tests, or remove them from E2EConfig.env if not required.
169
+```
170
+
171
+This prevents silent failures from missing credentials.
172
+
173
+## The `usesFixtures` Option
174
+
175
+When `usesFixtures: true` is set:
176
+
177
+- Working directory changes to `{testDir}/fixtures/`
178
+- Docker volume mounts at `fixtures/node_modules`
179
+- Fixture paths in `runFixture({ filename })` are relative to `fixtures/`
180
+
181
+Use this for tests that have their own `package.json` and need to run `npm install`:
182
+
183
+```typescript
184
+e2e(import.meta.url, {
185
+ usesFixtures: true,
186
+ defineTests: ({ runFixture }) => {
187
+ beforeAll(async () => {
188
+ // Both commands run in fixtures/ directory
189
+ result = await runFixture({
190
+ filename: 'index.mjs', // Resolves to fixtures/index.mjs
191
+ setup: 'npm install', // Runs in fixtures/
192
+ });
193
+ });
194
+ },
195
+});
196
+```
197
+
198
## Scripts
199
200
```bash
@@ -97,6 +205,76 @@ pnpm docker:build
205
pnpm docker:clean
206
```
207
208
+## DEBUG.log Output
209
+
210
+Each test suite generates a `DEBUG.log` file with structured output grouped by Node version:
211
+
212
+```
213
+================================================================================
214
+E2E Test: openai-zod4-compat
215
+Started: 2026-01-30T12:18:42.000Z
216
+Test file: ts/e2e-tests/runtimes/node/openai-zod4-compat/e2e.test.ts
217
+Node versions: 20.19.0, 22.12.0
218
+================================================================================
219
+
220
+################################################################################
221
+### Node.js 20.19.0
222
+################################################################################
223
+Image: composio-e2e-node:20.19.0
224
+
225
+--- Phase 1/2: setup ---
226
+Container: e2e-openai-zod4-compat-20-19-0-1769775520382-setup
227
+Command: npm install --legacy-peer-deps
228
+Duration: 2.55s
229
+Exit Code: 0 (success)
230
+
231
+[stdout]
232
+added 3 packages, and audited 5 packages in 2s
233
+
234
+[stderr]
235
+(empty)
236
+
237
+--- Phase 2/2: fixture ---
238
+Container: e2e-openai-zod4-compat-20-19-0-1769775520382-fixture
239
+Command: node index.mjs
240
+Duration: 0.56s
241
+Exit Code: 0 (success)
242
+
243
+[stdout]
244
+zod@4 works
245
+openai@5 works
246
+All packages work together!
247
+
248
+[stderr]
249
+(empty)
250
+
251
+################################################################################
252
+### Node.js 22.12.0 (SKIPPED)
253
+################################################################################
254
+Reason: Not selected via COMPOSIO_E2E_NODE_VERSION
255
+
256
+================================================================================
257
+Summary
258
+================================================================================
259
+Node.js 20.19.0: PASS (2 phases, 3.11s total)
260
+Node.js 22.12.0: SKIPPED
261
+
262
+Finished: 2026-01-30T12:18:46.500Z
263
+Total duration: 4.50s
264
+================================================================================
265
+```
266
+
267
+**Features:**
268
+
269
+- File cleared at start of each test run (no stale data)
270
+- Phases grouped by Node version for easy scanning
271
+- Visual hierarchy: `===` for file boundaries, `###` for versions, `---` for phases
272
+- Empty stdout/stderr shown as `(empty)`
273
+- Summary with pass/fail/skip status and timing
274
+
275
## Behavior
276
102
-Builds an isolated Docker container and runs the test command inside it. Docker is required.
277
+- Builds an isolated Docker container and runs the test command inside it
278
+- Docker is required
279
+- Tests run sequentially per Node version
280
+- Volume cleanup is best-effort (doesn't fail tests on cleanup errors)
ts/e2e-tests/_utils/package.json
+2
-1
@@ -21,7 +21,8 @@
21
},
22
"scripts": {
23
"docker:build": "bun run scripts/docker-build.ts",
24
- "docker:clean": "bun run scripts/docker-clean.ts"
24
+ "docker:clean": "bun run scripts/docker-clean.ts",
25
+ "typecheck": "tsc --noEmit"
26
},
27
"devDependencies": {
28
"typescript": "catalog:"
ts/e2e-tests/_utils/src/runner.ts
+6
-4
@@ -1,7 +1,7 @@
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, E2ETestResultWithSetup, NodeVersionMeta, RunFixtureOptions } from './types';
4
+import type { DefineTestsContext, 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';
@@ -352,7 +352,9 @@ function createDockerExecutors(
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> => {
355
+ function runFixture(options: { filename: string }): Promise<E2ETestResult>;
356
+ function runFixture(options: { filename: string; setup: string }): Promise<E2ETestResultWithSetup>;
357
+ async function runFixture(options: RunFixtureOptions): Promise<E2ETestResult | E2ETestResultWithSetup> {
358
const { filename, setup } = options;
359
360
// Smart mode: no setup (or empty string) = no volumes, just run directly
@@ -443,7 +445,7 @@ function createDockerExecutors(
445
// 6. Always cleanup volume (best-effort, doesn't throw)
446
await removeVolume(volumeName);
447
}
446
- };
448
+ }
449
450
/**
451
* Finalize this version's log output.
@@ -545,7 +547,7 @@ export function runE2E(config: RunE2EInternalConfig): void {
547
// Call user's defineTests with bun:test functions and Docker utilities
548
defineTests({
549
runCmd: (cmd) => executors.runCmd(cmd),
548
- runFixture: (opts) => executors.runFixture(opts),
550
+ runFixture: ((opts) => executors.runFixture(opts)) as DefineTestsContext['runFixture'],
551
});
552
553
// Write version section after all tests for this version complete
ts/e2e-tests/_utils/src/types.ts
+5
-2
@@ -76,10 +76,13 @@ export interface DefineTestsContext {
76
* const result = await runFixture({
77
* filename: 'index.mjs',
78
* setup: 'npm install --legacy-peer-deps',
79
- * }) as E2ETestResultWithSetup;
79
+ * });
80
* expect(result.setup.exitCode).toBe(0);
81
*/
82
- runFixture: (options: RunFixtureOptions) => Promise<E2ETestResult | E2ETestResultWithSetup>;
82
+ runFixture: {
83
+ (options: { filename: string }): Promise<E2ETestResult>;
84
+ (options: { filename: string; setup: string }): Promise<E2ETestResultWithSetup>;
85
+ };
86
}
87
88
/**
ts/e2e-tests/runtimes/node/cjs-basic/README.md
+15
-3
@@ -24,11 +24,23 @@ Many Node.js projects still use CommonJS. This suite ensures:
24
| constants | Constants namespace is accessible |
25
| logger | Logger instance is exported |
26
27
-## Isolation Tool
27
+## Fixture
28
+
29
+```
30
+fixtures/
31
+└── test.cjs # CommonJS test script using require()
32
+```
33
29
-**Docker** with Node.js versions: 20.18.0, 20.19.0, 22.12.0
34
+The fixture is a standalone `.cjs` file that:
35
+
36
+- Uses `require('@composio/core')` to import the package
37
+- Verifies each export exists and has the correct type
38
+- Attempts to instantiate `OpenAIProvider` to catch runtime errors
39
+- Outputs test results to stdout with pass/fail markers
40
+
41
+## Isolation Tool
42
31
-This ensures tests run against exact Node.js versions independent of the developer's local setup, catching version-specific module resolution issues.
43
+**Docker** with Node.js versions: 20.18.0, 20.19.0, 22.12.0.
44
45
## Running
46
ts/e2e-tests/runtimes/node/cjs-basic/e2e.test.ts
+2
-1
@@ -15,11 +15,12 @@ e2e(import.meta.url, {
15
'20.19.0',
16
'22.12.0',
17
],
18
+ usesFixtures: true,
19
defineTests: ({ runFixture }) => {
20
let result: E2ETestResult;
21
22
beforeAll(async () => {
22
- result = await runFixture({ filename: 'fixtures/test.cjs' });
23
+ result = await runFixture({ filename: 'test.cjs' });
24
});
25
26
describe('CommonJS compatibility', () => {
ts/e2e-tests/runtimes/node/esm-basic/README.md
+16
-3
@@ -25,11 +25,24 @@ ESM is the modern JavaScript module standard. This suite ensures:
25
| logger | Logger instance is exported |
26
| Named imports | Destructuring imports work correctly |
27
28
-## Isolation Tool
28
+## Fixture
29
+
30
+```
31
+fixtures/
32
+└── test.mjs # ESM test script using import()
33
+```
34
30
-**Docker** with Node.js versions: 20.18.0, 20.19.0, 22.12.0
35
+The fixture is a standalone `.mjs` file that:
36
+
37
+- Uses `import('@composio/core')` to dynamically import the package
38
+- Verifies each export exists and has the correct type
39
+- Tests destructured named imports (`{ Composio, OpenAIProvider }`)
40
+- Attempts to instantiate `OpenAIProvider` to catch runtime errors
41
+- Outputs test results to stdout with pass/fail markers
42
+
43
+## Isolation Tool
44
32
-This ensures tests run against exact Node.js versions independent of the developer's local setup, catching version-specific ESM resolution issues.
45
+**Docker** with Node.js versions: 20.18.0, 20.19.0, 22.12.0.
46
47
## Running
48
ts/e2e-tests/runtimes/node/esm-basic/e2e.test.ts
+2
-1
@@ -15,11 +15,12 @@ e2e(import.meta.url, {
15
'20.19.0',
16
'22.12.0',
17
],
18
+ usesFixtures: true,
19
defineTests: ({ runFixture }) => {
20
let result: E2ETestResult;
21
22
beforeAll(async () => {
22
- result = await runFixture({ filename: 'fixtures/test.mjs' });
23
+ result = await runFixture({ filename: 'test.mjs' });
24
});
25
26
describe('ESM compatibility', () => {
ts/e2e-tests/runtimes/node/json-schema-to-zod-v3/README.md
+15
@@ -23,6 +23,21 @@ The `@composio/json-schema-to-zod` package must support both Zod v3 and v4. This
23
| anyOf schemas | Union type conversion |
24
| Round-trip conversion | JSON Schema -> Zod -> JSON Schema preserves `additionalProperties` |
25
26
+## Test Setup
27
+
28
+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:
29
+
30
+```typescript
31
+import { jsonSchemaToZod, type JsonSchema } from '@composio/json-schema-to-zod';
32
+import zodToJsonSchema from 'zod-to-json-schema';
33
+```
34
+
35
+Tests use `bun:test` assertions to verify schema conversion and round-trip behavior.
36
+
37
+## Isolation Tool
38
+
39
+**Docker** with Node.js versions: current (as specified in `.nvmrc`).
40
+
41
## Running
42
43
```bash
ts/e2e-tests/runtimes/node/json-schema-to-zod-v4/README.md
+14
@@ -25,6 +25,20 @@ The `@composio/json-schema-to-zod` package must support both Zod v3 and v4. This
25
| Complex nested arrays | Arrays of objects with nested arrays |
26
| Union with constraints | anyOf with minLength, minimum, and required fields |
27
28
+## Test Setup
29
+
30
+This test runs **directly in Bun** (no Docker fixtures). The test file imports `@composio/json-schema-to-zod` from the monorepo workspace:
31
+
32
+```typescript
33
+import { jsonSchemaToZod, type JsonSchema } from '@composio/json-schema-to-zod';
34
+```
35
+
36
+Tests use `bun:test` assertions to verify schema conversion and parsing behavior.
37
+
38
+## Isolation Tool
39
+
40
+**Docker** with Node.js versions: current (as specified in `.nvmrc`).
41
+
42
## Running
43
44
```bash
ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v3/README.md
+24
-2
@@ -13,10 +13,32 @@ Issue [#2109](https://github.com/ComposioHQ/composio/issues/2109) tracks Mastra
13
14
## What It Tests
15
16
-| Test | Description |
17
-| -------------------- | -------------------------------------------------------- |
16
+| Test | Description |
17
+| -------------------- | ------------------------------------------------------------ |
18
| Tool Router workflow | Creates session, connects MCP, runs agent with Zod v3 schema |
19
20
+## Test Setup
21
+
22
+This test runs **directly in Bun** (no Docker fixtures). It imports packages from the monorepo workspace and makes real API calls:
23
+
24
+```typescript
25
+import { Composio } from '@composio/core';
26
+import { MastraProvider } from '@composio/mastra';
27
+import { MCPClient } from '@mastra/mcp';
28
+import { Agent } from '@mastra/core/agent';
29
+import { createOpenAI } from '@ai-sdk/openai';
30
+import { z } from 'zod';
31
+```
32
+
33
+**Required environment variables:**
34
+
35
+- `COMPOSIO_API_KEY` - Composio API key for Tool Router
36
+- `OPENAI_API_KEY` - OpenAI API key for agent LLM calls
37
+
38
+## Isolation Tool
39
+
40
+**Docker** with Node.js versions: 22.12.0.
41
+
42
## Running
43
44
```bash
ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v4/README.md
+24
-2
@@ -13,10 +13,32 @@ Issue [#2109](https://github.com/ComposioHQ/composio/issues/2109) tracks Mastra
13
14
## What It Tests
15
16
-| Test | Description |
17
-| -------------------- | -------------------------------------------------------- |
16
+| Test | Description |
17
+| -------------------- | ------------------------------------------------------------ |
18
| Tool Router workflow | Creates session, connects MCP, runs agent with Zod v4 schema |
19
20
+## Test Setup
21
+
22
+This test runs **directly in Bun** (no Docker fixtures). It imports packages from the monorepo workspace and makes real API calls:
23
+
24
+```typescript
25
+import { Composio } from '@composio/core';
26
+import { MastraProvider } from '@composio/mastra';
27
+import { MCPClient } from '@mastra/mcp';
28
+import { Agent } from '@mastra/core/agent';
29
+import { createOpenAI } from '@ai-sdk/openai';
30
+import { z } from 'zod';
31
+```
32
+
33
+**Required environment variables:**
34
+
35
+- `COMPOSIO_API_KEY` - Composio API key for Tool Router
36
+- `OPENAI_API_KEY` - OpenAI API key for agent LLM calls
37
+
38
+## Isolation Tool
39
+
40
+**Docker** with Node.js versions: 22.12.0.
41
+
42
## Running
43
44
```bash
ts/e2e-tests/runtimes/node/openai-zod4-compat/README.md
+24
-8
@@ -8,17 +8,33 @@ Issue [#2336](https://github.com/ComposioHQ/composio/issues/2336) reported peer
8
9
## What It Tests
10
11
-| Test | Description |
12
-| ------------------- | ------------------------------------------------------ |
13
-| npm install | Installs `@composio/core`, `openai`, and `zod@4` |
14
-| Package integration | Verifies all packages work together without conflicts |
15
-| wrapTool | Confirms OpenAI provider tool wrapping works |
11
+| Test | Description |
12
+| ------------------- | ----------------------------------------------------- |
13
+| npm install | Installs `@composio/core`, `openai`, and `zod@4` |
14
+| Package integration | Verifies all packages work together without conflicts |
15
+| wrapTool | Confirms OpenAI provider tool wrapping works |
16
17
-## Isolation Tool
17
+## Fixture
18
+
19
+```
20
+fixtures/
21
+├── index.mjs # Test script that imports and uses all packages
22
+└── package.json # Declares dependencies: @composio/core, openai@^6.16.0, zod@^4.3.5
23
+```
24
+
25
+The fixture uses `usesFixtures: true` with a setup phase to install dependencies at runtime:
26
19
-**Docker** with Node.js versions: 20.19.0, 22.12.0
27
+- `package.json` declares `@composio/core` (linked from monorepo), `openai`, and `zod@4`
28
+- `index.mjs` imports all three packages and verifies they work together
29
+- Tests `wrapTool` to ensure schema conversion works with Zod v4
30
+
31
+## Setup
32
+
33
+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.
34
+
35
+## Isolation Tool
36
21
-This ensures tests run against exact Node.js versions independent of the developer's local setup.
37
+**Docker** with Node.js versions: 20.19.0, 22.12.0.
38
39
## Running
40
ts/e2e-tests/runtimes/node/typescript-mjs-import-nodenext/README.md
+32
-3
@@ -22,11 +22,40 @@ This causes `TS2307: Cannot find module './foo.mjs'` errors.
22
| File existence | Verifies generated .ts files exist |
23
| TypeScript compilation | Runs `tsc --noEmit` to check import resolution |
24
25
-## Isolation Tool
25
+## Fixture
26
+
27
+```
28
+fixtures/
29
+├── index.mjs # Test runner script that generates and compiles TypeScript
30
+└── tsconfig.json # TypeScript config with moduleResolution: "nodenext"
31
+```
32
+
33
+The fixture script:
34
27
-**Docker** with Node.js version: current runtime
35
+1. Cleans up any previous generated files
36
+2. Runs `composio ts generate --toolkits entelligence --output-dir ./generated`
37
+3. Verifies generated `.ts` files exist
38
+4. Runs `npx tsc --noEmit` to check TypeScript compilation
39
+5. Fails if TS2307 errors occur (indicating `.mjs` import bug)
40
+
41
+**tsconfig.json:**
42
+
43
+```json
44
+{
45
+ "compilerOptions": {
46
+ "target": "ES2022",
47
+ "module": "NodeNext",
48
+ "moduleResolution": "nodenext",
49
+ "strict": true,
50
+ "noEmit": true
51
+ },
52
+ "include": ["generated/**/*.ts"]
53
+}
54
+```
55
+
56
+## Isolation Tool
57
29
-This test uses the current Node.js runtime version for simplicity.
58
+**Docker** with Node.js versions: current (as specified in `.nvmrc`).
59
60
## Running
61