externalSerenityFixtures

Serenity/JS-specific Playwright Test fixtures injected into your test scenarios.

Configuring Serenity/JS using a test file

import { Ensure, equals } from '@serenity-js/assertions'
import { describe, it, test } from '@serenity-js/playwright-test'
import { Photographer, TakePhotosOfFailures } from '@serenity-js/web'

describe(`Recording items`, () => {

    test.use({
        defaultActorName: 'Serena',
        crew: [
            Photographer.whoWill(TakePhotosOfFailures),
        ],

        // Register a custom cast of Serenity/JS actors to replace the default one
        actors: async ({ browser, contextOptions, extraContextOptions, baseURL }, use) => {
             const cast = Cast.where(actor =>
                 actor.whoCan(
                     BrowseTheWebWithPlaywright.using(browser, contextOptions, extraContextOptions),
                     TakeNotes.usingAnEmptyNotepad(),
                     CallAnApi.at(baseURL),
                 )
             )

             await use(cast)
        },
    })

    describe(`Todo List App`, () => {

        it(`should allow me to add a todo item`, async ({ actor }) => {
            await actor.attemptsTo(
                startWithAnEmptyList(),

                recordItem('Buy some milk'),

                Ensure.that(itemNames(), equals([
                    'Buy some milk',
                ])),
            )
        })
    })
})

Configuring Serenity/JS using Playwright configuration file

