chore: Add mockserver for e2e testing (#19104)

Author: mutdmour

packages/testing/containers/n8n-test-container-creation.ts

@@ -22,6 +22,7 @@ import {
 	setupRedis,
 	setupCaddyLoadBalancer,
 	pollContainerHttpEndpoint,
+	setupProxyServer,
 } from './n8n-test-container-dependencies';
 import { createSilentLogConsumer } from './n8n-test-container-utils';
 
@@ -31,6 +32,7 @@ const POSTGRES_IMAGE = 'postgres:16-alpine';
 const REDIS_IMAGE = 'redis:7-alpine';
 const CADDY_IMAGE = 'caddy:2-alpine';
 const N8N_E2E_IMAGE = 'n8nio/n8n:local';
+const MOCKSERVER_IMAGE = 'mockserver/mockserver:5.15.0';
 
 // Default n8n image (can be overridden via N8N_DOCKER_IMAGE env var)
 const N8N_IMAGE = process.env.N8N_DOCKER_IMAGE ?? N8N_E2E_IMAGE;
@@ -78,6 +80,7 @@ export interface N8NConfig {
 		memory?: number; // in GB
 		cpu?: number; // in cores
 	};
+	proxyServerEnabled?: boolean;
 }
 
 export interface N8NStack {
@@ -109,15 +112,22 @@ export interface N8NStack {
  * });
  */
 export async function createN8NStack(config: N8NConfig = {}): Promise<N8NStack> {
-	const { postgres = false, queueMode = false, env = {}, projectName, resourceQuota } = config;
+	const {
+		postgres = false,
+		queueMode = false,
+		env = {},
+		proxyServerEnabled = false,
+		projectName,
+		resourceQuota,
+	} = config;
 	const queueConfig = normalizeQueueConfig(queueMode);
 	const usePostgres = postgres || !!queueConfig;
 	const uniqueProjectName = projectName ?? `n8n-stack-${Math.random().toString(36).substring(7)}`;
 	const containers: StartedTestContainer[] = [];
 
 	const mainCount = queueConfig?.mains ?? 1;
 	const needsLoadBalancer = mainCount > 1;
-	const needsNetwork = usePostgres || !!queueConfig || needsLoadBalancer;
+	const needsNetwork = usePostgres || !!queueConfig || needsLoadBalancer || proxyServerEnabled;
 
 	let network: StartedNetwork | undefined;
 	if (needsNetwork) {
@@ -182,6 +192,31 @@ export async function createN8NStack(config: N8NConfig = {}): Promise<N8NStack>
 		}
 	}
 
+	if (proxyServerEnabled) {
+		assert(network, 'Network should be created for ProxyServer');
+		const hostname = 'proxyserver';
+		const port = 1080;
+		const url = `http://${hostname}:${port}`;
+		const proxyServerContainer: StartedTestContainer = await setupProxyServer({
+			proxyServerImage: MOCKSERVER_IMAGE,
+			projectName: uniqueProjectName,
+			network,
+			hostname,
+			port,
+		});
+
+		containers.push(proxyServerContainer);
+
+		environment = {
+			...environment,
+			// Configure n8n to proxy all HTTP requests through ProxyServer
+			HTTP_PROXY: url,
+			HTTPS_PROXY: url,
+			// Ensure https requests can be proxied without SSL issues
+			...(proxyServerEnabled ? { NODE_TLS_REJECT_UNAUTHORIZED: '0' } : {}),
+		};
+	}
+
 	let baseUrl: string;
 
 	if (needsLoadBalancer) {

packages/testing/containers/n8n-test-container-dependencies.ts

@@ -316,6 +316,40 @@ export async function pollContainerHttpEndpoint(
 	);
 }
 
+export async function setupProxyServer({
+	proxyServerImage,
+	projectName,
+	network,
+	hostname,
+	port,
+}: {
+	proxyServerImage: string;
+	projectName: string;
+	network: StartedNetwork;
+	hostname: string;
+	port: number;
+}): Promise<StartedTestContainer> {
+	const { consumer, throwWithLogs } = createSilentLogConsumer();
+
+	try {
+		return await new GenericContainer(proxyServerImage)
+			.withNetwork(network)
+			.withNetworkAliases(hostname)
+			.withExposedPorts(port)
+			// Wait.forListeningPorts strategy did not work here for some reason
+			.withWaitStrategy(Wait.forLogMessage(`INFO ${port} started on port: ${port}`))
+			.withLabels({
+				'com.docker.compose.project': projectName,
+				'com.docker.compose.service': 'proxyserver',
+			})
+			.withName(`${projectName}-proxyserver`)
+			.withReuse()
+			.withLogConsumer(consumer)
+			.start();
+	} catch (error) {
+		return throwWithLogs(error);
+	}
+}
+
 // TODO: Look at Ollama container?
 // TODO: Look at MariaDB container?
