@serenity-js/playwright-test

** This README is for Serenity/JS version 3.0-RC. Some links might not work yet as we're working on getting the new website and API docs ready. Thanks for your patience and support! **

Serenity/JS

Serenity/JS is a framework designed to make acceptance and regression testing of modern full-stack applications faster, more collaborative and easier to scale.

Visit serenity-js.org for the latest tutorials and API docs, and follow @SerenityJS and @JanMolak on Twitter for project updates.

Subscribe to Serenity/JS YouTube channel to get notified when new demos and video tutorials are available.

Learning Serenity/JS

To learn more about Serenity/JS, follow the tutorial, review the examples, and create your own test suite using the Serenity/JS template projects.

If you have any questions, join us on Serenity/JS Community Chat.

Serenity/JS Playwright Test

@serenity-js/playwright-test module offers a Serenity/JS reporter and fixtures that integrate Playwright Test with Serenity/JS Screenplay Pattern APIs.

Installation

To install this module, use an existing Playwright project or generate a new one by running:

npm init playwright@latest

Next, run the following command in your Playwright project directory:

npm install --save-dev @serenity-js/{assertions,console-reporter,core,serenity-bdd,web,playwright,playwright-test}

Serenity/JS Playwright Fixtures

To use Serenity/JS Screenplay Pattern APIs and benefit from the in-depth reporting capabilities, import Serenity/JS test fixtures instead of the default ones:

// example.spec.ts
+ import { test } from '@serenity-js/playwright-test'
- import { test } from '@playwright/test'

test.describe('Serenity Screenplay with Playwright', () => {
    
    test.describe('New Todo', () => {

        test('should allow me to add todo items', async ({ page }) => {
            //...
        })
    })
})

If you prefer, Serenity/JS also offers the more concise BDD-style describe/it syntax:

// example.spec.ts
import { describe, it, test } from '@serenity-js/playwright-test'

test.use({
    headles: true,
})

describe('Serenity Screenplay with Playwright', () => {
    
    describe('New Todo', () => {

        it('should allow me to add todo items', async ({ page }) => {
            //...
        })
    })
})

Serenity/JS Screenplay Pattern Actors

Serenity/JS test fixtures simplify how you instantiate and use Serenity/JS Screenplay Pattern Actors.

Single-actor scenarios

If your tests need only a single actor, you can inject it using the actor fixture. To configure the name of your default actor, use the defaultActorName configuration property:

// example.spec.ts

import { describe, it, test } from '@serenity-js/playwright-test'   // import fixtures
import { Navigate, Page } from '@serenity-js/playwright'            // import Screenplay Pattern Web APIs
import { Ensure, equals } from '@serenity-js/assertions'            // import Screenplay Pattern assertion APIs                            

test.use({
    headles: true,
    defaultActorName: 'Serena'  // change default actor name
})

describe('Serenity Screenplay with Playwright', () => {
    
    describe('New Todo', () => {

        // inject default actor:
        it('should allow me to add todo items', async ({ actor }) => { 
            
            // define test workflow
            await actor.attemptsTo(                                                  
                Navigate.to('https://todo-app.serenity-js.org/'),
                Ensure.that(Page.current().title(), equals('Serenity/JS TodoApp')),
            )
        })
    })
})

Multi-actor scenarios

For multi-actor scenarios where you need each actor to use a separate browser, use the actorCalled fixture. You can also use this pattern to override the default actor name on a per-scenario basis:

// example.spec.ts

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

describe('Serenity Screenplay with Playwright', () => {
    
    describe('Chat app', () => {

        it('should allow actors to send and receive messages', async ({ actorCalled }) => { 

            // define part of the workflow performed by the first actor:
            await actorCalled('Alice').attemptsTo(                               
                // navigate to a chat app
                // post a message to Bob
            )

            // define parts of the workflow performed by the any other actors:
            await actorCalled('Bob').attemptsTo(                                 
                // navigate to a chat app
                // post a reply to Alice
            )

            // Note that invoking actorCalled(name) multiple times
            // while using the same name and within the scope of a single test
            // returns the same actor, so you don't need to cache them:
            await actorCalled('Alice').attemptsTo(                              
                // check if the reply from Bob is received                      
            )                                                                   
        })
    })
})

Customising Actors

The default cast of actors is limited to using a single ability to BrowseTheWebWithPlaywright.

If you'd like to give your actors additional abilities, like to TakeNotes, CallAnApi, or ManageALocalServer, you can install the relevant Serenity/JS module and configure them as follows:

// example.spec.ts

import { Cast, TakeNotes } from '@serenity-js/core'
import { test } from '@serenity-js/playwright-test'
import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
import { CallAnApi } from '@serenity-js/rest'                            

