Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | # E2E Tests |
| 2 | |
| 3 | End-to-end tests for `@composio/core` and the CLI across different runtimes. |
| 4 | |
| 5 | ## Directory Structure |
| 6 | |
| 7 | ``` |
| 8 | ts/e2e-tests/ |
| 9 | ├── _utils/ # Shared test infrastructure |
| 10 | │ ├── Dockerfile.node # Docker image for Node.js tests |
| 11 | │ ├── Dockerfile.cli # Docker image for CLI tests (scratch) |
| 12 | │ ├── scripts/ # Docker build and cleanup scripts |
| 13 | │ │ ├── docker-build.ts # Pre-build images for all Node/CLI versions |
| 14 | │ │ └── docker-clean.ts # Remove all e2e Docker images |
| 15 | │ ├── src/ # TypeScript runner utilities |
| 16 | │ │ ├── config.ts # Configuration utilities |
| 17 | │ │ ├── const.ts # Well-known Node.js versions and timeouts |
| 18 | │ │ ├── e2e.ts # Main e2e test entry point |
| 19 | │ │ ├── image-lifecycle.ts # Docker image build/run utilities |
| 20 | │ │ ├── index.ts # Public exports |
| 21 | │ │ ├── runner.ts # Docker test runner |
| 22 | │ │ ├── sanitize.ts # Output sanitization utilities |
| 23 | │ │ ├── types.ts # TypeScript type definitions |
| 24 | │ │ └── volume.ts # Docker volume management |
| 25 | │ └── README.md # Utils documentation |
| 26 | ├── runtimes/ |
| 27 | ├── node/ # Node.js runtime tests |
| 28 | │ ├── cjs-basic/ # Node.js 22 require(esm) interop tests |
| 29 | │ ├── claude-agent-sdk/ # @composio/claude-agent-sdk + Claude Agent SDK MCP tests |
| 30 | │ ├── custom-tools/ # Custom local tools execution (session.execute, proxyExecute, Zod validation) |
| 31 | │ ├── esm-basic/ # ESM compatibility tests |
| 32 | │ ├── json-schema-to-zod-v3/ # @composio/json-schema-to-zod + Zod v3 tests |
| 33 | │ ├── json-schema-to-zod-v4/ # @composio/json-schema-to-zod + Zod v4 tests |
| 34 | │ ├── mastra-tool-router-zod-v3/ # @composio/mastra Tool Router + Zod v3 tests |
| 35 | │ ├── mastra-tool-router-zod-v4/ # @composio/mastra Tool Router + Zod v4 tests |
| 36 | │ ├── openai-zod4-compat/ # OpenAI + Zod v4 compatibility tests |
| 37 | │ ├── tool-router-files/ # Tool Router session files (list, upload, download, delete) |
| 38 | │ ├── tool-router-pagination/ # Tool Router session.toolkits() cursor pagination |
| 39 | │ ├── tool-router-proxy-execute/ # Tool Router proxyExecute session option (live API) |
| 40 | │ ├── tool-router-session-update/ # Tool Router session.update() with default options (live API) |
| 41 | │ └── typescript-mjs-import-nodenext/ # TypeScript moduleResolution: nodenext tests |
| 42 | └── cloudflare/ # Cloudflare runtime tests |
| 43 | ├── cf-workers-basic/ # Basic Cloudflare Workers tests |
| 44 | ├── cf-workers-files/ # Cloudflare Workers file handling tests |
| 45 | └── cf-workers-tool-router-ai/ # Cloudflare Workers AI SDK tool router tests |
| 46 | └── cli/ # CLI runtime tests (scratch) |
| 47 | ├── version/ # composio version command tests |
| 48 | ├── whoami/ # composio whoami command tests |
| 49 | └── toolkits/ # composio toolkits command tests |
| 50 | ├── list/ # composio toolkits list tests |
| 51 | ├── info/ # composio toolkits info tests |
| 52 | └── search/ # composio toolkits search tests |
| 53 | ``` |
| 54 | |
| 55 | ## Running Tests |
| 56 | |
| 57 | ### All E2E Tests |
| 58 | |
| 59 | ```bash |
| 60 | pnpm test:e2e |
| 61 | ``` |
| 62 | |
| 63 | ### Node.js Tests Only |
| 64 | |
| 65 | ```bash |
| 66 | pnpm test:e2e:node |
| 67 | ``` |
| 68 | |
| 69 | Runs Node.js tests in Docker using `bun test`. The default Node.js version is determined by `mise.toml`. |
| 70 | |
| 71 | To run with a specific Node.js version: |
| 72 | |
| 73 | ```bash |
| 74 | COMPOSIO_E2E_NODE_VERSION=22.23.5 pnpm test:e2e:node |
| 75 | ``` |
| 76 | |
| 77 | ### Cloudflare Workers Tests Only |
| 78 | |
| 79 | ```bash |
| 80 | pnpm test:e2e:cloudflare |
| 81 | ``` |
| 82 | |
| 83 | ### CLI Tests Only |
| 84 | |
| 85 | ```bash |
| 86 | pnpm test:e2e:cli |
| 87 | ``` |
| 88 | |
| 89 | To run with a specific CLI version: |
| 90 | |
| 91 | ```bash |
| 92 | COMPOSIO_E2E_CLI_VERSION=0.1.24 pnpm test:e2e:cli |
| 93 | ``` |
| 94 | |
| 95 | ## Adding New Tests |
| 96 | |
| 97 | ### Node.js Runtime Tests |
| 98 | |
| 99 | 1. Create a new directory under `runtimes/node/` (e.g., `runtimes/node/my-test`) |
| 100 | 2. Add a `package.json` with name `@e2e-tests/node-my-test` |
| 101 | 3. Add `test:e2e` and `test:e2e:node` scripts |
| 102 | 4. Create an `e2e.test.ts` file with inline configuration: |
| 103 | |
| 104 | ```typescript |
| 105 | import { e2e, type E2ETestResult } from '@e2e-tests/utils'; |
| 106 | import { TIMEOUTS } from '@e2e-tests/utils/const'; |
| 107 | import { describe, it, expect, beforeAll } from 'bun:test'; |
| 108 | |
| 109 | e2e(import.meta.url, { |
| 110 | versions: { |
| 111 | node: ['22.23.5', '24.22.3', '26.13.1'], // Optional: defaults to the current version in mise.toml |
| 112 | }, |
| 113 | env: { MY_VAR: process.env.MY_VAR }, // Optional: env vars (validated at startup) |
| 114 | defineTests: ({ runtime, runFixture }) => { |
| 115 | let result: E2ETestResult; |
| 116 | |
| 117 | beforeAll(async () => { |
| 118 | result = await runFixture({ filename: 'fixtures/test.mjs' }); |
| 119 | }, TIMEOUTS.FIXTURE); |
| 120 | |
| 121 | describe('output', () => { |
| 122 | it('exits successfully', () => { |
| 123 | expect(result.exitCode).toBe(0); |
| 124 | }); |
| 125 | |
| 126 | it('contains expected output', () => { |
| 127 | expect(result.stdout).toContain('expected text'); |
| 128 | }); |
| 129 | }); |
| 130 | }, |
| 131 | }); |
| 132 | ``` |
| 133 | |
| 134 | 5. Add fixture files in a `fixtures/` directory |
| 135 | |
| 136 | ### Tests with External Dependencies (npm install) |
| 137 | |
| 138 | For tests that need to install npm packages at runtime, use `usesFixtures: true` and the `setup` option: |
| 139 | |
| 140 | ```typescript |
| 141 | import { e2e, type E2ETestResultWithSetup } from '@e2e-tests/utils'; |
| 142 | import { TIMEOUTS } from '@e2e-tests/utils/const'; |
| 143 | import { describe, it, expect, beforeAll } from 'bun:test'; |
| 144 | |
| 145 | e2e(import.meta.url, { |
| 146 | versions: { |
| 147 | node: ['22.23.5', '24.22.3', '26.13.1'], |
| 148 | }, |
| 149 | usesFixtures: true, // Sets cwd to fixtures/ directory |
| 150 | env: { MY_API_KEY: process.env.MY_API_KEY }, |
| 151 | defineTests: ({ runFixture }) => { |
| 152 | let result: E2ETestResultWithSetup; |
| 153 | |
| 154 | beforeAll(async () => { |
| 155 | result = await runFixture({ |
| 156 | filename: 'index.mjs', |
| 157 | setup: 'npm install --legacy-peer-deps', // Runs before fixture |
| 158 | }); |
| 159 | }, TIMEOUTS.FIXTURE); |
| 160 | |
| 161 | describe('setup', () => { |
| 162 | it('npm install completes successfully', () => { |
| 163 | expect(result.setup.exitCode).toBe(0); |
| 164 | }); |
| 165 | }); |
| 166 | |
| 167 | describe('fixture', () => { |
| 168 | it('exits successfully', () => { |
| 169 | expect(result.exitCode).toBe(0); |
| 170 | }); |
| 171 | }); |
| 172 | }, |
| 173 | }); |
| 174 | ``` |
| 175 | |
| 176 | ### Cloudflare Runtime Tests |
| 177 | |
| 178 | 1. Create a new directory under `runtimes/cloudflare/` (e.g., `runtimes/cloudflare/my-test`) |
| 179 | 2. Add a `package.json` with name `@e2e-tests/cf-my-test` |
| 180 | 3. Add `test:e2e` and `test:e2e:cloudflare` scripts |
| 181 | 4. Configure vitest with `@cloudflare/vitest-pool-workers` |
| 182 | |
| 183 | ### CLI Runtime Tests |
| 184 | |
| 185 | 1. Create a new directory under `cli/` (e.g., `cli/my-test`) |
| 186 | 2. Add a `package.json` with name `@e2e-tests/cli-my-test` |
| 187 | 3. Add `test:e2e` and `test:e2e:cli` scripts |
| 188 | 4. Create an `e2e.test.ts` file with inline configuration: |
| 189 | |
| 190 | ```typescript |
| 191 | import { e2e, sanitizeOutput, type E2ETestResult } from '@e2e-tests/utils'; |
| 192 | import { TIMEOUTS } from '@e2e-tests/utils/const'; |
| 193 | import { describe, it, expect, beforeAll } from 'bun:test'; |
| 194 | |
| 195 | e2e(import.meta.url, { |
| 196 | versions: { |
| 197 | cli: ['current'], |
| 198 | }, |
| 199 | defineTests: ({ runCmd }) => { |
| 200 | let result: E2ETestResult; |
| 201 | |
| 202 | beforeAll(async () => { |
| 203 | result = await runCmd('composio version'); |
| 204 | }, TIMEOUTS.FIXTURE); |
| 205 | |
| 206 | describe('output', () => { |
| 207 | it('exits successfully', () => { |
| 208 | expect(result.exitCode).toBe(0); |
| 209 | }); |
| 210 | |
| 211 | it('stdout matches snapshot', () => { |
| 212 | expect(sanitizeOutput(result.stdout)).toMatchSnapshot(); |
| 213 | }); |
| 214 | }); |
| 215 | }, |
| 216 | }); |
| 217 | ``` |
| 218 | |
| 219 | ## Debugging |
| 220 | |
| 221 | Each test suite generates an ephemereal `DEBUG.log` file in its directory with structured output: |
| 222 | |
| 223 | ``` |
| 224 | ================================================================================ |
| 225 | E2E Test: my-test |
| 226 | Started: 2026-01-30T12:18:42.000Z |
| 227 | Test file: ts/e2e-tests/runtimes/node/my-test/e2e.test.ts |
| 228 | Runtime versions: Node.js 22.23.5, Node.js 24.22.3, Node.js 26.13.1 |
| 229 | ================================================================================ |
| 230 | |
| 231 | ################################################################################ |
| 232 | ### Node.js 22.23.5 |
| 233 | ################################################################################ |
| 234 | Image: composio-e2e-node:22.23.5 |
| 235 | |
| 236 | --- Phase 1/2: setup --- |
| 237 | Container: e2e-my-test-22-23-5-1769775520382-setup |
| 238 | Command: npm install |
| 239 | Duration: 2.55s |
| 240 | Exit Code: 0 (success) |
| 241 | |
| 242 | [stdout] |
| 243 | added 3 packages in 2s |
| 244 | |
| 245 | [stderr] |
| 246 | (empty) |
| 247 | |
| 248 | --- Phase 2/2: fixture --- |
| 249 | Container: e2e-my-test-22-23-5-1769775520382-fixture |
| 250 | Command: node index.mjs |
| 251 | Duration: 0.56s |
| 252 | Exit Code: 0 (success) |
| 253 | |
| 254 | [stdout] |
| 255 | Test passed! |
| 256 | |
| 257 | [stderr] |
| 258 | (empty) |
| 259 | |
| 260 | ================================================================================ |
| 261 | Summary |
| 262 | ================================================================================ |
| 263 | Node.js 22.23.5: PASS (2 phases, 3.11s total) |
| 264 | Node.js 24.22.3: PASS (2 phases, 3.09s total) |
| 265 | Node.js 26.13.1: PASS (2 phases, 3.08s total) |
| 266 | |
| 267 | Finished: 2026-01-30T12:18:46.500Z |
| 268 | Total duration: 4.50s |
| 269 | ================================================================================ |
| 270 | ``` |