-// TODO: Look at MockServer container, could we use this for mocking out external services?

packages/testing/playwright/README.md

@@ -37,6 +37,7 @@ test('postgres only @mode:postgres', ...)            // Mode-specific
 test('needs clean db @db:reset', ...)                // Sequential per worker
 test('chaos test @mode:multi-main @chaostest', ...) // Isolated per worker
 test('cloud resource test @cloud:trial', ...)       // Cloud resource constraints
+test('proxy test @capability:proxy', ...)           // Requires proxy server capability
 ```
 
 ## Fixture Selection
@@ -73,5 +74,48 @@ test('Performance under constraints @cloud:trial', async ({ n8n, api }) => {
 - **utils**: Utility functions (string manipulation, helpers, etc.)
 - **workflows**: Test workflow JSON files for import/reuse
 
+## Writing Tests with Proxy
+
+You can use ProxyServer to mock API requests.
+
+```typescript
+import { test, expect } from '../fixtures/base';
+
+// The `@capability:proxy` tag ensures tests only run when proxy infrastructure is available.
+test.describe('Proxy tests @capability:proxy', () => {
+  test('should mock HTTP requests', async ({ proxyServer, n8n }) => {
+    // Create mock expectations
+    await proxyServer.createGetExpectation('/api/data', { result: 'mocked' });
+
+    // Execute workflow that makes HTTP requests
+    await n8n.canvas.openNewWorkflow();
+    // ... test implementation
+
+    // Verify requests were proxied
+    expect(await proxyServer.wasGetRequestMade('/api/data')).toBe(true);
+  });
+});
+```
+
+### Recording and replaying requests
+
+The ProxyServer service supports recording HTTP requests for test mocking and replay. All proxied requests are automatically recorded by the mock server as described in the [Mock Server documentation](https://www.mock-server.com/proxy/record_and_replay.html).
+
+```typescript
+// Record all requests
+await proxyServer.recordExpectations();
+
+// Record requests with matching criteria
+await proxyServer.recordExpectations({
+  method: 'POST',
+  path: '/api/workflows',
+  queryStringParameters: {
+    'userId': ['123']
+  }
+});
+```
+
+Recorded expectations are saved as JSON files in the `expectations/` directory with unique names based on the request details. When the ProxyServer fixture initializes, all saved expectations are automatically loaded and mocked for subsequent test runs.
+
 ## Writing Tests
 For guidelines on writing new tests, see [CONTRIBUTING.md](./CONTRIBUTING.md).

packages/testing/playwright/expectations/GET-mock_endpoint.json

@@ -0,0 +1,26 @@
+{
+	"httpRequest": {
+		"method": "GET",
+		"path": "/mock-endpoint"
+	},
+	"httpResponse": {
+		"statusCode": 200,
+		"headers": {
+			"Content-Type": ["application/json"]
+		},
+		"body": {
+			"userId": 1,
+			"id": 1,
+			"title": "delectus aut autem",
+			"completed": false
+		}
+	},
+	"id": "511d9c87-9ee3-4af8-8729-ca13b0a70e89",
+	"priority": 0,
+	"timeToLive": {
+		"unlimited": true
+	},
+	"times": {
+		"remainingTimes": 1
+	}
+}

packages/testing/playwright/fixtures/base.ts

@@ -6,6 +6,7 @@ import { ContainerTestHelpers } from 'n8n-containers/n8n-test-container-helpers'
 import { setupDefaultInterceptors } from '../config/intercepts';
 import { n8nPage } from '../pages/n8nPage';
 import { ApiHelpers } from '../services/api-helper';
+import { ProxyServer } from '../services/proxy-server';
 import { TestError, type TestRequirements } from '../Types';
 import { setupTestRequirements } from '../utils/requirements';
 
@@ -14,6 +15,7 @@ type TestFixtures = {
 	api: ApiHelpers;
 	baseURL: string;
 	setupRequirements: (requirements: TestRequirements) => Promise<void>;
+	proxyServer: ProxyServer;
 };
 
 type WorkerFixtures = {
@@ -31,6 +33,7 @@ interface ContainerConfig {
 		workers: number;
 	};
 	env?: Record<string, string>;
+	proxyServerEnabled?: boolean;
 }
 
 /**
@@ -158,6 +161,31 @@ export const test = base.extend<TestFixtures, WorkerFixtures>({
 
 		await use(setupFunction);
 	},
+
+	proxyServer: async ({ n8nContainer }, use) => {
+		// n8nContainer is "null" if running tests in "local" mode
+		if (!n8nContainer) {
+			throw new TestError(
+				'Testing with Proxy server is not supported when using N8N_BASE_URL environment variable. Remove N8N_BASE_URL to use containerized testing.',
+			);
+		}
+
+		const proxyServerContainer = n8nContainer.containers.find((container) =>
+			container.getName().endsWith('proxyserver'),
+		);
+
+		// proxy server is not initialized in local mode (it be only supported in container modes)
+		// tests that require proxy server should have "@capability:proxy" so that they are skipped in local mode
+		if (!proxyServerContainer) {
+			throw new TestError('Proxy server container not initialized. Cannot initialize client.');
+		}
+
+		const serverUrl = `http://${proxyServerContainer?.getHost()}:${proxyServerContainer?.getFirstMappedPort()}`;
+		const proxyServer = new ProxyServer(serverUrl);
+		await proxyServer.loadExpectations();
+
+		await use(proxyServer);
+	},
 });
 
 export { expect };

