Playwright Overview

Playwright is an automated end-to-end testing framework built to run on all modern browser engines and operating systems. Playwright leverages the DevTools protocol to provide reliable tests that run in actual browsers.

Set Up

To add Playwright to an existing Stencil project, leverage the Stencil Playwright testing adapter. This is a tool built by the Stencil team to help Stencil and Playwright work better together. The best part is you'll write your tests using the same APIs as defined and documented by Playwright. So, be sure to check out their documentation for help writing your first tests!

The quickest way to set up is the wizard. Run it from your Stencil project:

stencil add @stencil/playwright

It installs the adapter and Playwright, creates playwright.config.ts, adds ESNext.Disposable to your tsconfig.json, and adds a test:e2e script to your package.json. Afterwards, install the Playwright browser binaries with npx playwright install.

To set up by hand instead, follow these steps:

1. Install the necessary dependencies:

   npm

   npm i @stencil/playwright @playwright/test --save-dev

   Yarn

   yarn add @stencil/playwright @playwright/test --dev

   pnpm

   pnpm add @stencil/playwright @playwright/test --save-dev

2. Install the Playwright browser binaries:

   npx playwright install

3. Create a Playwright config at the root of your Stencil project:

   playwright.config.ts

   import { expect } from '@playwright/test';
   import { matchers, createConfig } from '@stencil/playwright';
   
   // Add custom Stencil matchers to Playwright assertions
   expect.extend(matchers);
   
   export default createConfig({
     // Overwrite Playwright config options here
   });

   The createConfig() function is a utility that will create a default Playwright configuration based on your project's Stencil config. Read more about how to use this utility in the API docs.

   note

   For createConfig() to work correctly, your Stencil config must be named either stencil.config.ts or stencil.config.js.

4. update your project's tsconfig.json to add the ESNext.Disposable option to the lib array:

   tsconfig.json

   {
     lib: [
       ...,
       "ESNext.Disposable"
     ],
     ...
   }
   note

   This will resolve a build error related to Symbol.asyncDispose. If this is not added, tests may fail to run since the Stencil dev server will be unable to start due to the build error.

5. Ensure the Stencil project has a www, loader-bundle, or standalone output target. Playwright relies on pre-compiled output running in a dev server to run tests against. When using the createConfig() helper, a configuration for the dev server will be automatically created based on the Stencil project's output target config and dev server config. If the project has more than one, the first of www, loader-bundle, and standalone is used.

6. If you use the page.goto pattern with HTML test pages, make sure the dev server can serve them:

   • With a www output target, Stencil writes every HTML file under src to the www directory, keeping its path. If those pages load other files, such as CSS, add a copy task for them:

     stencil.config.ts

     {
        type: 'www',
        copy: [{ src: '**/test/*.css' }]
     }

   • With only a loader-bundle output target, the dev server serves your project's root directory, and page.goto takes the path from there, such as /src/components/my-component/my-component.e2e.html.

7. Test away! Check out the e2e testing page for more help getting started writing tests.

Migrating to Playwright

Coming from Stencil v4's integrated e2e testing (stencil test --e2e and newE2EPage())? See Migrating E2E Tests to Playwright.