[Feature]: Support to run browsers in Testcontainer with JUnit Extension

[c3mig]

🚀 Feature Request

Hey! I've created a JUnit extension which wraps the official Playwright JUnit extension to allow to run the browsers within a local docker testcontainer without any downloads. I wanted to ask if this feature could be a general need and integrate it into the official extension.

Here's a preview (it is not public yet):

Playwright Testcontainers Extension for JUnit 6

A JUnit 6 extension that runs Playwright browsers in Docker containers using Testcontainers for
consistent and reproducible test execution. This extension wraps the
official Playwright JUnit integration and manages Docker containers automatically.

Overview

This extension builds upon the official Playwright JUnit integration (
see Playwright Java Docs) and adds automatic Docker container management via
Testcontainers. All core Playwright functionality — browser automation, page injection, tracing, etc. comes from the official
Playwright library.

How it works:

1. Testcontainers Integration: Uses Testcontainers to automatically start and manage Playwright
   Docker containers
2. Container Lifecycle: The extension starts a Playwright server container before tests run and stops it after completion
3. Port Mapping: Testcontainers handles port mapping between container and host automatically
4. Host Access: Container can reach services on the host
5. Container Reuse: A single shared container is reused across all test classes for better performance
6. Thread Safety: Uses ThreadLocal storage for parallel test execution support

By default, browsers run inside Docker containers managed by Testcontainers for consistent CI/CD execution. For local development, you can switch to LOCAL mode to use locally installed browsers.

Features

• Testcontainers Integration: Automatic Docker container management using Testcontainers
• Container-Based Execution: Run browsers in isolated Docker containers for consistent CI/CD execution
• Official Playwright Integration: Full access to Playwright JUnit features
• Container Reuse: Single shared Testcontainer for all tests to improve performance
• Host Access: Containers can reach services on the host - access the hostname via
  PlaywrightTestContainerExtension.getBrowserHost() or Spring's @Value("${playwright.browser.host}")
• Version Matching: Automatically uses Playwright version from Maven/Gradle dependency
• Annotation Inheritance: Support for test base classes with configurable overrides
• Thread-Safe: Supports parallel test execution
• Local Development Mode: Switch to local browsers with mode = Mode.LOCAL for faster development

Example

import com.microsoft.playwright.Page;
import com.microsoft.playwright.junit.Options;
import com.microsoft.playwright.junit.OptionsFactory;

import dev.mam.p3.playwright.junit.UsePlaywrightTestContainer;
import org.junit.jupiter.api.Test;

@UsePlaywrightTestContainer(options = ChromiumOptions.class)
class BasicTest {

    public static class ChromiumOptions implements OptionsFactory {
        @Override
        public Options getOptions() {
            return new Options();  // Uses Chromium by default
        }
    }

    @Test
    void shouldRunInContainer(Page page) {
        page.navigate("http://example.com");
        // Test logic...
    }
}

@UsePlaywrightTestContainer(
        mode = Mode.LOCAL,
        headless = Headless.FALSE  // Show browser UI for debugging
)
class LocalDevelopmentTest {

    @Test
    void shouldRunLocally(Page page) {
        page.navigate("http://example.com");
        // You can see the browser in action!
    }
}

@UsePlaywrightTestContainer(
        image = "your.registry.example.com/playwright-test-runner:{version}"
)
class CustomImageTest {
    @Test
    void shouldUseCustomImage(Page page) {
        // Runs in your custom image
    }
}

Motivation

• Run browsers in isolated Docker containers for consistent CI/CD execution
• Reuse an existing docker image on CI which may be cached on the current runner
• Use internal docker registry
• Prevent downloading browsers on every run from an external network