Skip to main content

externalSerenityOptions

Configuration object accepted by @serenity-js/playwright-test.

Example

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

// Define any custom configuration options, if needed
interface MyCustomOptions {
    apiUrl: string;
}

const config: PlaywrightTestConfig<MyCustomOptions> = {

    // 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' } ]
        ],

        // Register a custom cast of Serenity/JS actors
        // if you don't want to use the default ones
        actors: ({ browser, contextOptions, apiUrl }, use) => {
             const cast = Cast.where(actor =>
                 actor.whoCan(
                     BrowseTheWebWithPlaywright.using(browser, contextOptions),
                     TakeNotes.usingAnEmptyNotepad(),
                     CallAnApi.at(apiUrl),
                 )
             )

             use(cast)
        },

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

        // Any custom options, as per the MyCustomOptions interface
        apiUrl: 'https://api.serenity-js.org/v1'

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

export default config

Learn more

Index

Properties

Properties

externalactors

actors: TestFixture<Cast, PlaywrightTestOptions & PlaywrightWorkerArgs>

Configures the Cast of SerenityConfig.actors|actors to be used when injecting an actor or invoking actorCalled in a test scenario.

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.

Using a custom crew of Serenity/JS actors

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

// Define any custom configuration options, if needed
interface MyCustomOptions {
    apiUrl: string;
}

// Parameterise PlaywrightTestConfig with MyCustomOptions
// to enable type checking of any custom properties
const config: PlaywrightTestConfig<MyCustomOptions> = {
    use: {
        contextOptions: {
            defaultNavigationTimeout: 30_000,
        },

        // custom properties
        apiUrl: 'https://api.serenity-js.org/v1',

        // Custom cast of actors receives `contextOptions`
        // with the additional Serenity/JS properties (see `PlaywrightOptions`),
        // as well as any other custom properties you define in the destructuring expression,
        // such as `apiUrl`.
        actors: ({ browser, contextOptions, apiUrl }, use) => {
            const cast = Cast.where(actor => actor.whoCan(
                BrowseTheWebWithPlaywright.using(browser, contextOptions),
                TakeNotes.usingAnEmptyNotepad(),
                CallAnApi.at(apiUrl),
            ))

            // Make sure to pass your custom cast to Playwright `use` callback
            use(cast)
        },
    },
};
export default config

Learn more

externaldefaultActorName

defaultActorName: string

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

Learn more

externalcrew

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

Configures the [SerenityConfig.crew|stage crew members](/api/core/class/SerenityConfig/#crew|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 { PlaywrightTestConfig } from '@serenity-js/playwright-test'

const config: PlaywrightTestConfig = {
    use: {
        crew: [
            [ '@serenity-js/web:Photographer', { strategy: 'TakePhotosOfFailures' } ]
        ],
    },
};
export default config

Learn more

externalcueTimeout

cueTimeout: number | Duration

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

Learn more

externaloptionalinteractionTimeout

interactionTimeout?: 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

externalcontextOptions

contextOptions: PlaywrightOptions

Playwright BrowserContextOptions, augmented with several convenience properties to be used with the ability to BrowseTheWebWithPlaywright.

Additional convenience properties include:

Using contextOptions with the default cast of Serenity/JS actors

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

const config: PlaywrightTestConfig = {
    use: {
        contextOptions: {
            defaultNavigationTimeout: 30_000,
        }

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

Using contextOptions with a custom cast of Serenity/JS actors

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

const config: PlaywrightTestConfig = {
    use: {
        contextOptions: {
            defaultNavigationTimeout: 30_000,
        }

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

            use(cast)
        },
    },
};
export default config;

Learn more