test: Align proxy service helper and add local dev service stack (no-changelog) (#25467)

Author: shortstacked

packages/testing/containers/n8n-start-stack.ts

@@ -1,12 +1,16 @@
 #!/usr/bin/env tsx
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 
 import { DockerImageNotFoundError } from './docker-image-not-found-error';
 import { BASE_PERFORMANCE_PLANS, isValidPerformancePlan } from './performance-plans';
+import { createServiceStack } from './service-stack';
 import type { CloudflaredResult } from './services/cloudflared';
 import type { KeycloakResult } from './services/keycloak';
 import type { MailpitResult } from './services/mailpit';
 import type { NgrokResult } from './services/ngrok';
+import { services as SERVICE_REGISTRY } from './services/registry';
 import type { TracingResult } from './services/tracing';
 import type { ServiceName } from './services/types';
 import type { VictoriaLogsResult } from './services/victoria-logs';
@@ -44,6 +48,8 @@ ${colors.yellow}Usage:${colors.reset}
   npm run stack [options]
 
 ${colors.yellow}Options:${colors.reset}
+  --services-only   Start services only (no n8n containers), write .env for local dev
+  --services <list> Comma-separated services (e.g. postgres,redis,mailpit,proxy,kafka)
   --postgres        Use PostgreSQL instead of SQLite
   --queue           Enable queue mode (requires PostgreSQL)
   --source-control  Enable source control (Git) container for testing
@@ -108,6 +114,11 @@ ${Object.keys(BASE_PERFORMANCE_PLANS)
 	.map((name) => `  npm run stack --plan ${name}`)
 	.join('\n')}
 
+  ${colors.bright}# Services only (local dev — writes .env for pnpm start)${colors.reset}
+  pnpm services --services postgres
+  pnpm services --services postgres,redis
+  pnpm services --services postgres,mailpit,proxy
+
   ${colors.bright}# Parallel instances${colors.reset}
   npm run stack --name test-1
   npm run stack --name test-2
@@ -127,8 +138,10 @@ async function main() {
 		args: process.argv.slice(2),
 		options: {
 			help: { type: 'boolean', short: 'h' },
+			'services-only': { type: 'boolean' },
 			postgres: { type: 'boolean' },
 			queue: { type: 'boolean' },
+			services: { type: 'string' },
 			'source-control': { type: 'boolean' },
 			oidc: { type: 'boolean' },
 			observability: { type: 'boolean' },
@@ -152,8 +165,20 @@ async function main() {
 		process.exit(0);
 	}
 
+	const servicesOnly = values['services-only'] ?? false;
+
 	// Build services array from CLI flags
+	const validServiceNames = new Set(Object.keys(SERVICE_REGISTRY));
 	const services: ServiceName[] = [];
+	if (values.services) {
+		for (const name of values.services.split(',').map((s) => s.trim())) {
+			if (!validServiceNames.has(name)) {
+				log.error(`Unknown service: '${name}'. Available: ${[...validServiceNames].join(', ')}`);
+				process.exit(1);
+			}
+			services.push(name as ServiceName);
+		}
+	}
 	if (values['source-control']) services.push('gitea');
 	if (values.oidc) services.push('keycloak');
 	if (values.observability) services.push('victoriaLogs', 'victoriaMetrics', 'vector');
@@ -167,7 +192,11 @@ async function main() {
 	const config: N8NConfig = {
 		postgres: values.postgres ?? false,
 		services,
-		projectName: values.name ?? `n8n-stack-${Math.random().toString(36).substring(7)}`,
+		projectName:
+			values.name ??
+			(servicesOnly
+				? `n8n-svc-${Math.random().toString(36).substring(7)}`
+				: `n8n-stack-${Math.random().toString(36).substring(7)}`),
 	};
 
 	// Handle queue mode (mains > 1 or workers > 0)
@@ -227,6 +256,94 @@ async function main() {
 		}
 	}
 
+	// Services-only mode: start containers, write .env, no n8n
+	if (servicesOnly) {
+		if (services.length === 0) {
+			log.error('No services specified. Use flags like --postgres, --redis, --mailpit, etc.');
+			process.exit(1);
+		}
+
+		log.header('Starting service containers');
+		log.info(`Project: ${config.projectName}`);
+		log.info(`Services: ${services.join(', ')}`);
+
+		try {
+			const stack = await createServiceStack({
+				services,
+				projectName: config.projectName,
+			});
+
+			// Collect host-compatible env vars from each service
+			const envVars: Record<string, string> = {};
+			for (const name of services) {
+				const result = stack.serviceResults[name];
+				if (!result) continue;
+
+				const service = SERVICE_REGISTRY[name];
+				Object.assign(
+					envVars,
+					service.env?.(result, true) ?? {},
+					service.extraEnv?.(result, true) ?? {},
+				);
+			}
+
+			// Write .env to packages/cli/bin/ because `pnpm start` runs os-normalize.mjs
+			// which does `cd packages/cli/bin` before launching n8n, and dotenv loads from cwd.
+			if (Object.keys(envVars).length > 0) {
+				const repoRoot = resolve(__dirname, '../../..');
+				const envPath = resolve(repoRoot, 'packages/cli/bin/.env');
+				const lines = [
+					'# Generated by pnpm services — do not edit',
+					`# Project: ${stack.projectName}`,
+					'# Stop with: pnpm --filter n8n-containers services:clean',
+					'',
+					...Object.entries(envVars).map(([key, value]) => `${key}=${value}`),
+					'',
+				];
+				writeFileSync(envPath, lines.join('\n'));
+				log.success(`Wrote ${Object.keys(envVars).length} env vars to packages/cli/bin/.env`);
+			}
+
+			// Print summary
+			log.header('Services running');
+			for (const name of services) {
+				const result = stack.serviceResults[name];
+				if (!result) continue;
+
+				const service = SERVICE_REGISTRY[name];
+				const vars = {
+					...(service.env?.(result, true) ?? {}),
+					...(service.extraEnv?.(result, true) ?? {}),
+				};
+				const varSummary = Object.entries(vars)
+					.map(([k, v]) => `${k}=${v}`)
+					.join(', ');
+				log.success(`${name}${varSummary ? `: ${varSummary}` : ''}`);
+			}
+
+			// Print mailpit UI URL if running
+			const mailpitResult = stack.serviceResults.mailpit as MailpitResult | undefined;
+			if (mailpitResult) {
+				console.log('');
+				log.info(`Mailpit UI: ${colors.cyan}${mailpitResult.meta.apiBaseUrl}${colors.reset}`);
+			}
+
+			console.log('');
+			log.info('Containers are running in the background');
+			log.info(`Run ${colors.bright}pnpm dev${colors.reset} in another terminal to start n8n`);
+			log.info(
+				`Cleanup: ${colors.bright}pnpm --filter n8n-containers services:clean${colors.reset}`,
+			);
+			console.log('');
+		} catch (error) {
+			log.error(
+				`Failed to start services: ${error instanceof Error ? error.message : String(error)}`,
+			);
+			process.exit(1);
+		}
+		return;
+	}
+
 	log.header('Starting n8n Stack');
 	log.info(`Project name: ${config.projectName}`);
 	displayConfig(config);

packages/testing/containers/package.json

@@ -18,6 +18,8 @@
     "stack:clean:containers": "docker ps -aq --filter 'name=n8n-stack-*' | xargs -r docker rm -f 2>/dev/null",
     "stack:clean:networks": "docker network ls --filter 'label=org.testcontainers=true' -q | xargs -r docker network rm 2>/dev/null",
     "stack:clean:all": "pnpm run stack:clean:containers && pnpm run stack:clean:networks",
+    "services": "tsx ./n8n-start-stack.ts --services-only",
+    "services:clean": "docker ps -aq --filter 'name=n8n-svc-*' | xargs docker rm -f 2>/dev/null; rm -f ../../../packages/cli/bin/.env",
     "lint": "eslint . --quiet",
     "lint:fix": "eslint . --fix"
   },
@@ -31,6 +33,7 @@
     "@testcontainers/postgresql": "^11.0.3",
     "@testcontainers/redis": "^11.0.3",
     "get-port": "^7.1.0",
+    "mockserver-client": "^5.15.0",
     "kafkajs": "catalog:",
     "testcontainers": "^11.11.0"
   }

packages/testing/containers/services/gitea.ts

@@ -76,9 +76,9 @@ export const gitea: Service<GiteaResult> = {
 		}
 	},
 
