Skip to main content

BrowseTheWebWithPlaywright

This implementation of the ability to BrowseTheWeb enables the Actor to interact with web front-ends using Playwright.

Using Playwright to BrowseTheWeb

In the example below, we configure the ability to BrowseTheWebWithPlaywright with a Playwright Browser so that Serenity/JS actors can create a new BrowserContext and instantiate Playwright pages as and when needed.

This configuration allows Serenity/JS to control the process of launching and shutting down browser instances and is useful when your test runner, e.g. Cucumber.js, doesn’t offer this functionality.

import { actorCalled } from '@serenity-js/core'
import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
import { By, Navigate, PageElement, Text } from '@serenity-js/web'
import { Ensure, equals } from '@serenity-js/assertions'
import { Browser, chromium } from 'playwright'

const HomePage = {
  title: () =>
    PageElement.located(By.css('h1')).describedAs('title')
}

const browser = await chromium.launch({ headless: true });

await actorCalled('Wendy')
  .whoCan(BrowseTheWebWithPlaywright.using(browser))
  .attemptsTo(
    Navigate.to(`https://serenity-js.org`),
    Ensure.that(Text.of(HomePage.title()), equals('Serenity/JS')),
  )

Using BrowseTheWeb with an existing Playwright page

Test runners like Playwright Test manage Playwright browsers for you and offer a page instance you can inject into the ability to BrowseTheWebWithPlaywright.

Note that Serenity/JS Playwright Test module automatically configures all your actors with an ability to BrowseTheWebWithPlaywright, so you don’t need to do it by hand unless you want to override the default configuration.

The example below demonstrates how to use the BrowseTheWebWithPlaywright.usingPage API and override the default Cast of actors.

import { describe, it, test } from '@playwright/playwright-test'
import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
import { By, Navigate, PageElement, Text } from '@serenity-js/web'
import { Ensure, equals } from '@serenity-js/assertions'

const HomePage = {
  title: () =>
    PageElement.located(By.css('h1')).describedAs('title')
}

describe('Serenity/JS with Playwright', () => {

  test.use({
    actors: async ({ page, contextOptions }, use) => {
      await use(
        Cast.where((actorName: string) => {
          return actor.whoCan(
            BrowseTheWebWithPlaywright.usingPage(page),
            // ... add any other abilities
          )
        })
      )
    }
  })

  it('lets you reuse an existing page', async ({ actor }) => {
    await actor.attemptsTo(
      Navigate.to(`https://serenity-js.org`),
      Ensure.that(Text.of(HomePage.title()), equals('Serenity/JS')),
    )
  })
})

Configuring Playwright

If you’re using Serenity/JS with Playwright Test, Serenity/JS will automatically pick up your configuration from the playwright.config.ts file.

With other test runners, you can configure Playwright by:

  • providing the browser-level configuration when calling BrowserType.launch,
  • providing the browser context-level PlaywrightOptions when initialising the ability to BrowseTheWebWithPlaywright.

The code snippet below demonstrates how to configure the browser and some popular browser context options, such as viewport size, geolocation, and permissions, but you can use it to configure any other option available in Playwright, like userAgent or storageState.

import { actorCalled } from '@serenity-js/core'
import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
import { Navigate } from '@serenity-js/web'
import { Browser, chromium } from 'playwright'

// specify browser launch options
const browser = await chromium.launch({
  headless: true
});

await actorCalled('Wendy')
  .whoCan(BrowseTheWebWithPlaywright.using(browser, {
     // specify browser context options
     viewport:    { width: 1600, height: 1200 },
     geolocation: { longitude: 51.50084271042897, latitude: -0.12462540129500639 },
     permissions: [ 'geolocation' ],

     defaultNavigationTimeout: 30_000,
     defaultTimeout: 10_000

     // ... and so on
  }))
  .attemptsTo(
    Navigate.to(`https://serenity-js.org`),
    // ...
  )

Note that in addition to all the standard Playwright BrowserContextOptions, you can also provide several others defined in Serenity/JS PlaywrightOptions, such as:

  • defaultNavigationTimeout, which changes the default maximum navigation timeout for the browser context,
  • defaultTimeout, which changes the default maximum time for all Playwright methods accepting the timeout option.

Learn more

Hierarchy

  • BrowseTheWeb<playwright.Locator>
    • BrowseTheWebWithPlaywright

Implements

  • Discardable

Index

Constructors

Methods

Constructors

constructor

  • Parameters

    • session: BrowsingSession<Page<Locator>>

    Returns BrowseTheWebWithPlaywright

Methods

staticusing

staticusingPage

discard

  • discard(): Promise<void>

currentPage

  • currentPage(): Promise<Page<Locator>>

  • Returns a Page representing the currently active browser tab.

    Returns Promise<Page<Locator>>

allPages

  • allPages(): Promise<Page<Locator>[]>

  • Returns an array of pages representing all the browser tabs available in the current BrowsingSession.

    Returns Promise<Page<Locator>[]>

browserCapabilities

  • browserCapabilities(): Promise<BrowserCapabilities>

  • Returns basic meta-data about the browser associated with this ability.

    Returns Promise<BrowserCapabilities>