Introduction: What Does a Playwright Docker Container Test Failure Mean?
A playwright docker container test failure happens when a Playwright test works on a developer’s machine but fails after running inside a Docker container.
For example, this may work locally:
npx playwright test
but fail inside Docker with errors such as:
Executable doesn’t exist
BrowserType.launch: Failed to launch
Permission denied
net::ERR_CONNECTION_REFUSED
Docker creates an isolated environment. That environment may have different:
- Operating system libraries
- Browser binaries
- Fonts
- File permissions
- Environment variables
- Network configuration
- Application URLs
- Node.js versions
- Playwright versions
Therefore, a Docker failure does not necessarily mean the test or application is broken.
The goal of Playwright Docker debugging is to identify whether the problem is caused by the browser, container, application, network, permissions, or test itself.
Why Playwright Tests Behave Differently Inside Docker
Your local machine may already contain:
Node.js
Playwright
Chromium
Linux libraries
Fonts
Environment variables
Certificates
Network access
A minimal Docker image may contain none of these browser dependencies.
This is why a common Playwright Docker test failure looks like:
Works locally
↓
Build Docker image
↓
↓
Browser launch failure
The container needs a compatible Playwright runtime and browser dependencies.
Common Playwright Docker Container Test Failures
| Failure | Common Cause |
| Browser executable missing | Browsers not installed |
| Browser launch failure | Missing OS dependencies |
| Permission denied | Incorrect user/file permissions |
| ERR_CONNECTION_REFUSED | Wrong application URL |
| Timeout | Container cannot reach application |
| Missing screenshots | Incorrect artifact path |
| Environment variable undefined | Variables not passed to container |
| CI failure | Different Docker/runtime environment |
| Sandbox error | Browser/container security configuration |
| Version mismatch | Node, Playwright, or browser versions differ |
The first step in any playwright docker container test failure is to classify the error.
Browser Installation and Missing Dependency Errors
One of the most common beginner problems is:
Executable doesn’t exist at …
This usually means the browser was not installed in the container.
A reliable option is to use the official Playwright Docker image appropriate for your Playwright version.
Example Dockerfile
FROM mcr.microsoft.com/playwright:v1.55.0-noble
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD [“npx”, “playwright”, “test”]
The Playwright image includes browsers and browser system dependencies.
Important: Keep the image version aligned with the Playwright version used by your project.
If your project uses a materially different Playwright version from the image, unexpected browser/runtime behavior can occur.
Installing Browsers Manually
If you use a Node base image instead:
FROM node:22-bookworm
WORKDIR /app
COPY package*.json ./
RUN npm ci
RUN npx playwright install –with-deps chromium
COPY . .
CMD [“npx”, “playwright”, “test”]
The –with-deps option installs the browser and required system dependencies for supported environments.
Problem → Root Cause → Diagnostic Step → Fix → Verification → Best Practice
Problem: Chromium cannot launch.
Root Cause: Browser or OS dependencies are missing.
Diagnostic Step:
npx playwright install –list
Fix: Install the required browser and dependencies.
Verification:
npx playwright test
Best Practice: Prefer a compatible official Playwright image for predictable CI execution.
Playwright Docker Image and Version Mismatch
A particularly confusing Playwright Docker container test failure occurs when:
package.json → Playwright version A
Docker image → Playwright version B
The browser binary and Playwright package should be kept compatible.
Check the project:
npm list @playwright/test
Check the image/version strategy used by your Dockerfile.
Best Practice
Pin your Playwright dependency and use a corresponding Playwright container image rather than relying on unrelated latest tags.
Headless Browser and Sandbox Problems
Playwright tests commonly run headlessly inside Docker:
import { test, expect } from ‘@playwright/test’;
test(‘homepage’, async ({ page }) => {
await page.goto(‘https://example.com’);
await expect(
page.getByRole(‘heading’, {
name: ‘Example Domain’
})
).toBeVisible();
});
If the browser fails before the test starts, investigate:
- Container user
- Browser dependencies
- Image compatibility
- Sandbox/security restrictions
- Shared memory
- Browser launch arguments
Do not blindly add browser flags just to suppress an error. Understand the security implications and why the container requires the setting.
Permissions and Filesystem Errors
Docker runs processes under a specific user.
You may see:
EACCES: permission denied
when Playwright tries to write:
test-results/
playwright-report/
screenshots/
videos/
Check the directory:
ls -la
Create required directories if necessary:
RUN mkdir -p /app/test-results /app/playwright-report
Then ensure the test process can write to them.
A common best practice is to run the container with a non-root user while ensuring that the application and artifact directories have appropriate ownership and permissions.
Environment Variables and Configuration Issues
A test may use:
const baseURL = process.env.BASE_URL;
Locally:
BASE_URL=http://localhost:3000
Inside Docker, however, localhost means the current container, not your host machine or another application container.
Configure:
environment:
BASE_URL: http://web:3000
when the application is another Compose service named web.
import { defineConfig } from ‘@playwright/test’;
export default defineConfig({
use: {
baseURL: process.env.BASE_URL
}
});
Network and Application URL Problems
This is one of the most common reasons for:
net::ERR_CONNECTION_REFUSED
Suppose your application runs on your host:
http://localhost:3000
Inside a Docker container, this is usually not the same host context.
If the application is another container, use its service name.
Example Docker Compose
services:
web:
image: my-test-app
ports:
– “3000:3000”
tests:
build: .
environment:
BASE_URL: http://web:3000
depends_on:
– web
Then your Playwright test can use:
import { test, expect } from ‘@playwright/test’;
test(‘application loads’, async ({ page }) => {
await page.goto(‘/’);
await expect(
page.getByRole(‘heading’, {
name: ‘Dashboard’
})
).toBeVisible();
});
Important
depends_on controls container startup ordering, but it does not guarantee that the application is ready to accept requests.
For reliable CI, add a proper health/readiness check.
Screenshots, Videos, Traces, and Test Artifacts
When a Docker test fails, preserve evidence.
import { defineConfig } from ‘@playwright/test’;
export default defineConfig({
use: {
screenshot: ‘only-on-failure’,
video: ‘retain-on-failure’,
trace: ‘retain-on-failure’
}
});
Use a predictable result directory:
export default defineConfig({
outputDir: ‘test-results’
});
Then mount artifacts from Docker:
docker run \
-v “$(pwd)/test-results:/app/test-results” \
playwright-tests
You can also mount the HTML report:
docker run \
-v “$(pwd)/playwright-report:/app/playwright-report” \
playwright-tests
These artifacts are extremely useful when debugging a failure that cannot be reproduced locally.
Debugging Playwright Docker Failures Locally
Start by building without cache:
docker build –no-cache -t playwright-tests .
Run:
docker run –rm playwright-tests
If the test fails, open a shell:
docker run –rm -it playwright-tests bash
Then check:
node –version
npx playwright –version
npx playwright install –list
Test network connectivity:
curl http://web:3000
Inspect environment variables:
env | sort
Check permissions:
ls -la
This turns a vague Playwright Container Error into a specific infrastructure problem.
Debugging Playwright Docker Failures in CI/CD
A typical GitHub Actions workflow can build and run the container:
name: Playwright Docker Tests
on:
push:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
– name: Checkout
uses: actions/checkout@v4
– name: Build Docker image
run: docker build -t playwright-tests .
– name: Run Playwright tests
run: docker run –rm playwright-tests
For artifacts:
– name: Upload Playwright results
if: always()
uses: actions/upload-artifact@v4
with:
name: playwright-results
path: |
test-results
playwright-report
If the tests fail only in CI, compare:
- Docker image
- Playwright version
- Node.js version
- Environment variables
- Network access
- CPU and memory
- Application readiness
- Browser dependencies
Real-World Playwright Docker Troubleshooting Examples
Example 1: Browser Not Installed
Problem: Browser executable missing.
Root Cause: node image does not contain Playwright browsers.
Diagnostic:
npx playwright install –list
Fix:
RUN npx playwright install –with-deps chromium
Verification:
npx playwright test
Best Practice: Use a compatible Playwright Docker image or explicitly install browsers.
Example 2: Localhost Connection Failure
Problem:
ERR_CONNECTION_REFUSED
Root Cause: Test container tries to reach localhost, which points to itself.
Diagnostic:
curl http://web:3000
Fix:
environment:
BASE_URL: http://web:3000
Verification: Confirm the application responds from inside the test container.
Best Practice: Use Docker service names for container-to-container communication.
Example 3: Permission Error
Problem:
EACCES: permission denied
Root Cause: Test process cannot write the results directory.
Fix: Correct directory ownership/permissions and ensure mounted host directories are writable.
Verification:
ls -ld test-results
Best Practice: Design artifact directories intentionally instead of running everything as root.
Common Mistakes and Solutions
| Mistake | Better Solution |
| Using a random Node image | Use a compatible Playwright image |
| Forgetting browser installation | Install browsers with dependencies |
| Using localhost incorrectly | Use Docker service names |
| Using latest everywhere | Pin versions |
| Ignoring application readiness | Add health/readiness checks |
| Running as root by default | Use appropriate user permissions |
| Losing CI artifacts | Upload reports/traces |
| Debugging only outside Docker | Reproduce inside the same image |
| Ignoring environment variables | Explicitly pass required values |
| Using unlimited parallel workers | Match workers to container resources |
Playwright Docker Testing Best Practices
Use this checklist for stable Playwright Container Testing:
- Pin Playwright and Docker image versions.
- Use compatible browsers and system dependencies.
- Keep Node.js versions consistent.
- Avoid assuming localhost means the host machine.
- Use Docker service names for internal networking.
- Add application health checks.
- Pass environment variables explicitly.
- Make artifact directories writable.
- Capture screenshots on failure.
- Retain videos and traces when useful.
- Upload HTML reports in CI.
- Reproduce CI failures inside the same container.
- Keep parallel workers appropriate for available resources.
- Avoid unnecessary browser launch flags.
- Keep test data isolated.
- Use deterministic authentication and application state.
Playwright Docker Interview Questions With Answers
Why do Playwright tests fail in Docker but pass locally?
The environments may differ in browser binaries, OS dependencies, fonts, permissions, network configuration, environment variables, or application URLs.
How do you install Playwright browsers in Docker?
Use a compatible Playwright image or install the required browser and dependencies with:
npx playwright install –with-deps chromium
Why does Playwright Docker show ERR_CONNECTION_REFUSED?
The test container may be trying to access an application through the wrong hostname, commonly localhost.
What is the advantage of the Playwright Docker image?
It provides a controlled environment containing compatible browser dependencies, reducing environment-related test differences.
How do you debug Playwright Docker failures?
Inspect the container interactively, check versions, browser installation, environment variables, network connectivity, permissions, screenshots, traces, and reports.
Why should Playwright Docker versions be pinned?
Uncontrolled image or dependency changes can introduce browser/runtime differences and make failures difficult to reproduce.
FAQs
Why do Playwright tests fail in Docker?
They can fail because Docker has different browser dependencies, networking, permissions, environment variables, fonts, or runtime versions.
How do I fix Playwright Docker test failure?
Identify whether the failure involves the browser, dependencies, permissions, network, configuration, application readiness, or test artifacts. Then reproduce the failure inside the same container.
Why is the Playwright browser not installed in Docker?
A generic Node image does not automatically contain Playwright browser binaries. Install them explicitly or use a compatible Playwright Docker image.
Why does Playwright Docker show a permission error?
The container user may not have permission to write screenshots, traces, videos, reports, or other files.
Why does localhost fail in Playwright Docker?
Inside a container, localhost normally refers to that container itself. If the application runs in another container, use its Docker service name.
How do I debug Playwright Docker CI failure?
Capture traces, screenshots, videos, and HTML reports; inspect container logs; verify environment variables and network connectivity; and reproduce the CI image locally.