external@serenity-js/playwright

Serenity/JS Playwright

@serenity-js/playwright brings full Serenity reporting capabilities to Playwright and enables writing tests using the Screenplay Pattern.

Features

• Integrates Serenity/JS with Playwright providing standardised Screenplay Web API
• Supports all Serenity/JS reporting features and expands native Playwright Test reports
• TypeScript-first design with strong typing for safer and more predictable test code.

Installation

npm install --save-dev @serenity-js/assertions @serenity-js/console-reporter @serenity-js/core @serenity-js/serenity-bdd @serenity-js/web @serenity-js/playwright

See the Serenity/JS Installation Guide.

Quick Start

Usage with Playwright Test

import { describe, it } from '@serenity-js/playwright-test'
import { Navigate, Page } from '@serenity-js/web'
import { Ensure, startsWith } from '@serenity-js/assertions'

describe('Website', () => {
    
    it('should have a title', async ({ actor }) => {

        await actor.attemptsTo(
            Navigate.to('https://serenity-js.org/'),
            Ensure.that(Page.current().title(), startsWith('Serenity/JS')),
        )
    })
})

Explore the in-depth Serenity/JS and Playwright Test integration guide in the Serenity/JS Handbook.

Usage with Cucumber

Follow the Serenity/JS configuration guide for Cucumber and the Serenity/JS Cucumber and Playwright Project Template.

Usage with Mocha

import { Ensure, startsWith } from '@serenity-js/assertions'
import { actorCalled, Cast, configure, Duration } from '@serenity-js/core'
import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
import { Navigate, Page } from '@serenity-js/web'

import { describe, it, beforeAll, afterAll } from 'mocha'
import * as playwright from 'playwright'

describe('Website', () => {

    let browser: playwright.Browser
    
    beforeAll(async () => {
        // Start a single browser before all the tests,
        // Serenity/JS will open new tabs
        // and manage Playwright browser context as needed  
        browser = await playwright.chromium.launch({
            headless: true
        })

        // Configure Serenity/JS providing your Actors
        // and required "stage crew memebers" (a.k.a. reporting services)
        configure({
            actors: Cast.where(actor => actor.whoCan(
                BrowseTheWebWithPlaywright.using(
                    browser,
                    { baseURL: `https://serenity-js.org` },
                    {
                        defaultNavigationTimeout:   Duration.ofSeconds(2).inMilliseconds(),
                        defaultTimeout:             Duration.ofMilliseconds(750).inMilliseconds(),
                    }
                )
            )),
            crew: [
                [ '@serenity-js/console-reporter', { theme: 'auto' } ],
                [ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
                [ '@serenity-js/web:Photographer', {
                    strategy: 'TakePhotosOfFailures',
                    // strategy: 'TakePhotosOfInteractions',
                } ],
                [ '@serenity-js/serenity-bdd', { specDirectory: 'spec' } ],
            ]
        })
    })
    
    it('should have a title', async () => {
 
        await actorCalled('William').attemptsTo(
            Navigate.to('https://serenity-js.org'),
            Ensure.that(Page.current().title(), startsWith('Serenity/JS')),        
        )
    })

    afterAll(async () => {
        // Close the browser after all the tests are finished
        if (browser) {
            await browser.close()
        }
    })
})

Documentation

• API Reference
• Screenplay Pattern Guide
• Serenity/JS Project Templates
• More examples and reference implementations
• Tutorial: First Web Scenario
• Tutorial: First API Scenario

Contributing

Contributions of all kinds are welcome! Get started with the Contributing Guide.

Community

• Community Chat
• Discussions Forum
  • Visit the 💡How to... ? section for answers to common questions

If you enjoy using Serenity/JS, make sure to star ⭐️ Serenity/JS on GitHub to help others discover the framework!

License

The Serenity/JS code base is licensed under the Apache-2.0 license, while its documentation and the Serenity/JS Handbook are licensed under the Creative Commons BY-NC-SA 4.0 International.

See the Serenity/JS License.

Support

Support ongoing development through GitHub Sponsors. Sponsors gain access to Serenity/JS Playbooks and priority help in the Discussions Forum.

For corporate sponsorship or commercial support, please contact Jan Molak.

Index

Abilities

• BrowseTheWebWithPlaywright

Configuration

• ExtraBrowserContextOptions
• ElectronLaunchOptions

Models

• PlaywrightBrowsingSession
• PlaywrightBrowsingSessionWithBrowser
• PlaywrightBrowsingSessionWithElectron
• PlaywrightBrowsingSessionWithPage
• PlaywrightCookie
• PlaywrightPage
• PlaywrightPageElement
• SelfLaunchingPlaywrightBrowsingSessionWithElectron
• PlaywrightLocator
• PlaywrightRootLocator

Configuration

externalElectronLaunchOptions

ElectronLaunchOptions: Parameters<typeof playwright._electron.launch>[0]

Options for launching an Electron application via Playwright.

This type re-exports Playwright's Electron launch options with additional documentation for commonly used properties.

Example

import { actorCalled } from '@serenity-js/core';
import { BrowseTheWebWithPlaywright, ElectronLaunchOptions } from '@serenity-js/playwright';

const options: ElectronLaunchOptions = {
    executablePath: '/path/to/electron',
    args: ['main.js'],
    cwd: '/path/to/app',
    env: { NODE_ENV: 'test' },
    timeout: 30000,
};

const actor = actorCalled('Tester').whoCan(
    BrowseTheWebWithPlaywright.launchingElectronApp(options)
);

Common Options

• executablePath: Path to the Electron executable. If not specified, uses the default Electron installed in node_modules/.bin/electron.
• args: Command-line arguments passed to the application. Typically includes the path to the main script (e.g., ['main.js']).
• cwd: Current working directory for the Electron process.
• env: Environment variables visible to the Electron process. Defaults to process.env.
• timeout: Maximum time in milliseconds to wait for the application to start. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.

Additional Options

• acceptDownloads: Whether to automatically download all attachments. Defaults to true.
• bypassCSP: Toggles bypassing page's Content-Security-Policy. Defaults to false.
• colorScheme: Emulates prefers-colors-scheme media feature. Supported values are 'light', 'dark', and 'no-preference'.
• locale: Specify user locale, for example en-GB, de-DE, etc.
• offline: Whether to emulate network being offline. Defaults to false.
• recordVideo: Enables video recording for all pages.
• timezoneId: Changes the timezone of the context.

Learn more

• Playwright Electron API
• Electron Testing with Playwright