ddev-playwright
Table of Contents
Introduction
Playwright 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
For DDEV v1.23.5 or above run
ddev add-on get julienloizelet/ddev-playwright
For earlier versions of DDEV run
ddev get julienloizelet/ddev-playwright
Then restart your project
ddev restart
[!NOTE] If you change
additional_hostnamesoradditional_fqdns, you have to re-runddev add-on get julienloizelet/ddev-playwright.
Basic usage
Quick start
- Create a
tests/Playwrightfolder in your project root directory (Only required for this “quick start”). ddev playwright-init --pm npmddev 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:
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:
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).
.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/Playwrightfolder of this repository.
<p>Example of package.json file</summary></p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> </span><span class="nl">"license"</span><span class="p">:</span><span class="w"> </span><span class="s2">"MIT"</span><span class="p">,</span><span class="w"> </span><span class="nl">"dependencies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="nl">"@playwright/test"</span><span class="p">:</span><span class="w"> </span><span class="s2">"^1.34.2"</span><span class="p">,</span><span class="w">
</span><span class="nl">"dotenv"</span><span class="p">:</span><span class="w"> </span><span class="s2">"^16.0.3"</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span></code></pre></div> </div>
<p></details></p>
<p>You will also find an example of a <code class="language-plaintext highlighter-rouge">playwright.config.js</code> file.</p>
<details>
<summary>
<p>Example of playwright.config.js file</summary></p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// @ts-check</span> <span class="kd">const</span> <span class="p">{</span> <span class="nx">defineConfig</span><span class="p">,</span> <span class="nx">devices</span> <span class="p">}</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="dl">"</span><span class="s2">@playwright/test</span><span class="dl">"</span><span class="p">);</span>
require(”dotenv”).config({ path: ”.env” });
/**
- @see https://playwright.dev/docs/test-configuration
*/</span>
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”] },
},
<span class="p">{</span>
<span class="na">name</span><span class="p">:</span> <span class="dl">"</span><span class="s2">firefox</span><span class="dl">"</span><span class="p">,</span>
<span class="na">use</span><span class="p">:</span> <span class="p">{</span> <span class="p">...</span><span class="nx">devices</span><span class="p">[</span><span class="dl">"</span><span class="s2">Desktop Firefox</span><span class="dl">"</span><span class="p">]</span> <span class="p">},</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="na">name</span><span class="p">:</span> <span class="dl">"</span><span class="s2">webkit</span><span class="dl">"</span><span class="p">,</span>
<span class="na">use</span><span class="p">:</span> <span class="p">{</span> <span class="p">...</span><span class="nx">devices</span><span class="p">[</span><span class="dl">"</span><span class="s2">Desktop Safari</span><span class="dl">"</span><span class="p">]</span> <span class="p">},</span>
<span class="p">},</span> <span class="p">],</span> <span class="p">});</span> </code></pre></div> </div>
<p></details></p>
<h4 id="init-a-playwright-project-from-scratch">Init a Playwright project from scratch</h4>
<ul>
<li><code class="language-plaintext highlighter-rouge">ddev playwright-init --pm [npm|yarn]</code></li>
</ul>
<p>This command will initialize a Playwright project in the <code class="language-plaintext highlighter-rouge">PLAYWRIGHT_TEST_DIR</code> as described in the <a href="https://playwright.dev/docs/intro#installing-playwright">Playwright documentation</a>.</p>
<p>You can choose to use <code class="language-plaintext highlighter-rouge">npm</code> or <code class="language-plaintext highlighter-rouge">yarn</code> as package manager by using the <code class="language-plaintext highlighter-rouge">--pm</code> option. By default, <code class="language-plaintext highlighter-rouge">yarn</code> is used.</p>
<p><strong>NB:</strong> Please note that this command is interactive and <a href="https://github.com/microsoft/playwright/issues/11843">should not be used in CI context</a>.</p>
<h4 id="run-a-playwright-command">Run a Playwright command</h4>
<ul>
<li><code class="language-plaintext highlighter-rouge">ddev playwright</code></li>
</ul>
<p>You can run all the playwright command with <code class="language-plaintext highlighter-rouge">ddev playwright [command]</code>.</p>
<ul>
<li>
<p>To run playwright’s test command:</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ddev playwright <span class="nb">test</span> </code></pre></div> </div>
</li>
<li>
<p>To run with the Playwright UI tool.</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ddev playwright <span class="nb">test</span> <span class="nt">--ui</span> </code></pre></div> </div>
</li>
<li>
<p>To run in headed mode.</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ddev playwright <span class="nb">test</span> <span class="nt">--headed</span> </code></pre></div> </div>
</li>
<li>
<p>To generate playwright report</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ddev playwright show-report <span class="nt">--host</span> 0.0.0.0 </code></pre></div> </div>
<p>and then browse to <code class="language-plaintext highlighter-rouge">https://<PROJECT>.ddev.site:9323</code></p>
<p><img src="https://raw.githubusercontent.com/julienloizelet/ddev-playwright/main/./docs/show-report.jpg" alt="show report" /></p>
</li>
</ul>
<h3 id="vnc-server">VNC server</h3>
<p>When running in UI/headed mode, you can use the provided Kasmvnc service by browsing to <code class="language-plaintext highlighter-rouge">https://<PROJECT>.ddev.site:8444</code></p>
<p><img src="https://raw.githubusercontent.com/julienloizelet/ddev-playwright/main/./docs/kasmvnc.jpg" alt="kasmvnc" /></p>
<p>It could be also used to generate playwright code by browsing with the following command:</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ddev playwright codegen </code></pre></div> </div>
<h3 id="other-commands">Other commands</h3>
<p>As for any DDEV additional service, you can use the <code class="language-plaintext highlighter-rouge">ddev exec -s playwright [command]</code> snippet to run a command in the playwright container.</p>
<p>For example:</p>
<ul>
<li><code class="language-plaintext highlighter-rouge">ddev exec -s playwright yarn install --cwd ./var/www/html/yarn --force</code></li>
<li><code class="language-plaintext highlighter-rouge">ddev exec -s playwright yarn --cwd /var/www/html/yarn test "__tests__/1-simple-test.js"</code></li>
</ul>
<h2 id="technical-notes">Technical notes</h2>
<h3 id="npmrc-file-and-ddevhomeadditions"><code class="language-plaintext highlighter-rouge">.npmrc</code> file and <code class="language-plaintext highlighter-rouge">.ddev/homeadditions</code></h3>
<p>If you wish to use a specific <code class="language-plaintext highlighter-rouge">.npmrc</code> file (for private NPM registries for example), you just need to place the <code class="language-plaintext highlighter-rouge">.npmrc</code> file in the <code class="language-plaintext highlighter-rouge">.ddev/homeadditions</code> folder of your project. This way, the <code class="language-plaintext highlighter-rouge">ddev playwright-install</code> command will automatically retrieve it.</p>
<p>More generally, all the <code class="language-plaintext highlighter-rouge">.ddev/homeadditions</code> folder content is copied to <code class="language-plaintext highlighter-rouge">/home/pwuser</code> folder when the <code class="language-plaintext highlighter-rouge">playwright</code> container is build.</p>
<h2 id="thanks">Thanks</h2>
<p><a href="https://github.com/Lullabot/ddev-playwright">Lullabot/ddev-playwright</a> 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.</p>
<p>We’d like to thank <a href="https://github.com/deviantintegral">devianintegral</a> for the fruitful discussions we’ve had and the fact that we are using a few pieces of code taken directly from his repository.</p>
<h2 id="contribute">Contribute</h2>
<p>Anyone is welcome to submit a Pull Request to this repository.</p>
<p>For more details on development processes, please read the <a href="https://github.com/julienloizelet/ddev-playwright/blob/main/./docs/DEVELOPER.md">developer guide</a>.</p>
<p><strong>Contributed and maintained by <a href="https://github.com/julienloizelet">julienloizelet</a></strong></p>
</summary>
</details>
<p>Example of package.json file</summary></p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> </span><span class="nl">"license"</span><span class="p">:</span><span class="w"> </span><span class="s2">"MIT"</span><span class="p">,</span><span class="w"> </span><span class="nl">"dependencies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="nl">"@playwright/test"</span><span class="p">:</span><span class="w"> </span><span class="s2">"^1.34.2"</span><span class="p">,</span><span class="w">
</span><span class="nl">"dotenv"</span><span class="p">:</span><span class="w"> </span><span class="s2">"^16.0.3"</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span></code></pre></div> </div>
<p></details></p>
<p>You will also find an example of a <code class="language-plaintext highlighter-rouge">playwright.config.js</code> file.</p>
<details>
<summary>
<p>Example of playwright.config.js file</summary></p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// @ts-check</span> <span class="kd">const</span> <span class="p">{</span> <span class="nx">defineConfig</span><span class="p">,</span> <span class="nx">devices</span> <span class="p">}</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="dl">"</span><span class="s2">@playwright/test</span><span class="dl">"</span><span class="p">);</span>
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”,
},<span class="p">{</span>
<span class="na">name</span><span class="p">:</span> <span class="dl">"</span><span class="s2">firefox</span><span class="dl">"</span><span class="p">,</span>
<span class="na">use</span><span class="p">:</span> <span class="p">{</span> <span class="p">...</span><span class="nx">devices</span><span class="p">[</span><span class="dl">"</span><span class="s2">Desktop Firefox</span><span class="dl">"</span><span class="p">]</span> <span class="p">},</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="na">name</span><span class="p">:</span> <span class="dl">"</span><span class="s2">webkit</span><span class="dl">"</span><span class="p">,</span>
<span class="na">use</span><span class="p">:</span> <span class="p">{</span> <span class="p">...</span><span class="nx">devices</span><span class="p">[</span><span class="dl">"</span><span class="s2">Desktop Safari</span><span class="dl">"</span><span class="p">]</span> <span class="p">},</span>
<span class="p">},</span> <span class="p">],</span> <span class="p">});</span> </code></pre></div> </div>
<p></details></p>
<h4 id="init-a-playwright-project-from-scratch">Init a Playwright project from scratch</h4>
<ul>
<li><code class="language-plaintext highlighter-rouge">ddev playwright-init --pm [npm|yarn]</code></li>
</ul>
<p>This command will initialize a Playwright project in the <code class="language-plaintext highlighter-rouge">PLAYWRIGHT_TEST_DIR</code> as described in the <a href="https://playwright.dev/docs/intro#installing-playwright">Playwright documentation</a>.</p>
<p>You can choose to use <code class="language-plaintext highlighter-rouge">npm</code> or <code class="language-plaintext highlighter-rouge">yarn</code> as package manager by using the <code class="language-plaintext highlighter-rouge">--pm</code> option. By default, <code class="language-plaintext highlighter-rouge">yarn</code> is used.</p>
<p><strong>NB:</strong> Please note that this command is interactive and <a href="https://github.com/microsoft/playwright/issues/11843">should not be used in CI context</a>.</p>
<h4 id="run-a-playwright-command">Run a Playwright command</h4>
<ul>
<li><code class="language-plaintext highlighter-rouge">ddev playwright</code></li>
</ul>
<p>You can run all the playwright command with <code class="language-plaintext highlighter-rouge">ddev playwright [command]</code>.</p>
<ul>
<li>
<p>To run playwright’s test command:</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ddev playwright <span class="nb">test</span> </code></pre></div> </div>
</li>
<li>
<p>To run with the Playwright UI tool.</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ddev playwright <span class="nb">test</span> <span class="nt">--ui</span> </code></pre></div> </div>
</li>
<li>
<p>To run in headed mode.</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ddev playwright <span class="nb">test</span> <span class="nt">--headed</span> </code></pre></div> </div>
</li>
<li>
<p>To generate playwright report</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ddev playwright show-report <span class="nt">--host</span> 0.0.0.0 </code></pre></div> </div>
<p>and then browse to <code class="language-plaintext highlighter-rouge">https://<PROJECT>.ddev.site:9323</code></p>
<p><img src="https://raw.githubusercontent.com/julienloizelet/ddev-playwright/main/./docs/show-report.jpg" alt="show report" /></p>
</li>
</ul>
<h3 id="vnc-server">VNC server</h3>
<p>When running in UI/headed mode, you can use the provided Kasmvnc service by browsing to <code class="language-plaintext highlighter-rouge">https://<PROJECT>.ddev.site:8444</code></p>
<p><img src="https://raw.githubusercontent.com/julienloizelet/ddev-playwright/main/./docs/kasmvnc.jpg" alt="kasmvnc" /></p>
<p>It could be also used to generate playwright code by browsing with the following command:</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ddev playwright codegen </code></pre></div> </div>
<h3 id="other-commands">Other commands</h3>
<p>As for any DDEV additional service, you can use the <code class="language-plaintext highlighter-rouge">ddev exec -s playwright [command]</code> snippet to run a command in the playwright container.</p>
<p>For example:</p>
<ul>
<li><code class="language-plaintext highlighter-rouge">ddev exec -s playwright yarn install --cwd ./var/www/html/yarn --force</code></li>
<li><code class="language-plaintext highlighter-rouge">ddev exec -s playwright yarn --cwd /var/www/html/yarn test "__tests__/1-simple-test.js"</code></li>
</ul>
<h2 id="technical-notes">Technical notes</h2>
<h3 id="npmrc-file-and-ddevhomeadditions"><code class="language-plaintext highlighter-rouge">.npmrc</code> file and <code class="language-plaintext highlighter-rouge">.ddev/homeadditions</code></h3>
<p>If you wish to use a specific <code class="language-plaintext highlighter-rouge">.npmrc</code> file (for private NPM registries for example), you just need to place the <code class="language-plaintext highlighter-rouge">.npmrc</code> file in the <code class="language-plaintext highlighter-rouge">.ddev/homeadditions</code> folder of your project. This way, the <code class="language-plaintext highlighter-rouge">ddev playwright-install</code> command will automatically retrieve it.</p>
<p>More generally, all the <code class="language-plaintext highlighter-rouge">.ddev/homeadditions</code> folder content is copied to <code class="language-plaintext highlighter-rouge">/home/pwuser</code> folder when the <code class="language-plaintext highlighter-rouge">playwright</code> container is build.</p>
<h2 id="thanks">Thanks</h2>
<p><a href="https://github.com/Lullabot/ddev-playwright">Lullabot/ddev-playwright</a> 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.</p>
<p>We’d like to thank <a href="https://github.com/deviantintegral">devianintegral</a> for the fruitful discussions we’ve had and the fact that we are using a few pieces of code taken directly from his repository.</p>
<h2 id="contribute">Contribute</h2>
<p>Anyone is welcome to submit a Pull Request to this repository.</p>
<p>For more details on development processes, please read the <a href="https://github.com/julienloizelet/ddev-playwright/blob/main/./docs/DEVELOPER.md">developer guide</a>.</p>
<p><strong>Contributed and maintained by <a href="https://github.com/julienloizelet">julienloizelet</a></strong></p>
</summary>
</details>