Skip to main content

SerenityOptions

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

actors

actors: TestFixture<Cast, PlaywrightTestOptions & PlaywrightWorkerArgs>

Configures the Cast of 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

defaultActorName

defaultActorName: string

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

Learn more

crew

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 { PlaywrightTestConfig } from '@serenity-js/playwright-test'

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

Learn more

cueTimeout

cueTimeout: number | Duration

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

Learn more

optionalinteractionTimeout

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

contextOptions

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