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
• extraAbilities
• actors
• actor
• axios

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

externalextraAbilities

extraAbilities: (actorName: string) => Ability[] | Ability[]

Extra abilities given to the actors on top of the default ones provided by the actors fixture.

Extra abilities for all actors

To give the same set of extra abilities to all the actors, make your extraAbilities fixture return an array of Ability objects.

import { type Ability } from '@serenity-js/core';
import { describe, it, test } from '@serenity-js/playwright-test';
import { MyAbility } from './MyAbility';

describe(`My feature`, () => {

    test.use({
        extraAbilities: [ new MyAbility() ]
    });

    it(`...`, async({ actor }) => {
      // ...
    });
});

Extra abilities for selected actors

To give extra abilities only to selected actors, make your extraAbilities fixture return a (actorName: string) => Ability[] function that maps the actor name to an array of Ability objects.

import { describe, it, test } from '@serenity-js/playwright-test';
import { MyAbility } from './MyAbility';

describe(`My feature`, () => {

    test.use({
        extraAbilities: async ({ }, use) => {
            await use((actorName: string) => {
                // Alice gets the extra abilities, but others don't
                return actorName === 'Alice'
                    ? [ new MyAbility() ]
                    : [];
            })
        }
    });

    it(`...`, async({ actor }) => {
      // ...
    });
});

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?

Serenity/JS test APIs offer fixtures that set up the default cast of actors for you, which should be sufficient in most web and HTTP API testing scenarios.

Each one of the default actors receives the following abilities:

• BrowseTheWebWithPlaywright, connected to Playwright page fixture
• TakeNotes
• CallAnApi, pointing at the baseURL and using any proxy settings in your Playwright config file.

The easiest way to give your actors additional abilities is to use the extraAbilities fixture.

Overriding the default cast of Serenity/JS actors

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

interface MyNotes {
  username: string;
}

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

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

        actors: async ({ axios, extraAbilities, extraContextOptions, extraHTTPHeaders, page }, use) => {
            const cast = Cast.where(actor => {
                const abilities = Array.isArray(extraAbilities)
                    ? extraAbilities
                    : extraAbilities(actor.name);

                return actor.whoCan(
                    BrowseTheWebWithPlaywright.usingPage(page, extraContextOptions),
                    TakeNotes.using<MyNotes>(Notepad.with({
                      username: 'example.username'
                    }),
                    CallAnApi.using(axios),
                    ...abilities,
                )
            })

            // 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

externalaxios

axios: AxiosInstance | AxiosRequestConfigDefaults

An instance of the Axios HTTP client, or default Axios request configurations, to be used by the CallAnApi ability, provided to the actors via the actors fixture.

By default, Serenity/JS configures Axios to use the following settings from your Playwright configuration file:

• baseURL
• proxy
• extraHTTPHeaders