[!NOTE] The Stencil Playwright adapter is currently an experimental package. Breaking changes may be introduced at any time.

The Stencil Playwright adapter is designed to only work with version 4.13.0 and higher of Stencil!

Stencil Playwright is a testing adapter package that allows developers to easily use the Playwright testing framework in their Stencil project.

For full documentation, please see the Playwright testing docs on the official Stencil site.

Getting Started

Install the necessary dependencies:

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

Install the Playwright browser binaries:
```
npx playwright install
```
Create a Playwright config at the root of your Stencil project:
```
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 section.

[!NOTE] For createConfig() to work correctly, your Stencil config must be named either stencil.config.ts or stencil.config.js.
update your project's tsconfig.json to add the ESNext.Disposable option to the lib array:
```
{
  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.
Ensure the Stencil project has a www 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 www output target config and dev server config. If no www output target is specified, tests will not be able to run.
Add the copy option to the www output target config:
```
{
   type: 'www',
   serviceWorker: null,
   copy: [{ src: '**/*.html' }, { src: '**/*.css' }]
}
```
This will clone all HTML and CSS files to the www output directory so they can be served by the dev server. If you put all testing related files in specific directory(s), you can update the copy task glob patterns to only copy those files:
```
{
   type: 'www',
   serviceWorker: null,
   copy: [{ src: '**/test/*.html' }, { src: '**/test/*.css' }]
}
```
[!NOTE] If the copy property is not set, you will not be able to use the page.goto testing pattern!
Test away! Check out the e2e testing page on the Stencil docs for more help getting started writing tests.

Testing Patterns

`page.goto()`

The goto() method allows tests to load a pre-defined HTML template. This pattern is great if a test file has many tests to execute that all use the same HTML code or if additional script or style tags need to be included in the HTML. However, with this pattern, developers are responsible for defining the necessary script tags pointing to the Stencil entry code (so all web components are correctly loaded and registered).

<!-- my-component.e2e.html -->

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf8" />

    <!-- Replace with the path to your entrypoint -->
    <script src="./build/test-app.esm.js" type="module"></script>
    <script src="./build/test-app.js" nomodule></script>
  </head>
  <body>
    <my-component first="Stencil"></my-component>
  </body>
</html>

// my-component.e2e.ts

import { expect } from '@playwright/test';
import { test } from '@stencil/playwright';

test.describe('my-component', () => {
  test('should render the correct name', async ({ page }) => {
    // The path here is the path to the www output relative to the dev server root directory
    await page.goto('/my-component/my-component.e2e.html');

    // Rest of test
  });
});

`page.setContent()`

The setContent() method allows tests to define their own HTML code on a test-by-test basis. This pattern is helpful if the HTML for a test is small, or to avoid affecting other tests is using the page.goto() pattern and modifying a shared HTML template file. With this pattern, the script tags pointing to Stencil entry code will be automatically injected into the generated HTML.

// my-component.e2e.ts

import { expect } from '@playwright/test';
import { test } from '@stencil/playwright';

test.describe('my-component', () => {
  test('should render the correct name', async ({ page }) => {
    await page.setContent('<my-component first="Stencil"></my-component>');

    // Rest of test
  });
});

API

`createConfig(overrides?: PlaywrightTestConfig): Promise<PlaywrightTestConfig>`

Returns a Playwright test configuration.

overrides, as the name implies, will overwrite the default configuration value(s) if supplied. These values can include any valid Playwright config option. Changing option values in a nested object will use a "deep merge" to combine the default and overridden values. So, creating a config like the following:

import { expect } from '@playwright/test';
import { matchers, createConfig } from '@stencil/playwright';

expect.extend(matchers);

export default createConfig({
  // Change which test files Playwright will execute
  testMatch: '*.spec.ts',

  webServer: {
    // Only wait max 30 seconds for server to start
    timeout: 30000,
  },
});

Will result in:

{
  testMatch: '*.spec.ts',
  use: {
    baseURL: 'http://localhost:3333',
  },
  webServer: {
    command: 'stencil build --dev --watch --serve --no-open',
    url: 'http://localhost:3333/ping',
    reuseExistingServer: !process.env.CI,
    // Only timeout gets overridden, not the entire object
    timeout: 30000,
  },
}

`test`

test designates which tests will be executed by Playwright. See the Playwright API documentation regarding usage.

This package modifies the page fixture and offers a skip utility as discussed below.

`page`

The page fixture is a class that allows interacting with the current test's browser tab. In addition to the default Playwright Page API, Stencil extends the class with a few additional methods:

waitForChanges(): Waits for Stencil components to re-hydrate before continuing.
spyOnEvent(): Creates a new EventSpy and listens on the window for an event to emit.

`skip`

The skip utility allows developers to skip tests for certain browsers or component modes:

test('my-test', ({ page, skip }) => {
    // Skip tests for certain browsers
    skip.browser('firefox', 'This behavior is not available on Firefox');

    // Skip tests for certain modes
    skip.mode('md', 'This behavior is not available in Material Design');

    ...
})

Keywords

stencil

playwright

testing

FAQs

What is @stencil/playwright?

Is @stencil/playwright popular?

Is @stencil/playwright well maintained?

Package last updated on 17 Sep 2024

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@stencil/playwright