How to Run E2E Tests Across Node.js, Deno, and Cloudflare Workers in Composio

Composio provides a Docker-based E2E testing framework in ts/e2e-tests that orchestrates test execution across Node.js, Deno, and Cloudflare Workers using runtime-specific Docker images and a unified test helper.

The ComposioHQ/composio repository maintains a comprehensive end-to-end test suite located in ts/e2e-tests designed to validate SDK compatibility across multiple JavaScript runtimes. This guide explains how to run E2E tests across Node.js, Deno, and Cloudflare Workers runtimes using the repository's Docker-based testing infrastructure and configuration utilities.

E2E Test Architecture and Runtime Support

The testing framework isolates each runtime inside dedicated Docker containers, ensuring consistent environments and eliminating local dependency conflicts.

Node.js Testing with Docker

Node.js tests execute inside containers built from ts/e2e-tests/_utils/Dockerfile.node. The default Node version is read from .nvmrc, though you can override this via environment variables. The image runs bun test against the target Node installation to verify ESM and CommonJS compatibility.

Deno Runtime Validation

Deno tests utilize ts/e2e-tests/_utils/Dockerfile.deno and import packages using the npm: specifier. This validates that the Composio SDK functions correctly under Deno's permission model and module resolution system.

Cloudflare Workers Simulation

Cloudflare Workers tests run inside a container defined in ts/e2e-tests/_utils/Dockerfile.cli, using @cloudflare/vitest-pool-workers to simulate the Workers runtime environment. This ensures compatibility with the Cloudflare Workers platform constraints and API surface.

Core Testing Infrastructure

The framework's orchestration logic resides in ts/e2e-tests/_utils/src/:

• src/config.ts – Reads environment variables (COMPOSIO_E2E_NODE_VERSION, COMPOSIO_E2E_DENO_VERSION, COMPOSIO_E2E_CLI_VERSION) to determine which runtime versions to test.
• src/runner.ts – Handles Docker image builds, container lifecycle management, and log streaming during test execution.
• src/e2e.ts – Provides the e2e(import.meta.url, { … }) helper used by every test suite to define runtime targets and test logic.

Running the E2E Test Suite

Executing the Full Test Matrix

To run E2E tests across all supported runtimes simultaneously:

pnpm test:e2e

This command performs the following steps:

1. Builds Docker images for Node.js, Deno, and Cloudflare Workers.
2. Launches containers for each runtime version defined in the configuration.
3. Executes every e2e.test.ts file across those containers.
4. Generates a DEBUG.log file per suite with structured output for troubleshooting.

Targeting Individual Runtimes

Run tests for a specific runtime without executing the full matrix:

# Node.js only (uses default from .nvmrc)

pnpm test:e2e:node

# Deno only (uses default from .dvmrc)

pnpm test:e2e:deno

# Cloudflare Workers only

pnpm test:e2e:cloudflare

Overriding Runtime Versions

Override default versions using environment variables without modifying repository files:

# Test against specific Node.js versions

COMPOSIO_E2E_NODE_VERSION=22.12.0 pnpm test:e2e:node

# Test against specific Deno version

COMPOSIO_E2E_DENO_VERSION=2.6.7 pnpm test:e2e:deno

These variables are processed by src/config.ts and passed as Docker build arguments, enabling testing against any supported runtime version.

Creating Custom E2E Tests

Add new test cases to validate specific features or edge cases:

1. Create a test directory under the appropriate runtime folder (e.g., ts/e2e-tests/runtimes/node/my-feature/).

2. Add a package.json with a unique scoped name:

   {
     "name": "@e2e-tests/node-my-feature",
     "scripts": {
       "test:e2e": "bun test",
       "test:e2e:node": "bun test"
     }
   }

3. Write e2e.test.ts using the framework helper:

   import { e2e, type E2ETestResult } from '@e2e-tests/utils';
   import { TIMEOUTS } from '@e2e-tests/utils/const';
   import { describe, it, expect, beforeAll } from 'bun:test';
   
   e2e(import.meta.url, {
     versions: {
       node: ['20.18.0', '22.12.0'],
     },
     defineTests: ({ runtime, runFixture }) => {
       let result: E2ETestResult;
   
       beforeAll(async () => {
         result = await runFixture({ filename: 'fixtures/example.mjs' });
       }, TIMEOUTS.FIXTURE);
   
       describe('output', () => {
         it('exits successfully', () => expect(result.exitCode).toBe(0));
         it('contains expected text', () => expect(result.stdout).toContain('hello world'));
       });
     },
   });

