Playwright Docker Integration with Java (Run Tests Inside Containers)

One of the biggest challenges in automation testing is ensuring that tests run consistently across different environments. A test that works on a developer's machine may fail on a CI server due to differences in browser versions, operating systems, or installed dependencies.

Docker solves this problem by packaging your Playwright framework and all its dependencies into a portable container. Whether you run the container on your laptop, a Jenkins server, or a cloud platform, the environment remains the same.

In this tutorial, you'll learn how to containerize a Playwright Java framework using Docker and execute your tests inside a container.

---

What is Docker?

Docker is a containerization platform that allows applications to run in isolated environments called containers.

A container includes:

• Application code
• Java Runtime
• Browser binaries
• System libraries
• Maven dependencies

This ensures that your automation framework behaves consistently across environments.

---

Why Run Playwright Inside Docker?

Running Playwright in Docker provides several advantages:

• Consistent execution across environments
• Easy setup for new team members
• Simplified CI/CD integration
• Isolated browser environments
• Reduced "works on my machine" issues
• Easy scaling for parallel execution

---

Prerequisites

Before you begin, ensure you have:

• Java 17 or later
• Maven installed
• Docker Desktop (Windows/macOS) or Docker Engine (Linux)
• A Playwright Java project
• Browser binaries installed locally for development

---

Project Structure

Example project layout:

playwright-framework
│
├── src
├── pom.xml
├── Dockerfile
├── testng.xml
├── screenshots
├── videos
└── allure-results

---

Step 1: Create a Dockerfile

Create a file named Dockerfile in the project root.

FROM maven:3.9.9-eclipse-temurin-17

WORKDIR /app

COPY . .

RUN mvn dependency:resolve

RUN mvn exec:java \
    -Dexec.mainClass=com.microsoft.playwright.CLI \
    -Dexec.args="install --with-deps"

CMD ["mvn", "test"]

This Dockerfile:

• Uses Maven with Java 17
• Copies the project into the container
• Downloads project dependencies
• Installs Playwright browser binaries and required system libraries
• Executes the test suite

---

Step 2: Build the Docker Image

Run the following command from the project root:

docker build -t playwright-java-framework .

Explanation:

• build creates an image.
• -t assigns a friendly name.
• . indicates the current directory as the build context.

---

Step 3: Verify the Image

List available Docker images:

docker images

Example output:

REPOSITORY                  TAG       IMAGE ID
playwright-java-framework   latest    abc123xyz

---

Step 4: Run the Container

Execute your tests:

docker run --rm playwright-java-framework

The --rm option automatically removes the container after execution.

---

Passing Environment Variables

Most automation frameworks use environment variables for configuration.

Example:

docker run --rm \
-e ENV=QA \
-e BROWSER=chromium \
playwright-java-framework

Your Java code can access these values using System.getenv().

---

Mounting Volumes

To preserve reports, screenshots, or videos outside the container, mount a local folder.

Example:

docker run --rm \
-v ${PWD}/reports:/app/allure-results \
playwright-java-framework

This copies the generated Allure results to your local machine.

---

Running Specific TestNG Suites

Execute a specific suite:

docker run --rm \
playwright-java-framework \
mvn test -DsuiteXmlFile=testng.xml

This is useful when you want to run smoke or regression suites independently.

---

Integrating with Jenkins

Once the image is built, Jenkins can execute it as part of your pipeline.

Example pipeline stage:

stage('Run Docker Tests') {

    steps {

        sh 'docker build -t playwright-java-framework .'

        sh 'docker run --rm playwright-java-framework'
    }
}

Note: On Windows Jenkins agents, use bat instead of sh.

---

Running Multiple Containers

For parallel execution, start multiple containers.

Example:

docker run --rm playwright-java-framework

docker run --rm playwright-java-framework

docker run --rm playwright-java-framework

Each container executes in an isolated environment.

---

Best Practices

Keep Images Small

Use lightweight base images where possible and avoid installing unnecessary packages.

---

Use Headless Browsers

Containers typically run without a graphical interface.

Launch browsers in headless mode:

new BrowserType.LaunchOptions()
        .setHeadless(true);

---

Avoid Hardcoded Paths

Use relative paths or environment variables to improve portability.

---

Store Configuration Outside the Image

Keep URLs, credentials, and environment settings outside the Docker image.

Use:

• Environment variables
• Properties files
• Secrets management

---

Clean Up Containers

Use:

docker run --rm

to automatically remove completed containers and avoid clutter.

---

Common Challenges

Browser Not Found

If browsers are missing, ensure Playwright installation is included during image creation:

playwright install --with-deps

---

Permission Issues

Verify that the container user has permission to read project files and write reports.

---

Slow Builds

To speed up builds:

• Cache Maven dependencies.
• Reuse Docker layers.
• Avoid unnecessary image rebuilds.

---

Common Interview Questions

Why use Docker for Playwright automation?

Docker provides a consistent execution environment, making tests portable and reliable across development, testing, and CI/CD systems.

---

What is the purpose of a Dockerfile?

A Dockerfile defines how a Docker image is built, including the base image, dependencies, application files, and startup command.

---

Can Docker containers run Playwright browsers?

Yes. Containers can include Chromium, Firefox, and WebKit along with the required operating system libraries.

---

Why is headless execution recommended inside Docker?

Most containers do not have a graphical user interface. Running browsers in headless mode improves compatibility and performance.

---

How can Docker help with parallel execution?

Multiple containers can run simultaneously, allowing test suites to execute in parallel across isolated environments.

---

Conclusion

Docker has become an essential part of modern automation testing and DevOps workflows.

By containerizing your Playwright framework, you ensure that tests run consistently regardless of the underlying operating system or infrastructure.

In this guide, you learned how to:

• Create a Dockerfile for a Playwright Java project
• Build and run Docker images
• Pass environment variables
• Mount report directories
• Integrate Docker with Jenkins
• Apply enterprise best practices

With Docker in place, your Playwright framework becomes portable, reproducible, and ready for cloud-native CI/CD pipelines.