chore: Improve test container dx (#16988)

packages/testing/containers/n8n-image-pull-policy.ts

@@ -0,0 +1,18 @@
+import { ImagePullPolicy, PullPolicy } from 'testcontainers';
+
+/**
+ * Custom pull policy for n8n images:
+ * - Never try to pull the local image
+ * - Otherwise, use the default pull policy (pull only if not present)
+ */
+export class N8nImagePullPolicy implements ImagePullPolicy {
+	constructor(private readonly image: string) {}
+
+	public shouldPull(): boolean {
+		if (this.image === 'n8nio/n8n:local') {
+			return false;
+		}
+
+		return PullPolicy.defaultPolicy().shouldPull();
+	}
+}

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

@@ -42,6 +42,9 @@ ${colors.yellow}Options:${colors.reset}
   --env KEY=VALUE   Set environment variables
   --help, -h        Show this help
 
+${colors.yellow}Environment Variables:${colors.reset}
+  • N8N_DOCKER_IMAGE=<image>  Use a custom Docker image (default: n8nio/n8n:local)
+
 ${colors.yellow}Examples:${colors.reset}
   ${colors.bright}# Simple SQLite instance${colors.reset}
   npm run stack

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

@@ -20,6 +20,7 @@ import {
 	setupRedis,
 } from './n8n-test-container-dependencies';
 import { DockerImageNotFoundError } from './docker-image-not-found-error';
+import { N8nImagePullPolicy } from './n8n-image-pull-policy';
 
 // --- Constants ---
 
@@ -313,6 +314,7 @@ async function createN8NContainer({
 			'com.docker.compose.service': isWorker ? 'n8n-worker' : 'n8n-main',
 			instance: instanceNumber.toString(),
 		})
+		.withPullPolicy(new N8nImagePullPolicy(N8N_IMAGE))
 		.withName(name)
 		.withReuse();