4. Add fixture files under a fixtures/ subdirectory if the test requires external assets or source code.

The test is automatically discovered because the framework scans for e2e.test.ts files under ts/e2e-tests/.

Key Configuration Files and Utilities

Path	Purpose
ts/e2e-tests/README.md	Overview of the E2E infrastructure, commands, and version handling.
ts/e2e-tests/_utils/Dockerfile.node	Docker definition for Node.js runtime testing.
ts/e2e-tests/_utils/Dockerfile.deno	Docker definition for Deno runtime testing.
ts/e2e-tests/_utils/Dockerfile.cli	Docker definition for Cloudflare Workers / CLI testing.
ts/e2e-tests/_utils/src/config.ts	Reads environment variables for version overrides.
ts/e2e-tests/_utils/src/runner.ts	Docker orchestration and container lifecycle management.
ts/e2e-tests/_utils/src/e2e.ts	Test definition helper used by all E2E suites.
ts/e2e-tests/runtimes/node/esm-basic/README.md	Example documentation for Node.js ESM compatibility tests.
ts/e2e-tests/runtimes/deno/esm-basic/README.md	Example documentation for Deno ESM compatibility tests.
ts/e2e-tests/runtimes/cloudflare/cf-workers-basic/README.md	Example documentation for Cloudflare Workers tests.

Summary

• Composio maintains a comprehensive E2E testing framework in ts/e2e-tests that validates SDK compatibility across Node.js, Deno, and Cloudflare Workers.
• Each runtime executes inside isolated Docker containers defined in Dockerfile.node, Dockerfile.deno, and Dockerfile.cli to ensure environment consistency.
• The orchestration layer in _utils/src/ provides configuration management (config.ts), Docker lifecycle handling (runner.ts), and a test definition helper (e2e.ts).
• Execute the full test matrix with pnpm test:e2e, or target specific runtimes using pnpm test:e2e:node, pnpm test:e2e:deno, or pnpm test:e2e:cloudflare.
• Override default runtime versions via environment variables (COMPOSIO_E2E_NODE_VERSION, COMPOSIO_E2E_DENO_VERSION) without modifying repository files.

Frequently Asked Questions

How do I run E2E tests for only one runtime without executing the full matrix?

Use the runtime-specific pnpm scripts to isolate testing to a single environment. For Node.js, run pnpm test:e2e:node. For Deno, use pnpm test:e2e:deno. For Cloudflare Workers, execute pnpm test:e2e:cloudflare. Each command builds the corresponding Docker image and runs only the tests defined for that runtime, skipping the full cross-runtime matrix.

Can I test against specific versions of Node.js or Deno?

Yes. Set the COMPOSIO_E2E_NODE_VERSION or COMPOSIO_E2E_DENO_VERSION environment variables before executing the test command. For example, COMPOSIO_E2E_NODE_VERSION=22.12.0 pnpm test:e2e:node tests against Node.js 22.12.0. These variables are read by ts/e2e-tests/_utils/src/config.ts and passed as build arguments to Docker, enabling validation against any supported runtime version.

What Docker images are used for each runtime?

The framework uses three distinct Docker images defined in the _utils directory. Node.js tests use composio-e2e-node:<version> built from Dockerfile.node. Deno tests use composio-e2e-deno:<version> built from Dockerfile.deno. Cloudflare Workers tests use composio-e2e-cloudflare built from Dockerfile.cli. Each image encapsulates the runtime environment and test runner configuration to ensure consistent, reproducible test execution across different machines and CI environments.

How do I add a new test case for a specific runtime?

Create a new directory under the appropriate runtime folder in ts/e2e-tests/runtimes/ (e.g., node/my-feature/). Add a package.json with a unique scoped name (e.g., @e2e-tests/node-my-feature) and the required test scripts. Write an e2e.test.ts file that imports the e2e helper from @e2e-tests/utils and defines your test logic using the defineTests callback. Include any necessary fixture files in a fixtures/ subdirectory. The framework automatically discovers and executes the new test when you run the suite.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}