external@serenity-js/playwright-test

Serenity/JS is an innovative open-source framework designed to make acceptance and regression testing of complex software systems faster, more collaborative and easier to scale.

⭐️ Get started with Serenity/JS!

• Serenity/JS web testing tutorial
• Serenity/JS Handbook and Getting Started guides
• API documentation
• Serenity/JS Project Templates on GitHub

👋 Join the Serenity/JS Community!

• Meet other Serenity/JS developers and maintainers on the Serenity/JS Community chat channel,
• Find answers to your Serenity/JS questions on the Serenity/JS Forum,
• Learn how to contribute to Serenity/JS,
• Support the project and gain access to Serenity/JS Playbooks by becoming a Serenity/JS GitHub Sponsor!

Serenity/JS Playwright Test

@serenity-js/playwright-test module offers a Serenity/JS reporter and fixtures that integrate Playwright Test with Serenity/JS Screenplay Pattern APIs.

Installation

To install this module, use an existing Playwright Test project or generate a new one by running:

npm init playwright@latest

Install the below Serenity/JS modules in your Playwright Test project directory:

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

To learn more about Serenity/JS and how to use it on your project, follow the Serenity/JS Getting Started guide for Playwright Test.

Serenity/JS Playwright Fixtures

To use Serenity/JS Screenplay Pattern APIs and benefit from the in-depth reporting capabilities, import Serenity/JS test fixtures instead of the default ones:

// example.spec.ts
+ import { test } from '@serenity-js/playwright-test'
- import { test } from '@playwright/test'

test.describe('Serenity Screenplay with Playwright', () => {
    
    test.describe('New Todo', () => {

        test('should allow me to add todo items', async ({ page }) => {
            //...
        })
    })
})

If you prefer, Serenity/JS also offers the more concise BDD-style describe/it syntax:

// example.spec.ts
import { describe, it, test } from '@serenity-js/playwright-test'

test.use({
    headless: true,
})

describe('Serenity Screenplay with Playwright', () => {
    
    describe('New Todo', () => {

        it('should allow me to add todo items', async ({ page }) => {
            //...
        })
    })
})

Serenity/JS Screenplay Pattern Actors

Serenity/JS test fixtures simplify how you instantiate and use Serenity/JS Screenplay Pattern Actors.

Single-actor scenarios

If your tests need only a single actor, you can inject it using the actor fixture. To configure the name of your default actor, use the defaultActorName configuration property:

// example.spec.ts

import { describe, it, test } from '@serenity-js/playwright-test'   // import fixtures
import { Navigate, Page } from '@serenity-js/playwright'            // import Screenplay Pattern web APIs
import { Ensure, equals } from '@serenity-js/assertions'            // import Screenplay Pattern assertion APIs                            

test.use({
    headless: true,
    defaultActorName: 'Serena'  // change default actor name
})

describe('Serenity Screenplay with Playwright', () => {
    
    describe('New Todo', () => {

        // inject default actor:
        it('should allow me to add todo items', async ({ actor }) => { 
            
            // define test workflow
            await actor.attemptsTo(                                                  
                Navigate.to('https://todo-app.serenity-js.org/'),
                Ensure.that(Page.current().title(), equals('Serenity/JS TodoApp')),
            )
        })
    })
})

Multi-actor scenarios

For multi-actor scenarios where you need each actor to use a separate browser, use the actorCalled fixture. You can also use this pattern to override the default actor name on a per-scenario basis:

// example.spec.ts

import { describe, it, test } from '@serenity-js/playwright-test'   // import fixtures

describe('Serenity Screenplay with Playwright', () => {
    
    describe('Chat app', () => {

        it('should allow actors to send and receive messages', async ({ actorCalled }) => { 

            // define part of the workflow performed by the first actor:
            await actorCalled('Alice').attemptsTo(                               
                // navigate to a chat app
                // post a message to Bob
            )

            // define parts of the workflow performed by the any other actors:
            await actorCalled('Bob').attemptsTo(                                 
                // navigate to a chat app
                // post a reply to Alice
            )

            // Note that invoking actorCalled(name) multiple times
            // while using the same name and within the scope of a single test
            // returns the same actor, so you don't need to cache them:
            await actorCalled('Alice').attemptsTo(                              
                // check if the reply from Bob is received                      
            )                                                                   
        })
    })
})

Customising Actors

The default cast of actors is limited to using a single ability to BrowseTheWebWithPlaywright.

If you'd like to give your actors additional abilities, like to TakeNotes, CallAnApi, or ManageALocalServer, you can install the relevant Serenity/JS module and configure them as follows:

// example.spec.ts