packages/testing/playwright/package.json

@@ -36,6 +36,7 @@
     "n8n-workflow": "workspace:*",
     "nanoid": "catalog:",
     "tsx": "catalog:",
+    "mockserver-client": "^5.15.0",
     "zod": "catalog:"
   }
 }

packages/testing/playwright/pages/CanvasPage.ts

@@ -2,6 +2,7 @@ import type { Locator } from '@playwright/test';
 import { nanoid } from 'nanoid';
 
 import { BasePage } from './BasePage';
+import { ROUTES } from '../config/constants';
 import { resolveFromRoot } from '../utils/path-helper';
 
 export class CanvasPage extends BasePage {
@@ -494,14 +495,18 @@ export class CanvasPage extends BasePage {
 		// Set fixed time using Playwright's clock API
 		await this.page.clock.setFixedTime(timestamp);
 
-		await this.page.goto('/workflow/new');
+		await this.openNewWorkflow();
 	}
 
 	async addNodeWithSubItem(searchText: string, subItemText: string): Promise<void> {
 		await this.addNode(searchText);
 		await this.nodeCreatorSubItem(subItemText).click();
 	}
 
+	async openNewWorkflow() {
+		await this.page.goto(ROUTES.NEW_WORKFLOW_PAGE);
+	}
+
 	getRagCalloutTip(): Locator {
 		return this.page.getByText('Tip: Get a feel for vector stores in n8n with our');
 	}

packages/testing/playwright/playwright-projects.ts

@@ -11,8 +11,11 @@ const CONTAINER_ONLY = new RegExp(`@capability:(${CONTAINER_ONLY_TAGS.join('|')}
 // In local run they are a "dependency" which means they will be skipped if earlier tests fail, not ideal but needed for isolation
 const SERIAL_EXECUTION = /@db:reset/;
 
+// Tags that require proxy server
+const REQUIRES_PROXY_SERVER = /@capability:proxy/;
+
 const CONTAINER_CONFIGS: Array<{ name: string; config: N8NConfig }> = [
-	{ name: 'standard', config: {} },
+	{ name: 'standard', config: { proxyServerEnabled: true } },
 	{ name: 'postgres', config: { postgres: true } },
 	{ name: 'queue', config: { queueMode: true } },
 	{ name: 'multi-main', config: { queueMode: { mains: 2, workers: 1 } } },
@@ -35,17 +38,23 @@ export function getProjects(): Project[] {
 				name: 'ui:isolated',
 				testDir: './tests/ui',
 				grep: SERIAL_EXECUTION,
+				grepInvert: REQUIRES_PROXY_SERVER,
 				workers: 1,
 				use: { baseURL: process.env.N8N_BASE_URL },
 			},
 		);
 	} else {
 		for (const { name, config } of CONTAINER_CONFIGS) {
+			const grepInvertPatterns = [SERIAL_EXECUTION.source];
+			if (!config.proxyServerEnabled) {
+				grepInvertPatterns.push(REQUIRES_PROXY_SERVER.source);
+			}
+
 			projects.push(
 				{
 					name: `${name}:ui`,
 					testDir: './tests/ui',
-					grepInvert: SERIAL_EXECUTION,
+					grepInvert: new RegExp(grepInvertPatterns.join('|')),
 					timeout: name === 'standard' ? 60000 : 180000, // 60 seconds for standard container test, 180 for containers to allow startup etc
 					fullyParallel: true,
 					use: { containerConfig: config },
@@ -54,6 +63,7 @@ export function getProjects(): Project[] {
 					name: `${name}:ui:isolated`,
 					testDir: './tests/ui',
 					grep: SERIAL_EXECUTION,
+					grepInvert: !config.proxyServerEnabled ? REQUIRES_PROXY_SERVER : undefined,
 					workers: 1,
 					use: { containerConfig: config },
 				},