ddev-playwright

A DDEV add-on that provides Playwright end-to-end testing in an isolated Docker container. Uses the official Microsoft Playwright Docker image with all browsers and system dependencies pre-installed, and Playwright’s native UI mode for interactive debugging — no VNC required.

• Installation
• Prerequisites
• Usage
• Accessing Your Web Application from Tests
• Configuration
• Troubleshooting

Installation

ddev add-on get ochorocho/ddev-playwright
ddev restart

After installation, the .ddev directory should be committed to version control.

Prerequisites

Your project must have @playwright/test installed as an npm dependency:

npm install -D @playwright/test

The version of @playwright/test in your package.json must match the Docker image version. The default Docker image is mcr.microsoft.com/playwright:v1.50.0-noble, which matches @playwright/[email protected].

If you use a different version, update the Docker image accordingly (see Configuration).

Usage

Any npx playwright command and option can be passed through:

ddev playwright test --trace on --timeout 60000
ddev playwright test --shard 1/4
ddev playwright test --last-failed

Playwright UI Mode

The ddev playwright browser command starts Playwright’s native UI mode, which provides:

• Time-travel debugging with DOM snapshots
• Watch mode for automatic re-runs on file changes
• Test filtering by name, project, tags, or status
• Built-in trace viewer with network and console logs
• Locator picker for identifying elements

The UI is accessible at https://<DDEV_SITENAME>.ddev.site:8078 (shown in ddev describe).

HTML Test Reports

After running tests with --reporter=html, view the report with:

ddev playwright show-report

The report is accessible at https://<DDEV_SITENAME>.ddev.site:9324 (shown in ddev describe).

Accessing Your Web Application from Tests

Inside the Playwright container, your DDEV web application is reachable at http://web. Configure this in your playwright.config.ts:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  use: {
    baseURL: 'http://web',
  },
  projects: [
    {
      name: 'chromium',
      use: { browserName: 'chromium' },
    },
    {
      name: 'firefox',
      use: { browserName: 'firefox' },
    },
    {
      name: 'webkit',
      use: { browserName: 'webkit' },
    },
  ],
});

Configuration

Test Directory

If your Playwright installation is not in the project root (e.g., in test/Playwright/), configure the test directory:

ddev dotenv set .ddev/.env.playwright --playwright-test-dir="test/Playwright"
ddev restart

This sets the working directory for all ddev playwright commands. The path is relative to your project root. Default: . (project root).

Multiple Playwright Installations

If you have multiple Playwright installations in different directories, use the --dir flag to target a specific one per command without changing the persistent configuration:

ddev playwright --dir=test/Playwright test
ddev playwright --dir=test/E2E test --project=chromium
ddev playwright --dir=test/Playwright browser

The --dir flag takes priority over the PLAYWRIGHT_TEST_DIR setting in .env.playwright.

Docker Image Version

The default image is mcr.microsoft.com/playwright:v1.50.0-noble. To use a different version:

ddev dotenv set .ddev/.env.playwright --playwright-docker-image="mcr.microsoft.com/playwright:v1.50.0-noble"
ddev restart

The image version must match your installed @playwright/test version. Check the available tags at the Microsoft Artifact Registry.

Service Ports

These ports appear automatically in ddev describe.

Shell Access

Access the Playwright container shell for debugging:

ddev ssh -s playwright

View container logs:

ddev logs -s playwright

Troubleshooting

Version Mismatch Error

If you see an error like browserType.launch: Executable doesn't exist, the Docker image version doesn’t match your @playwright/test version.

1. Check your installed version: ddev playwright --version
2. Update the Docker image to match:

   ddev dotenv set .ddev/.env.playwright --playwright-docker-image="mcr.microsoft.com/playwright:v<YOUR_VERSION>-noble"
   ddev restart
   

Firefox Hangs in Docker

Firefox can occasionally hang inside Docker containers. This is a known Playwright issue. Workarounds:

• Use Chromium or WebKit as your primary browser for Docker-based testing
• Add a timeout to your Firefox project configuration

File Permissions

If test artifacts (screenshots, reports) have incorrect permissions, you can fix them with:

ddev exec -s playwright chown -R $(id -u):$(id -g) /var/www/html/test-results /var/www/html/playwright-report 2>/dev/null || true