import { Cast, TakeNotes } from '@serenity-js/core'
import { test } from '@serenity-js/playwright-test'
import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
import { CallAnApi } from '@serenity-js/rest'                            

test.use({
    actors: async ({ browser, baseURL }, use) => {
        await use(
            Cast.where(actor => actor.whoCan(
                BrowseTheWebWithPlaywright.using(browser),
                TakeNotes.usingAnEmptyNotepad(),
                CallAnApi.at(baseURL),
            ))
        )
    },
})

For scenarios where different actors need to be configured differently, you can also implement your own Cast:

// example.spec.ts

import { Cast } from '@serenity-js/core'
import { BrowseTheWebWithPlaywright, PlaywrightOptions } from '@serenity-js/playwright'
import { test } from '@serenity-js/playwright-test'
import { CallAnApi } from '@serenity-js/rest'
import { Browser } from 'playwright'

class Actors implements Cast {
    constructor(
        private readonly browser: Browser,
        private readonly options: PlaywrightOptions,
    ) {
    }

    prepare(actor: Actor) {
        switch (actor.name) {
            case 'James':
                return actor.whoCan(BrowseTheWebWithPlaywright.using(this.browser, this.options))
            default:
                return actor.whoCan(CallAnApi.at(this.options.baseURL))
        }
    }
}

test.use({
    actors: async ({ browser, config }) => {
        await use(new Actors(browser, {
            defaultNavigationWaitUntil: 'domcontentloaded'
        }))
    }
})

Customising test fixtures

useFixtures lets you configure Serenity/JS Screenplay Pattern actors in a single place, and define custom test fixtures if needed.

// my-custom-api.ts
export const { 
    describe, it, test, beforeAll, beforeEach, afterEach, afterAll, expect
} = useFixtures<{ email: string }>({
    
    // Override Serenity/JS fixtures:
    actors: async ({ browser, baseURL }, use) => {
        await use(
            Cast.where(actor => actor.whoCan(
                BrowseTheWebWithPlaywright.using(browser),
                TakeNotes.usingAnEmptyNotepad(),
                CallAnApi.at(baseURL),
            ))
        )
    },
    
    // Add your own fixtures:
    email: async ({ actor }, use) => {
        await use(`${ actor.name }@example.org`);
    },    
})

With the custom test API definition in place, use it in your test files instead of the default one:

// example.spec.ts
import { Log } from '@serenity-js/core'

import { describe, it, test } from './my-custom-api'    // Note the custom test API

describe('Serenity Screenplay with Playwright', () => {

    describe('New Todo', () => {

        // inject default actor:
        it('should allow me to add todo items', async ({ actor, email }) => {

            // define test workflow
            await actor.attemptsTo(
                Log.the(email),
            )
        })
    })
})

UI Component Testing

You can use Serenity/JS and Playwright Test to write UI component tests and reuse your test code between component and end-to-end test suites.

To get started with component testing:

• Follow the Playwright Test Component Testing tutorial to configure your component test suite,
• Use Serenity/JS test fixtures instead of the default ones.

// src/App.spec.tsx
- import { test, expect } from '@playwright/experimental-ct-react'
+ import { test as componentTest } from '@playwright/experimental-ct-react'
+ import { useBase } from '@serenity-js/playwright-test'

+ const { test, expect } = useBase(componentTest)

import App from './App'

test.use({ viewport: { width: 500, height: 500 } })

test('should work', async ({ mount }) => {
  const component = await mount(<App />)
  await expect(component).toContainText('Learn React')
})

Using Serenity/JS Screenplay Pattern Actors for Component Testing

Serenity/JS useBase(test) creates a test API that gives you access to all the SerenityFixtures you could access in any other regular end-to-end test.

This capability allows you to use Serenity/JS Actors and design and experiment with your Screenplay Pattern Tasks before incorporating them in your high-level acceptance and end-to-end tests.

import { test as componentTest } from '@playwright/experimental-ct-react'
import { Ensure, contain } from '@serenity-js/assertions'
import { useBase } from '@serenity-js/playwright-test'
import { Enter, PageElement, CssClasses } from '@serenity-js/web'

import EmailInput from './EmailInput'

const { it, describe } = useBase(componentTest).useFixtures<{ emailAddress: string }>({
    emailAddress: ({ actor }, use) => {
        use(`${ actor.name }@example.org`)
    }
})

describe('EmailInput', () => {

    it('allows valid email addresses', async ({ actor, mount, emailAddress }) => {
        const nativeComponent = await mount(<EmailInput/>)

        const component = PageElement.from(nativeComponent)

        await actor.attemptsTo(
            Enter.theValue(emailAddress).into(component),
            Ensure.that(CssClasses.of(component), contain('valid')),
        )
    })
})

