KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #open-source #ai #claude-code #codex #developer-tools #dsh-plugin #ai-agent #mcp #deepseek-harness

ddev-playwright

★ 18 Open GitHub ↗

Playwright add-on for ddev

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![add-on registry](https://img.shields.io/badge/DDEV-Add--on_Registry-blue)](https://addons.ddev.com)
[![tests](https://github.com/julienloizelet/ddev-playwright/actions/workflows/tests.yml/badge.svg)](https://github.com/julienloizelet/ddev-playwright/actions/workflows/tests.yml)
[![last commit](https://img.shields.io/github/last-commit/julienloizelet/ddev-playwright)](https://github.com/julienloizelet/ddev-playwright/commits)
[![Version](https://img.shields.io/github/v/release/julienloizelet/ddev-playwright)](https://github.com/julienloizelet/ddev-playwright/releases)

# ddev-playwright

**Table of Contents**

- [Introduction](#introduction)
- [Installation](#installation)
- [Basic usage](#basic-usage)
  - [Quick start](#quick-start)
  - [Customization](#customization)
    - [Playwright testing directory](#playwright-testing-directory)
    - [Docker image and KASMVNC version](#docker-image-and-kasmvnc-version)
    - [`.env` file](#env-file)
  - [Add-on commands](#add-on-commands)
    - [Install Playwright from a `package.json` file](#install-playwright-from-a-packagejson-file)
    - [Init a Playwright project from scratch](#init-a-playwright-project-from-scratch)
    - [Run a Playwright command](#run-a-playwright-command)
  - [VNC server](#vnc-server)
  - [Other commands](#other-commands)
- [Technical notes](#technical-notes)
  - [`.npmrc` file and `.ddev/homeadditions`](#npmrc-file-and-ddevhomeadditions)
- [Thanks](#thanks)
- [Contribute](#contribute)

## Introduction

[Playwright](https://playwright.dev) was created to accommodate the needs of end-to-end testing.

This DDEV add-on allows you to use Playwright in a separate `playwright` service.

## Installation

Run:

```bash
ddev add-on get julienloizelet/ddev-playwright
```

Then restart your project

```bash
ddev restart
```

## Basic usage

### Quick start

- Create a `tests/Playwright` folder in your project root directory (Only required for this "quick start").
- `ddev playwright-init --pm npm`
- `ddev playwright test`

### Customization

#### Playwright testing directory

Each command of this add-on runs inside the `PLAYWRIGHT_TEST_DIR` directory of the Playwright container.

By default, `tests/Playwright` is used as `PLAYWRIGHT_TEST_DIR` value, but you can override this value to suit your
need by creating a `docker-compose.override.yaml` (or any `docker-compose.<some-good-name>.yaml` file) in
the `.ddev` root directory with the following content:

```yaml
services:
  playwright:
    environment:
      - PLAYWRIGHT_TEST_DIR=your/playwright/directory/path
```

If you want to use the root directory of your project, you can use the following value:

```yaml
services:
  playwright:
    environment:
      - PLAYWRIGHT_TEST_DIR=./
```

You could also edit the value directly in the `docker-compose.playwright.yaml` file, but you risk losing your changes every time you do a `ddev add-on get julienloizelet/ddev-playwright` (unless you delete the `#ddev-generated` line at the beginning of the file).

#### Docker image and KASMVNC version

To change the Docker image, you can set the `PLAYWRIGHT_DOCKER_IMAGE` variable in the `.ddev/.env.playwright` file.
To change the KasmVNC version, you can set the `KASMVNC_VERSION` variable in the `.ddev/.env.playwright` file.

For example, to use the `mcr.microsoft.com/playwright:v1.46.0-focal-amd64` image, run the following command:

```bash
ddev dotenv set .ddev/.env.playwright --playwright-docker-image=mcr.microsoft.com/playwright:v1.46.0-focal-amd64
ddev add-on get julienloizelet/ddev-playwright
ddev restart
```

Make sure to commit the `.ddev/.env.playwright` file to version control.

All customization options (use with caution):

| Variable                  | Flag                        | Default |
|---------------------------|-----------------------------| ------- |
| `PLAYWRIGHT_DOCKER_IMAGE` | `--playwright-docker-image` | `mcr.microsoft.com/playwright:focal` |
| `KASMVNC_VERSION` | `--kasmvnc-version` | `1.4.0` |

#### `.env` file

If there is a `.env.example` file in the `PLAYWRIGHT_TEST_DIR` folder, it will be copied (while running `ddev
playwright-install` or `ddev playwright-init` ) into a `.env` file (to be used with the `dotenv` package for example).

### Add-on commands

#### Install Playwright from a `package.json` file

- `ddev playwright-install --pm [npm|yarn]`

This command will install `playwright` and all dependencies in a folder defined by the environment variable `PLAYWRIGHT_TEST_DIR` of the `docker-compose.playwright.yaml` file.

You can choose to use `npm` or `yarn` as package manager by using the `--pm` option. By default, `yarn` is used.

**Before running this command**, ensure that you have a `package.json` file in the `PLAYWRIGHT_TEST_DIR` folder.

You will find an example of such a file in the `tests/project_root/tests/Playwright`folder of this repository.

<summary>Example of package.json file</summary>

```json
{
  "license": "MIT",
  "dependencies": {
    "@playwright/test": "^1.34.2",
    "dotenv": "^16.0.3"
  }
}
```

</details>

You will also find an example of a `playwright.config.js` file.

<details>
<summary>Example of playwright.config.js file</summary>

```javascript
// @ts-check
const { defineConfig, devices } = require("@playwright/test");

require("dotenv").config({ path: ".env" });

/**
 * @see https://playwright.dev/docs/test-configuration
 */
module.exports = defineConfig({
  testDir: "./tests",
  /* Run tests in files in parallel */
  fullyParallel: true,
  /* Fail the build on CI if you accidentally left test.only in the source code. */
  forbidOnly: !!process.env.CI,
  /* Retry on CI only */
  retries: process.env.CI ? 2 : 0,
  /* Opt out of parallel tests on CI. */
  workers: process.env.CI ? 1 : undefined,
  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
  reporter: [[process.env.CI ? "github" : "list"], ["html", { open: "never" }]],
  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
  use: {
    /* Base URL to use in actions like `await page.goto('/')`. */
    baseURL: process.env.BASEURL,
    ignoreHTTPSErrors: true,
    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
    trace: "on-first-retry",
  },

/* Configure projects for major browsers */
  projects: [
    {
      name: "chromium",
      use: { ...devices["Desktop Chrome"] },
    },

{
      name: "firefox",
      use: { ...devices["Desktop Firefox"] },
    },

{
      name: "webkit",
      use: { ...devices["Desktop Safari"] },
    },
  ],
});
```

</details>

#### Init a Playwright project from scratch

- `ddev playwright-init --pm [npm|yarn]`

This command will initialize a Playwright project in the `PLAYWRIGHT_TEST_DIR` as described in the [Playwright documentation](https://playwright.dev/docs/intro#installing-playwright).

You can choose to use `npm` or `yarn` as package manager by using the `--pm` option. By default, `yarn` is used.

**NB:** Please note that this command is interactive and [should not be used in CI context](https://github.com/microsoft/playwright/issues/11843).

#### Run a Playwright command

- `ddev playwright`

You can run all the playwright command with `ddev playwright [command]`.

- To run playwright's test command:

```bash
  ddev playwright test
  ```

- To run with the Playwright UI tool.

```bash
  ddev playwright test --ui
  ```

- To run in headed mode.

```bash
  ddev playwright test --headed
  ```

- To generate playwright report

```bash
  ddev playwright show-report --host 0.0.0.0
  ```

and then browse to `https://<PROJECT>.ddev.site:9323`

![show report](https://raw.githubusercontent.com/julienloizelet/ddev-playwright/main/docs/show-report.jpg)

### VNC server

When running in UI/headed mode, you can use the provided Kasmvnc service by browsing to `https://<PROJECT>.ddev.site:8444`

![kasmvnc](https://raw.githubusercontent.com/julienloizelet/ddev-playwright/main/docs/kasmvnc.jpg)

It could be also used to generate playwright code by browsing with the following command:

```bash
ddev playwright codegen
```

### Other commands

As for any DDEV additional service, you can use the `ddev exec -s playwright [command]` snippet to run a command in the playwright container.

For example:

- `ddev exec -s playwright yarn install --cwd ./var/www/html/yarn --force`
- `ddev exec -s playwright yarn --cwd /var/www/html/yarn test "__tests__/1-simple-test.js"`

## Technical notes

### `.npmrc` file and `.ddev/homeadditions`

If you wish to use a specific `.npmrc` file (for private NPM registries for example), you just need to place the `.npmrc` file in the `.ddev/homeadditions` folder of your project. This way, the `ddev playwright-install` command
will automatically retrieve it.

More generally, all the `.ddev/homeadditions` folder content is copied to `/home/<your-user>` folder when the `playwright`
container is build.

## Thanks

[Lullabot/ddev-playwright](https://github.com/Lullabot/ddev-playwright) is another way of implementing Playwright as a DDEV add-on. The main difference is that this other add-on embeds Playwright in the Web container. Everyone can choose what suits them best.

We'd like to thank [devianintegral](https://github.com/deviantintegral) for the fruitful discussions we've had and the fact that we are using a few pieces of code taken directly from his repository.

## Contribute

Anyone is welcome to submit a Pull Request to this repository.

For more details on development processes, please read the [developer guide](./docs/DEVELOPER.md).

**Contributed and maintained by [julienloizelet](https://github.com/julienloizelet)**

ddev-playwright

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README