Playwright Adapter API

createStencilPlaywrightConfig Function

Signature: createStencilPlaywrightConfig(overrides?: CreateStencilPlaywrightConfigOptions): 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 as well as some options to override specific values in the config options related to the Stencil integration:

• webServerCommand: This can be specified to change the command that will run to start the Stencil dev server. Defaults to npm start -- --no-open.
• webServerTimeout: This can be specified to change the amount of time (in milliseconds) Playwright will wait for the dev server to start. Defaults to 60000 (60 seconds).

playwright.config.ts

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

expect.extend(matchers);

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

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

caution

Although any valid Playwright config option can be overridden, there are a few properties that may cause issues with tests if changed. In particular, these are the webServer and baseUrl options. These properties are automatically generated based on the Stencil project's config (analyzing the output targets and dev server configuration), so be cautious when overriding these values as it can result in issues with Playwright connecting to the Stencil dev server.

test Function

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 Fixture

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 Function

The skip() function is used to skip test execution 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');

    ...
})

Matchers

Playwright comes with a set of matchers to do test assertions. However, the Stencil Playwright adapter has additional custom matchers.

Assertion	Description
toHaveFirstReceivedEvent	Ensures that the first event received matches a specified CustomEvent.detail payload.
toHaveNthReceivedEventDetail	Ensures that the nth event received matches a specified CustomEvent.detail payload.
toHaveReceivedEvent	Ensures an event has been received at least once.
toHaveReceviedEventDetail	Ensures an event has been received with a specified CustomEvent.detail payload.
toHaveReceivedEventTimes	Ensures an event has been received a certain number of times.