@stencil/playwright
Advanced tools
[!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.
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 eitherstencil.config.tsorstencil.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
copyproperty is not set, you will not be able to use thepage.gototesting pattern!
Test away! Check out the e2e testing page on the Stencil docs for more help getting started writing tests.
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
});
});
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,
},
}
testtest 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.
pageThe 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.skipThe 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');
...
})
FAQs
Testing adapter to use Playwright with Stencil
We found that @stencil/playwright demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
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.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.