// playwright.config.ts
import { defineConfig } from '@playwright/test'
import type { Cast, TakeNotes } from '@serenity-js/core'
import type { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
import type { SerenityFixtures, SerenityWorkerFixtures } from '@serenity-js/playwright-test'
import type { CallAnApi } from '@serenity-js/rest'

export default defineConfig<SerenityFixtures & MyCustomOptions, SerenityWorkerFixtures> = {

    // Register Serenity/JS reporter for Playwright Test
    // to enable integration with Serenity/JS stage crew members
    // and have them instantiated in the Playwright reporter process
    reporter: [
        [ '@serenity-js/playwright-test', {
            // Stage crew members instantiated in the test reporter process
            crew: [
                '@serenity-js/serenity-bdd',
                '@serenity-js/console-reporter',
                [ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
            ]
        }]
    ],

    use: {

        // Register Serenity/JS stage crew members
        // and have them instantiated in Playwright Test worker processes
        crew: [
            [ '@serenity-js/web:Photographer', { strategy: 'TakePhotosOfFailures' } ]
        ],

        // Name to be given to an actor injected via `actor` fixture
        defaultActorName: 'Alice',

        // Any other Playwright options
        baseURL: 'https://todo-app.serenity-js.org/',
        video: 'on-first-retry',
        trace: 'on-first-retry',
    },
})

Learn more

• Using Serenity/JS with Playwright Test
• PlaywrightTestConfig
• Cast
• SerenityFixtures

Index

Properties

• defaultActorName
• crew
• cueTimeout
• interactionTimeout
• extraContextOptions
• actors
• actor

Properties

externaldefaultActorName

defaultActorName: string

Configures the name given to the default Serenity/JS actor injected into a test scenario.

Learn more

• Declaring a Serenity/JS test scenario
• SerenityFixtures

externalcrew

crew: (StageCrewMember | StageCrewMemberBuilder<ListensToDomainEvents> | ClassDescription)[]

Configures the stage crew members to be instantiated in Playwright Test worker processes.

Did you know?

By default, Serenity/JS registers a Photographer.whoWill(TakePhotosOfFailures), so that any test failures are automatically accompanied by a screenshot.

If you prefer a different behaviour, you can configure the crew with an empty array to disable taking screenshots altogether (crew: []), or with a Photographer who uses a different PhotoTakingStrategy, like to TakePhotosOfInteractions.

Example

// playwright.config.ts
import type { SerenityFixtures, SerenityWorkerFixtures } from '@serenity-js/playwright-test'
import { defineConfig } from '@playwright/test'

export default defineConfig<SerenityFixtures, SerenityWorkerFixtures>({
    use: {
        crew: [
            [ '@serenity-js/web:Photographer', { strategy: 'TakePhotosOfFailures' } ]
        ],
    },
});

Learn more

• SerenityConfig.crew

externalcueTimeout

cueTimeout: number | Duration

Sets the cueTimeout to a given duration or a numeric value in milliseconds. Defaults to 5 seconds.

Learn more

• SerenityConfig.cueTimeout
• Discardable
• Ability

externalinteractionTimeout

interactionTimeout: number | Duration

The maximum default amount of time allowed for interactions such as Wait.until to complete.

Defaults to 5 seconds, can be overridden per interaction.

Learn more

• Wait.until

externalextraContextOptions

extraContextOptions: Partial<ExtraBrowserContextOptions>

Convenience properties to be used with the ability to BrowseTheWebWithPlaywright, in addition to Playwright BrowserContextOptions:

• defaultNavigationTimeout
• defaultNavigationWaitUntil
• defaultTimeout

Using extraContextOptions with the default cast of Serenity/JS actors

// playwright.config.ts
import type { SerenityFixtures, SerenityWorkerFixtures } from '@serenity-js/playwright-test'
import { defineConfig } from '@playwright/test'

export default defineConfig<SerenityFixtures, SerenityWorkerFixtures>({
    use: {
        extraContextOptions: {
            defaultNavigationTimeout: 30_000,
        }

        // Since `actors` property is not defined,
        // `extraContextOptions` will be passed to the default cast of Serenity/JS actors
        // and injected into the ability to `BrowseTheWebWithPlaywright`
        // that each actor receives.
    },
})

Using extraContextOptions with a custom cast of Serenity/JS actors

// playwright.config.ts
import type { SerenityFixtures, SerenityWorkerFixtures } from '@serenity-js/playwright-test'
import { defineConfig } from '@playwright/test'

export default defineConfig<SerenityFixtures, SerenityWorkerFixtures>({
    use: {
        extraContextOptions: {
            defaultNavigationTimeout: 30_000,
        }

        // Custom cast of actors receives the default `contextOptions` and
        // the `extraContextOptions` with the additional Serenity/JS properties.
        actors: async ({ browser, contextOptions, extraContextOptions }, use) => {
            const cast = Cast.where(actor => actor.whoCan(
                BrowseTheWebWithPlaywright.using(browser, contextOptions, extraContextOptions),
                TakeNotes.usingAnEmptyNotepad(),
            ))

            await use(cast)
        },
    },
})

Learn more

• SerenityFixtures
• Playwright Browser Context options
• Playwright Test fixtures

externalactors

actors: Cast

A cast of Serenity/JS actors to be used instead of the default cast when instantiating actor and invoking actorCalled.

Did you know?

When you use @serenity-js/playwright-test test APIs, Serenity/JS already provides a default cast of actors for you. Each one of the default actors receives abilities to BrowseTheWebWithPlaywright and TakeNotes.usingAnEmptyNotepad.

The default abilities should be sufficient in most web testing scenarios. However, you might want to override this default configuration when you need your actors to interact with REST APIs, manage local servers, start with a notepad that has some initial state, or receive custom abilities.

Overriding the default cast of Serenity/JS actors

import { Cast, TakeNotes } from '@serenity-js/core'
import { Ensure, equals } from '@serenity-js/assertions'
import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
import { describe, it, test } from '@serenity-js/playwright-test'

describe(`Recording items`, () => {

    test.use({
        extraContextOptions: {
            defaultNavigationTimeout: 30_000,
        },

        defaultActorName: 'Serena',
        actors: async ({ browser, contextOptions, extraContextOptions }, use) => {
            const cast = Cast.where(actor =>
                actor.whoCan(
                    BrowseTheWebWithPlaywright.using(browser, contextOptions, extraContextOptions),
                    TakeNotes.usingAnEmptyNotepad(),
                )
            )

            // Make sure to pass your custom cast to Playwright `use` callback
            await use(cast)
        },
    })

    describe(`Todo List App`, () => {

        it(`should allow me to add a todo item`, async ({ actor }) => {
            await actor.attemptsTo(
                startWithAnEmptyList(),

                recordItem('Buy some milk'),

                Ensure.that(itemNames(), equals([
                    'Buy some milk',
                ])),
            )
        })
    })
})


#### Learn more
- Declaring a Serenity/JS [test scenario](/api/playwright-test/function/it/)
- [`SerenityFixtures`](/api/playwright-test/interface/SerenityFixtures/)

externalactor

actor: Actor

Default actor injected into a test scenario.

Using actor fixture is equivalent to invoking actorCalled with defaultActorName.

Learn more

• actorCalled
• defaultActorName
• Declaring a Serenity/JS test scenario