-	env(): Record<string, string> {
+	env(result: GiteaResult, external?: boolean): Record<string, string> {
 		return {
-			N8N_SOURCECONTROL_HOST: `http://${HOSTNAME}:${HTTP_PORT}`,
+			N8N_SOURCECONTROL_HOST: external ? result.meta.apiUrl : `http://${HOSTNAME}:${HTTP_PORT}`,
 		};
 	},
 };

packages/testing/containers/services/kafka.ts

@@ -41,8 +41,11 @@ export const kafka: Service<KafkaResult> = {
 		};
 	},
 
-	env(): Record<string, string> {
-		return {};
+	env(result: KafkaResult, external?: boolean): Record<string, string> {
+		if (!external) return {};
+		return {
+			KAFKA_BROKER: result.meta.externalBroker,
+		};
 	},
 };
 

packages/testing/containers/services/keycloak.ts

@@ -306,7 +306,14 @@ export const keycloak: Service<KeycloakResult> = {
 		}
 	},
 
-	env(): Record<string, string> {
+	env(result: KeycloakResult, external?: boolean): Record<string, string> {
+		if (external) {
+			return {
+				N8N_OIDC_DISCOVERY_URL: result.meta.discoveryUrl,
+				N8N_OIDC_CLIENT_ID: result.meta.clientId,
+				N8N_OIDC_CLIENT_SECRET: result.meta.clientSecret,
+			};
+		}
 		return {
 			NODE_EXTRA_CA_CERTS: N8N_KEYCLOAK_CERT_PATH,
 			NO_PROXY: `localhost,127.0.0.1,${HOSTNAME},host.docker.internal`,

packages/testing/containers/services/localstack.ts

@@ -84,11 +84,9 @@ export const localstack: Service<LocalStackResult> = {
 		}
 	},
 
-	env(result: LocalStackResult): Record<string, string> {
+	env(result: LocalStackResult, external?: boolean): Record<string, string> {
 		return {
-			// AWS SDK v3 standard endpoint override
-			AWS_ENDPOINT_URL: result.meta.internalEndpoint,
-			// Dummy credentials (LocalStack doesn't validate by default)
+			AWS_ENDPOINT_URL: external ? result.meta.endpoint : result.meta.internalEndpoint,
 			AWS_ACCESS_KEY_ID: 'test',
 			AWS_SECRET_ACCESS_KEY: 'test',
 			AWS_DEFAULT_REGION: DEFAULT_REGION,

packages/testing/containers/services/mailpit.ts

@@ -114,11 +114,13 @@ export const mailpit: Service<MailpitResult> = {
 		}
 	},
 
-	env(): Record<string, string> {
+	env(result: MailpitResult, external?: boolean): Record<string, string> {
 		return {
 			N8N_EMAIL_MODE: 'smtp',
-			N8N_SMTP_HOST: HOSTNAME,
-			N8N_SMTP_PORT: String(SMTP_PORT),
+			N8N_SMTP_HOST: external ? result.container.getHost() : HOSTNAME,
+			N8N_SMTP_PORT: external
+				? String(result.container.getMappedPort(SMTP_PORT))
+				: String(SMTP_PORT),
 			N8N_SMTP_SSL: 'false',
 			N8N_SMTP_SENDER: 'test@n8n.local',
 		};
@@ -128,8 +130,16 @@ export const mailpit: Service<MailpitResult> = {
 export class MailpitHelper {
 	private readonly apiBaseUrl: string;
 
-	constructor(apiBaseUrl: string) {
+	/** SMTP host that n8n should use to send email (internal hostname in container mode, localhost in local mode) */
+	readonly smtpHost: string;
+
+	/** SMTP port that n8n should use to send email (1025 in container mode, mapped port in local mode) */
+	readonly smtpPort: number;
+
+	constructor(apiBaseUrl: string, smtpHost = HOSTNAME, smtpPort = SMTP_PORT) {
 		this.apiBaseUrl = apiBaseUrl;
+		this.smtpHost = smtpHost;
+		this.smtpPort = smtpPort;
 	}
 
 	async clear(): Promise<void> {

packages/testing/containers/services/mysql.ts

@@ -54,7 +54,15 @@ export const mysqlService: Service<MySqlResult> = {
 		};
 	},
 
-	env(): Record<string, string> {
-		return {};
+	env(result: MySqlResult, external?: boolean): Record<string, string> {
+		if (!external) return {};
+		return {
+			DB_TYPE: 'mysqldb',
+			DB_MYSQLDB_HOST: result.meta.externalHost,
+			DB_MYSQLDB_PORT: String(result.meta.externalPort),
+			DB_MYSQLDB_DATABASE: result.meta.database,
+			DB_MYSQLDB_USER: result.meta.username,
+			DB_MYSQLDB_PASSWORD: result.meta.password,
+		};
 	},
 };

packages/testing/containers/services/postgres.ts

@@ -45,11 +45,11 @@ export const postgres: Service<PostgresResult> = {
 		};
 	},
 
-	env(result: PostgresResult): Record<string, string> {
+	env(result: PostgresResult, external?: boolean): Record<string, string> {
 		return {
 			DB_TYPE: 'postgresdb',
-			DB_POSTGRESDB_HOST: HOSTNAME,
-			DB_POSTGRESDB_PORT: '5432',
+			DB_POSTGRESDB_HOST: external ? result.container.getHost() : HOSTNAME,
+			DB_POSTGRESDB_PORT: external ? String(result.container.getMappedPort(5432)) : '5432',
 			DB_POSTGRESDB_DATABASE: result.meta.database,
 			DB_POSTGRESDB_USER: result.meta.username,
 			DB_POSTGRESDB_PASSWORD: result.meta.password,