Serenity Reports

To use Serenity/JS reporting capabilities, register the @serenity-js/playwright-test reporter in your playwright.config.ts and define the appropriate reporting services (a.k.a. your "stage crew").

For example, to enable Serenity/JS Console Reporter and Serenity BDD Reporter, install the relevant modules:

npm install --save-dev @serenity-js/console-reporter @serenity-js/serenity-bdd

Next, configure your Playwright project as follows:

// playwright.conf.ts

import type { PlaywrightTestConfig } from '@playwright/test'

const config: PlaywrightTestConfig = {
    testDir: './spec',
    
    reporter: [
        [ '@serenity-js/playwright-test', {
            crew: [
                '@serenity-js/console-reporter',
                [ '@serenity-js/serenity-bdd', { specDirectory: './spec' } ],
                [ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
                // '@serenity-js/core:StreamReporter',
            ]
        }],

        // optional
        [ 'html', { open: 'never' } ],          // built-in Playwright HTML reporter
    ],

    // Other configuration omitted for brevity
    // For details, see https://playwright.dev/docs/test-configuration
}

export default config

Note that Serenity/JS reporters work well with the built-in Playwright reporters.

Reference implementation

You can find a reference implementation demonstrating how to integrate Serenity/JS with Playwright Test in the Serenity/JS GitHub repository.

📣 Stay up to date

New features, tutorials, and demos are coming soon! Follow Serenity/JS on LinkedIn, subscribe to Serenity/JS channel on YouTube and join the Serenity/JS Community Chat to stay up to date! Please also make sure to star ⭐️ Serenity/JS on GitHub to help others discover the framework!

💛 Support Serenity/JS

If you appreciate all the effort that goes into making sophisticated tools easy to work with, please support our work and become a Serenity/JS GitHub Sponsor today!

Index

Classes

• default

Functions

• it
• test
• describe
• beforeAll
• beforeEach
• afterEach
• afterAll
• expect
• useFixtures
• useBase

Interfaces

• SerenityFixtures
• SerenityOptions
• SuiteFunction
• SerenityReporterForPlaywrightTestConfig

Type Aliases

• DescribeFunction
• PlaywrightTestConfig
• TestApi

Variables

• fixtures

Type Aliases

externalDescribeFunction

DescribeFunction: SuiteFunction & { only: SuiteFunction; skip: SuiteFunction; fixme: SuiteFunction; serial: SuiteFunction & { only: SuiteFunction }; parallel: SuiteFunction & { only: SuiteFunction }; configure: (options: { mode?: default | parallel | serial; retries?: number; timeout?: number }) => void }

externalPlaywrightTestConfig

PlaywrightTestConfig<TestArgs, WorkerArgs>: BasePlaywrightTestConfig<SerenityOptions & TestArgs, WorkerArgs>

Convenience alias for PlaywrightTestConfig object that includes SerenityOptions and allows for any other custom options when needed.

Example

Configuring Playwright Test using the standard PlaywrightTestConfig from @playwright/test:

// playwright.config.ts
import type { PlaywrightTestConfig } from '@playwright/test'
import type { SerenityOptions } from '@serenity-js/playwright-test'

const config: PlaywrightTestConfig<SerenityOptions & MyCustomOptions> = {
    // ...
}

export default config

Simplified configuration using Serenity/JS PlaywrightTestConfig from @serenity-js/playwright-test:

// playwright.config.ts
import type { PlaywrightTestConfig } from '@serenity-js/playwright-test'

const config: PlaywrightTestConfig<MyCustomOptions> = {
   // ...
}
export default config

Learn more

• SerenityOptions
• SerenityFixtures
• SerenityReporterForPlaywrightTestConfig
• Playwright Test configuration

---

Type parameters

• TestArgs = object
• WorkerArgs = object

externalTestApi

TestApi<TestArgs, WorkerArgs>: Pick<TestType<TestArgs, WorkerArgs>, beforeAll | beforeEach | afterEach | afterAll | expect> & { useFixtures: <T, W>(customFixtures: Fixtures<T, W, TestArgs, WorkerArgs>) => TestApi<TestArgs & T, WorkerArgs & W>; it: TestType<TestArgs, WorkerArgs>; test: TestType<TestArgs, WorkerArgs>; describe: DescribeFunction }

Serenity/JS BDD-style test API created by useBase.

---

Type parameters

• TestArgs: Record<string, any>
• WorkerArgs: Record<string, any>

Variables

externalconstfixtures

fixtures: Fixtures<Omit<SerenityOptions, actors> & SerenityFixtures, object, PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions> = ...