test.use({
    actors: async ({ browser, baseURL }, use) => {
        await use(
            Cast.whereEveryoneCan(
                BrowseTheWebWithPlaywright.using(browser),
                TakeNotes.usingAnEmptyNotepad(),
                CallAnApi.at(baseURL),
            )
        )
    },
})

For scenarios where different actors need to be configured differently, you can also implement your own Cast:

// example.spec.ts

import { Cast } from '@serenity-js/core'
import { BrowseTheWebWithPlaywright, PlaywrightOptions } from '@serenity-js/playwright'
import { test } from '@serenity-js/playwright-test'
import { CallAnApi } from '@serenity-js/rest'
import { Browser } from 'playwright'

class Actors implements Cast {
    constructor(
        private readonly browser: Browser,
        private readonly options: PlaywrightOptions,
    ) {
    }

    prepare(actor: Actor) {
        switch (actor.name) {
            case 'James':
                return actor.whoCan(BrowseTheWebWithPlaywright.using(this.browser, this.options))
            default:
                return actor.whoCan(CallAnApi.at(this.options.baseURL))
        }
    }
}

test.use({
    actors: async ({ browser, config }) => {
        await use(new Actors(browser, {
            defaultNavigationWaitUntil: 'domcontentloaded'
        }))
    }
})

Serenity Reports

To use Serenity/JS reporting capabilities, register the @serenity-js/playwright-test reporter in your playwright.config.ts and define the appropriate reporting services (a.k.a. your "stage crew").

For example, to enable Serenity/JS Console Reporter and Serenity BDD reporter, install the relevant modules:

npm install --save-dev @serenity-js/{console-reporter,serenity-bdd}

Next, configure your Playwright project as follows:

// playwright.conf.ts

import type { PlaywrightTestConfig } from '@playwright/test'

const config: PlaywrightTestConfig = {
    reporter: [
        [ '@serenity-js/playwright-test', {
            crew: [
                '@serenity-js/serenity-bdd',
                '@serenity-js/console-reporter',
                [ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
                // '@serenity-js/core:StreamReporter',
            ]
        }],

        // optional
        [ 'html', { open: 'never' } ],          // built-in Playwright HTML reporter
    ],

    // Other configuration omitted for brevity
    // For details, see https://playwright.dev/docs/test-configuration
}

export default config

Note that Serenity/JS reporters work well with the built-in Playwright reporters.

Reference implementation

You can find a reference implementation demonstrating how to integrate Serenity/JS with Playwright Test in the Serenity/JS GitHub repository.

More coming soon!

New features, tutorials, and demos are coming soon, so follow us on Twitter and join the Serenity/JS Community chat channel to stay up to date!

If you enjoy using Serenity/JS and would like to keep new features coming, become our GitHub Sponsor and donate as much or as little as you find appropriate.

Changelog

3.0.0-rc.28 (2022-09-30)

Bug Fixes

• console-reporter: corrected default export so that it's detected as no-arg (e39fc12), closes #1240
• console-reporter: corrected error reporting when scenarios are executed in parallel (170a31e), closes #1240
• core: activity is now able to detect invocation location on Node 14 (41f4776), closes #1240
• core: enabled support for synthetic default imports and ES module interop (3e63d07), closes #1240
• core: improved implementation of EventQueue to better support parallel scenarios (025e4fd), closes #1240
• core: simplified SceneFinishes event (9ad947a), closes #1240
• playwright-test: bulk-attach all Serenity/JS events to Playwright report (a5f3d7c), closes #1240
• playwright-test: support for Playwright Test Babel loader (f9a5412), closes #1240
• playwright-test: wait for Photographer to finish taking screenshots before dismissing actors (b0c5adb), closes #1240
• playwright: corrected not(isPresent()) for PlaywrightPageElement (0693b2f), closes #1240
• playwright: upgraded Playwright to 1.25.2 (fcbfdda)
• playwright: upgraded Playwright to 1.26.0 (a13ab3c)
• rest: removed deprecated ChangeApiUrl (a8ab177), closes #1259
• web: question about Text.of(element) now trims newline and space characters (c68bbe9)

Features

• assertions: new assertion about a property of an object (9cc03d5)
• console-reporter: improved support for tests executed in parallel (01264ce), closes #1240
• console-reporter: report both total and real time it took to execute all the scenarios (654be57), closes #1240
• core: serenity/JS stage crew members can now be configured using string (786cdad), closes #1240 #594
• playwright-test: first draft of the Serenity/JS Playwright Test reporter (b9e3d89), closes #1240
• playwright-test: improved Playwright Test reports (6c6b537), closes #1240
• playwright-test: support Screenplay Pattern-style scenarios (c425c54), closes #1240
• serenity-bdd: support for configuring SerenityBDDReporter using a ClassDescription string (968e349), closes #594

Reverts

• web: reverted the change to Text that would make it automatically trim the retrieved text (f5a47b7)