@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
161 lines (128 loc) ā¢ 8.28 kB
Markdown
# Serenity/JS
[](https://www.linkedin.com/company/serenity-js)
[](https://www.youtube.com/@serenity-js)
[](https://matrix.to/#/#serenity-js:gitter.im)
[](https://github.com/sponsors/serenity-js)
[Serenity/JS](https://serenity-js.org) is an innovative open-source framework designed to make acceptance and regression testing
of complex software systems faster, more collaborative and easier to scale.
āļø Get started with Serenity/JS!
- [Serenity/JS web testing tutorial](https://serenity-js.org/handbook/web-testing/your-first-web-scenario)
- [Serenity/JS + Playwright Test deep dive](https://serenity-js.org/handbook/test-runners/playwright-test/)
- [Serenity/JS Handbook](https://serenity-js.org/handbook)
- [API documentation](https://serenity-js.org/api/)
- [Serenity/JS Project Templates](https://serenity-js.org/handbook/project-templates/)
š Join the Serenity/JS Community!
- Meet other Serenity/JS developers and maintainers on the [Serenity/JS Community chat channel](https://matrix.to/#/#serenity-js:gitter.im),
- Find answers to your Serenity/JS questions on the [Serenity/JS Forum](https://github.com/orgs/serenity-js/discussions/categories/how-do-i),
- Learn how to [contribute to Serenity/JS](https://serenity-js.org/community/contributing/),
- Support the project and gain access to [Serenity/JS Playbooks](https://github.com/serenity-js/playbooks) by becoming a [Serenity/JS GitHub Sponsor](https://github.com/sponsors/serenity-js)!
## Serenity/JS Playwright
[`@serenity-js/playwright`](https://serenity-js.org/api/playwright/) module is a [Screenplay Pattern](https://serenity-js.org/handbook/design/screenplay-pattern/)-style adapter
for [Playwright](https://playwright.dev/), that helps with testing web-based apps.
### Installation
To install this module, run the following command in your [Playwright project directory](https://playwright.dev/docs/intro):
```bash
npm install --save-dev @serenity-js/assertions @serenity-js/console-reporter @serenity-js/core @serenity-js/serenity-bdd @serenity-js/web @serenity-js/playwright
```
## Usage with `@playwright/test`
Follow the [Using Serenity/JS with Playwright Test guide](https://serenity-js.org/handbook/test-runners/playwright-test/)
## Usage with Cucumber
Follow the [Serenity/JS configuration guide for Cucumber](https://serenity-js.org/handbook/test-runners/cucumber/)
and review the [Serenity/JS Cucumber and Playwright Project Template](https://github.com/serenity-js/serenity-js-cucumber-playwright-template).
### Usage with Mocha
```typescript
import { Ensure, equals } from '@serenity-js/assertions'
import { actorCalled, Actor, Cast, configure, Duration } from '@serenity-js/core'
import { BrowseTheWebWithPlaywright, ExtraBrowserContextOptions } from '@serenity-js/playwright'
import { By, Navigate, PageElement, TakePhotosOfFailures, Text } from '@serenity-js/web'
import { describe, it, beforeAll, afterAll } from 'mocha'
import * as playwright from 'playwright'
// example Lean Page Object describing a widget we interact with in the test
class SerenityJSWebsite {
static header = () =>
PageElement.located(By.css('h1')) // selector to identify the interactable element
.describedAs('header') // description to be used in reports
}
// example Actors class, confgures Serenity/JS actors to use Playwright
class Actors implements Cast {
constructor(
private readonly browser: playwright.Browser,
private readonly contextOptions: playwright.BrowserContextOptions,
private readonly extraContextOptions: ExtraBrowserContextOptions,
) {
}
prepare(actor: Actor): Actor {
return actor.whoCan(
BrowseTheWebWithPlaywright.using(
this.browser,
this.contextOptions,
this.extraContextOptions
),
// ... add other abilities as needed, like CallAnApi or TakeNotes
)
}
}
describe('Serenity/JS', () => {
let browser: playwright.Browser
beforeAll(async () => {
// Start a single browser before all the tests,
// Serenity/JS will open new tabs
// and manage Playwright browser context as needed
browser = await playwright.chromium.launch({
headless: true
})
// Configure Serenity/JS providing your Actors
// and required "stage crew memebers" (a.k.a. reporting services)
configure({
actors: new Actors(browser, {
baseURL: `https://serenity-js.org`,
defaultNavigationTimeout: Duration.ofSeconds(2).inMilliseconds(),
defaultTimeout: Duration.ofMilliseconds(750).inMilliseconds(),
}),
crew: [
[ '@serenity-js/console-reporter', { theme: 'auto' } ],
[ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
[ '@serenity-js/web:Photographer', {
strategy: 'TakePhotosOfFailures',
// strategy: 'TakePhotosOfInteractions',
} ],
[ '@serenity-js/serenity-bdd', { specDirectory: 'spec' } ],
]
})
})
it('supports Playwright', async () => {
// actorCalled(name) instantiates or retrieves an existing actor identified by name
// Actors class configures the actors to use Playwright
await actorCalled('William')
.attemptsTo(
Navigate.to('https://serenity-js.org'),
Ensure.that(
Text.of(SerenityJSWebsite.header()),
equals('Next generation acceptance testing')
),
)
})
afterAll(async () => {
// Close the browser after all the tests are finished
if (browser) {
await browser.close()
}
})
})
```
Next steps:
- Add [`@serenity-js/mocha`](https://serenity-js.org/api/mocha/) adapter to produce the reports
- Learn about the [Screenplay Pattern](https://serenity-js.org/handbook/design/screenplay-pattern.html)
- Explore [`@serenity-js/web`](https://serenity-js.org/api/web) and [`@serenity-js/assertions`](https://serenity-js.org/api/assertions) APIs
## š£ Stay up to date
New features, tutorials, and demos are coming soon!
Follow [Serenity/JS on LinkedIn](https://www.linkedin.com/company/serenity-js),
subscribe to [Serenity/JS channel on YouTube](https://www.youtube.com/@serenity-js) and join the [Serenity/JS Community Chat](https://matrix.to/#/#serenity-js:gitter.im) to stay up to date!
Please also make sure to star āļø [Serenity/JS on GitHub](https://github.com/serenity-js/serenity-js) to help others discover the framework!
[](https://www.linkedin.com/company/serenity-js)
[](https://www.youtube.com/@serenity-js)
[](https://matrix.to/#/#serenity-js:gitter.im)
[](https://github.com/serenity-js/serenity-js)
## š Support Serenity/JS
If you appreciate all the effort that goes into making sophisticated tools easy to work with, please support our work and become a Serenity/JS GitHub Sponsor today!
[](https://github.com/sponsors/serenity-js)