@serenity-js/playwright
Version:
Adapter that integrates @serenity-js/web with Playwright, enabling Serenity/JS reporting and using the Screenplay Pattern to write component and end-to-end test scenarios
283 lines (274 loc) • 12.5 kB
text/typescript
import { Discardable, Initialisable } from '@serenity-js/core';
import { BrowseTheWeb } from '@serenity-js/web';
import * as playwright from 'playwright-core';
import type { ExtraBrowserContextOptions } from '../../ExtraBrowserContextOptions.js';
import {
type ElectronLaunchOptions,
PlaywrightBrowsingSessionWithBrowser,
PlaywrightBrowsingSessionWithElectron,
PlaywrightBrowsingSessionWithPage,
SelfLaunchingPlaywrightBrowsingSessionWithElectron
} from '../models/index.js';
/**
* This implementation of the [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
* enables the [`Actor`](https://serenity-js.org/api/core/class/Actor/) to interact with web front-ends using [Playwright](https://playwright.dev/).
*
* ## Using Playwright to `BrowseTheWeb`
*
* In the example below, we configure the ability to [`BrowseTheWebWithPlaywright`](https://serenity-js.org/api/playwright/class/BrowseTheWebWithPlaywright/) with a Playwright
* [`Browser`](https://playwright.dev/docs/api/class-browser) so that Serenity/JS [actors](https://serenity-js.org/api/core/class/Actor/)
* can create a new [`BrowserContext`](https://playwright.dev/docs/api/class-browsercontext) and
* instantiate Playwright [`page`s](https://playwright.dev/docs/api/class-page) 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](https://serenity-js.org/api/cucumber), doesn't offer this functionality.
*
* ```ts
* 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](https://serenity-js.org/api/playwright-test/) manage Playwright browsers for you
* and offer a [`page`](https://playwright.dev/docs/api/class-page) instance you can
* inject into the ability to [`BrowseTheWebWithPlaywright`](https://serenity-js.org/api/playwright/class/BrowseTheWebWithPlaywright/).
*
* Note that [Serenity/JS Playwright Test module](https://serenity-js.org/api/playwright-test/)
* automatically configures all your [actors](https://serenity-js.org/api/core/class/Actor/)
* with an ability to [`BrowseTheWebWithPlaywright`](https://serenity-js.org/api/playwright/class/BrowseTheWebWithPlaywright/),
* so you don't need to do it by hand unless you want to override the [default configuration](https://serenity-js.org/api/playwright-test/interface/SerenityFixtures/).
*
* The example below demonstrates how to use the [`BrowseTheWebWithPlaywright.usingPage`](https://serenity-js.org/api/playwright/class/BrowseTheWebWithPlaywright/#usingPage) API and
* override the default [cast](https://serenity-js.org/api/core/class/Cast/) of actors.
*
* ```ts
* 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](https://serenity-js.org/handbook/test-runners/playwright-test/),
* Serenity/JS will automatically pick up your configuration from the [`playwright.config.ts`](https://playwright.dev/docs/test-configuration) file.
*
* With other [test runners](https://serenity-js.org/handbook/test-runners/), you can configure Playwright by:
* - providing the browser-level configuration when calling [`BrowserType.launch`](https://playwright.dev/docs/api/class-browsertype#browser-type-launch),
* - providing the browser context-level [`ExtraBrowserContextOptions`](https://serenity-js.org/api/playwright/interface/ExtraBrowserContextOptions/)
* 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](https://playwright.dev/docs/api/class-browser#browser-new-context-option-viewport),
* [`geolocation`](https://playwright.dev/docs/api/class-browser#browser-new-page-option-geolocation),
* and [`permissions`](https://playwright.dev/docs/api/class-browser#browser-new-page-option-permissions),
* but you can use it to configure any other option available in Playwright, like
* [`userAgent`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-user-agent)
* or [`storageState`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-storage-state).
*
* ```ts
* 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
* }))
* .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 [`ExtraBrowserContextOptions`](https://serenity-js.org/api/playwright/interface/ExtraBrowserContextOptions/),
* 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
* - [Full list of Playwright `BrowserContextOptions`](https://playwright.dev/docs/api/class-browser#browser-new-context)
* - [Playwright website](https://playwright.dev/)
* - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
* - [`Ability`](https://serenity-js.org/api/core/class/Ability/)
* - [`Actor`](https://serenity-js.org/api/core/class/Actor/)
*
* @group Abilities
*/
export class BrowseTheWebWithPlaywright
extends BrowseTheWeb<playwright.Locator>
implements Initialisable, Discardable
{
static using(
browser: playwright.Browser,
browserContextOptions?: playwright.BrowserContextOptions,
extraBrowserContextOptions?: ExtraBrowserContextOptions
): BrowseTheWebWithPlaywright {
return new BrowseTheWebWithPlaywright(new PlaywrightBrowsingSessionWithBrowser(browser, browserContextOptions, extraBrowserContextOptions, playwright.selectors));
}
static usingPage(
page: playwright.Page,
extraBrowserContextOptions?: ExtraBrowserContextOptions
): BrowseTheWebWithPlaywright {
return new BrowseTheWebWithPlaywright(new PlaywrightBrowsingSessionWithPage(page, extraBrowserContextOptions, playwright.selectors));
}
/**
* Creates an ability to browse the web using an already-launched Electron application.
*
* Use this method when the Electron application lifecycle is managed externally,
* such as in Playwright Test where the app is launched per-worker.
*
* ## Example
*
* ```ts
* import { _electron as electron } from 'playwright';
* import { actorCalled } from '@serenity-js/core';
* import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright';
*
* const electronApp = await electron.launch({ args: ['main.js'] });
*
* const actor = actorCalled('Tester').whoCan(
* BrowseTheWebWithPlaywright.usingElectronApp(electronApp)
* );
*
* // After tests, close the app manually
* await electronApp.close();
* ```
*
* @param electronApp - An already-launched Playwright ElectronApplication instance
* @param extraBrowserContextOptions - Optional configuration for timeouts and navigation
*/
static usingElectronApp(
electronApp: playwright.ElectronApplication,
extraBrowserContextOptions?: ExtraBrowserContextOptions
): BrowseTheWebWithPlaywright {
return new BrowseTheWebWithPlaywright(
new PlaywrightBrowsingSessionWithElectron(
electronApp,
extraBrowserContextOptions ?? {},
playwright.selectors
)
);
}
/**
* Creates an ability to browse the web by launching and managing an Electron application.
*
* Use this method when you want Serenity/JS to manage the Electron application lifecycle.
* The app is launched on first use and closed when the ability is discarded.
*
* ## Example
*
* ```typescript
* import { actorCalled } from '@serenity-js/core';
* import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright';
*
* const actor = actorCalled('Tester').whoCan(
* BrowseTheWebWithPlaywright.launchingElectronApp({
* args: ['path/to/main.js'],
* cwd: 'path/to/app',
* })
* );
*
* // The app is automatically closed when the actor is dismissed
* ```
*
* @param launchOptions - Options for launching the Electron application
* @param extraBrowserContextOptions - Optional configuration for timeouts and navigation
*/
static launchingElectronApp(
launchOptions: ElectronLaunchOptions,
extraBrowserContextOptions?: ExtraBrowserContextOptions
): BrowseTheWebWithPlaywright {
return new BrowseTheWebWithPlaywright(
new SelfLaunchingPlaywrightBrowsingSessionWithElectron(
launchOptions,
extraBrowserContextOptions ?? {},
playwright.selectors
)
);
}
async initialise(): Promise<void> {
if (Initialisable.isInitialisable(this.session)) {
await this.session.initialise();
}
}
isInitialised(): boolean {
return Initialisable.isInitialisable(this.session)
? this.session.isInitialised()
: true;
}
/**
* Automatically closes any open [pages](https://serenity-js.org/api/web/class/Page/) when the [SceneFinishes](https://serenity-js.org/api/core-events/class/SceneFinishes/)
*
* For self-launching Electron sessions, also closes the Electron application.
*
* #### Learn more
* - [`PlaywrightBrowsingSession.closeAllPages`](https://serenity-js.org/api/playwright/class/PlaywrightBrowsingSession/#closeAllPages)
* - [`Discardable`](https://serenity-js.org/api/core/class/Discardable/)
*/
async discard(): Promise<void> {
if (Discardable.isDiscardable(this.session)) {
await this.session.discard();
}
}
}