Configuration

Serenity/JS configuration lives alongside the rest of your Playwright Test configuration in playwright.config.ts. Use the reporter option to register @serenity-js/playwright-test and the reporting Crew Members that publish results after a run. Configure the Actors and services available in test scenarios via use.

Configure	Where	Use it for
Reporting	reporter	Register the Serenity/JS reporter and reporting Crew Members, such as the Console Reporter and HTML Reporter.
Actor and scenario services	use	Configure the default Actor name, automatic screenshots, browser context options, extra Abilities, or a custom Cast.
Global use	Top-level use in playwright.config.ts	Apply configuration to every test scenario.
Project use	Project-level use in playwright.config.ts	Apply configuration to every scenario in a Playwright project; overrides global settings.
Per-scenario configuration	test.use in spec files	Apply configuration to a scenario or group of scenarios; overrides project and global settings.

This guide covers reporting and automatic screenshots. See Customising actors for Actor configuration, Reporting to choose report formats, and the fixture API reference for scenario-level configuration.

Integrating Serenity/JS reporting

To integrate Serenity/JS reporting, modify the playwright.config.ts file as follows:

playwright.config.ts

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

export default defineConfig<SerenityFixtures, SerenityWorkerFixtures>({
    testDir: './spec',

    reporter: [
        // Serenity/JS reporting services
        [ '@serenity-js/playwright-test', {
            crew: [
                '@serenity-js/console-reporter',
                [ '@serenity-js/html-reporter', {
                  specDirectory: './spec'
                } ],
            ]
        }],

        // Any other native Playwright Test reporters
        [ 'html', { open: 'never' } ],
    ],

    // Other Playwright Test configuration options
});

This configuration enables the @serenity-js/playwright-test test runner adapter, which in turn configures the "stage crew" of Serenity/JS reporting services:

• Console reporter - Displays test results in the terminal.
• HTML Reporter - Produces a self-contained HTML report with trend history, flaky test detection, and an interactive dashboard.

Note that the above configuration assumes the following directory structure of your project:

• ./spec - stores your test scenarios and is the top-most directory of your requirements hierarchy.

If you'd like to use a different location for your tests, adjust the specDirectory setting accordingly.

Using Serenity BDD Reporter instead?

If you prefer Serenity BDD's multi-page report format, see the Serenity BDD Reporter configuration.

Enabling automatic screenshots

Serenity/JS offers automatic screenshot capture for test scenarios using the Screenplay Pattern. This is handled by the Photographer service, which takes screenshots based on interactions and assertion failures performed by the Serenity/JS actors.

To capture screenshots automatically, add the @serenity-js/web:Photographer service to the crew array in the appropriate use section of your playwright.config.ts configuration file. Use TakePhotosOfFailures for a focused failure record, or TakePhotosOfInteractions when you need an audit trail.

There are three available scopes for configuring the Photographer:

• testConfig.use - Global scope for all test scenarios.
• testProject.use - Project-specific scope that overrides global settings.
• test.use - Test file scope, which overrides both global and project configurations.

For example, to take screenshots only on assertion failures by default, but capture every interaction in the audit-trail test suite, configure your project as follows:

playwright.config.ts

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

export default defineConfig<SerenityFixtures, SerenityWorkerFixtures>({
    reporter: [
        // ...
    ],

    // Global configuration for all test scenarios
    use: {
        crew: [
            // Automatically take screenshots upon an assertion failure
            ['@serenity-js/web:Photographer', { strategy: 'TakePhotosOfFailures' }]
        ],
        defaultActorName: 'Alice',
    },

    projects: [
        // Per-project configuration, overrides the global defaults.
        {
            name: 'audit-trail',
            testMatch: [
                '**/audit-trail/**/*.spec.ts',
            ],
            use: {
                ...devices['Desktop Chrome'],
                crew: [
                    // Automatically take screenshots of every actor interaction
                    ['@serenity-js/web:Photographer', { strategy: 'TakePhotosOfInteractions' }]
                ],
            },
        },
        // Other projects
    }

    // Other Playwright Test configuration options
});

You also have the option to configure the Photographer for individual test files. To do that, add the test.use outside of any describe blocks.

spec/checkout.spec.ts

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

test.use({
  crew: [
    [ '@serenity-js/web:Photographer', { strategy: 'TakePhotosOfInteractions' } ]
  ]
})

describe('Checkout', () => {

    // test scenarios
})

Learn more about:

• Serenity/JS test fixtures and configuration options
• Serenity/JS test fixtures and configuration options
• Playwright Test configuration options

What you learnt

• Serenity/JS reporting is configured in the reporter array of playwright.config.ts.
• The Photographer captures screenshots automatically — configure it in the use.crew array.
• Screenshot strategies can be scoped globally, per-project, or per-file.

Next step

Once you've configured reporting, proceed to writing tests.