@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
205 lines • 10.1 kB
JavaScript
;
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
var desc = Object.getOwnPropertyDescriptor(m, k);
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
desc = { enumerable: true, get: function() { return m[k]; } };
}
Object.defineProperty(o, k2, desc);
}) : (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
o[k2] = m[k];
}));
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
Object.defineProperty(o, "default", { enumerable: true, value: v });
}) : function(o, v) {
o["default"] = v;
});
var __importStar = (this && this.__importStar) || (function () {
var ownKeys = function(o) {
ownKeys = Object.getOwnPropertyNames || function (o) {
var ar = [];
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
return ar;
};
return ownKeys(o);
};
return function (mod) {
if (mod && mod.__esModule) return mod;
var result = {};
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
__setModuleDefault(result, mod);
return result;
};
})();
Object.defineProperty(exports, "__esModule", { value: true });
exports.BrowseTheWebWithPlaywright = void 0;
const web_1 = require("@serenity-js/web");
const playwright = __importStar(require("playwright-core"));
const models_1 = require("../models");
/**
* 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
*/
class BrowseTheWebWithPlaywright extends web_1.BrowseTheWeb {
static using(browser, browserContextOptions, extraBrowserContextOptions) {
return new BrowseTheWebWithPlaywright(new models_1.PlaywrightBrowsingSessionWithBrowser(browser, browserContextOptions, extraBrowserContextOptions, playwright.selectors));
}
static usingPage(page, extraBrowserContextOptions) {
return new BrowseTheWebWithPlaywright(new models_1.PlaywrightBrowsingSessionWithPage(page, extraBrowserContextOptions, playwright.selectors));
}
/**
* 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/)
*
* #### Learn more
* - [`PlaywrightBrowsingSession.closeAllPages`](https://serenity-js.org/api/playwright/class/PlaywrightBrowsingSession/#closeAllPages)
* - [`Discardable`](https://serenity-js.org/api/core/interface/Discardable/)
*/
async discard() {
await this.session.closeAllPages();
}
}
exports.BrowseTheWebWithPlaywright = BrowseTheWebWithPlaywright;
//# sourceMappingURL=BrowseTheWebWithPlaywright.js.map