The Screenplay Developer Hub

Welcome to the Screenplay developer hub. You'll find comprehensive guides and documentation to help you start working with Screenplay as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Getting Started with ScreenPlay

This page will help you get started with Screenplay

About ScreenPlay

ScreenPlay is a root cause analysis (RCA) enhancement tool for Puppeteer and Playwright.
We believe modern automation frameworks like Puppeteer, Playwright, and Selenium are pretty fast and useful, but maintaining and debugging tests can be sometimes difficult. ScreenPlay streamlines the debugging process, by adding root cause analysis features to Puppeteer or Playwright test runs. As part of the test runs, ScreenPlay displays a screenshot for each step, highlights the action taken, and saves it to a local drive. The screenshots can be easily viewed in succession on ScreenPlay’s UI, and can be used to demonstrate the test flow and easily identify where a test has failed.

ScreenPlay Node.js Installation

In order to use ScreenPlay, first install ScreenPlay’s Node.js package:
(You may also use the yarn equivalent commands)

npm install @testim/screenplay -D

Using Screenplay with standalone Node code (for custom scenarios, no test runner)

ScreenPlay can be used as a root cause analysis (RCA) enhancement tool to any Node code test by simply adding a few lines of code to your test (no need for a test runner). ScreenPlay will collect root cause analysis information, such as located elements, screenshots, console logs, and other Puppeteer calls automatically and display them in an easy-to-use viewer (as explained below):
For a working example, see our examples repository

const screenplay = require('@testim/screenplay');
 
screenplay.launch({ testName: "My screenplay test" }, async page => {
    // use the page object normally like you regularly would
 
    await page.goto('https://example.com');
    await page.click('a');
});

Using ScreenPlay with Jest

Integrating ScreenPlay with Jest requires minor config changes in Jest. Following the configuration, ScreenPlay will begin collecting root cause analysis information, such as located elements, screenshots, console logs, etc.
If you are not sure how your Jest is configured, see https://jestjs.io/docs/en/configuration.

For working puppeteer examples
For working playwright examples

📘

Note

ensure you have Puppeteer/Playwright integration that exposes browser & page globally.

For the following example, we assume you are using jest-puppeteer as preset.

jest.config.js

const puppeteerPreset = require('jest-puppeteer-preset/jest-preset.json');
const runId = Date.now().toString();

module.exports = {
    ...puppeteerPreset,
    reporters: [
        ['@testim/screenplay/src/jest/reporter/default', { runId }],
    ],
    setupFilesAfterEnv: ['expect-puppeteer', '@testim/screenplay/src/jest/forJestSetupFilesAfterEnv'],
    globals: {
        runId,
    },
};

For the following example, we assume you are using jest-playwright as preset.

jest.config.js

const playwrightPreset = require("jest-playwright-preset/jest-preset.json");

const runId = Date.now().toString();

module.exports = {
    ...playwrightPreset,
    testRunner: "jasmine2",
    reporters: [
        ['@testim/screenplay/src/jest/reporter/default', { runId }],
    ],
    setupFilesAfterEnv: [...playwrightPreset.setupFilesAfterEnv, '@testim/screenplay/src/jest/forJestSetupFilesAfterEnv'],
    globals: {
        runId,
    },
};

As you can see in the example, we add a ScreenPlay reporter and ScreenPlay setupFilesAfterEnv entry.
We also pass runId as a global Jest variable and as a parameter to the Jest reporter.
The value of runId should be unique for each Jest run.

Viewing ScreenPlay results / ScreenPlay CLI

📘

Note

It is recommended to install @testim/screenplay locally in your project, so npx will use the local version.

After running the test, ScreenPlay saves all of the test data in the .screenplay folder and the root cause analysis results can be accessed through the CLI and then viewed on a web browser.

To list the recent test runs:

npx screenplay ls

Example output:

screenplay-show-interactivescreenplay-show-interactive

To see the results of a specific test, copy the id and pass it to the npx screenplay show, as following:

npx screenplay show <result-id>

This will open your default browser with the ScreenPlay viewer that looks something like this:

screenplay-uiscreenplay-ui

You may also interactively select the test to show:

screenplay-show-interactivescreenplay-show-interactive

To see all of the ScreenPlay CLI possible options:

npx screenplay --help

CI Integration

It's possible to use ScreenPlay in your CI, similar to how you would use Puppeteer in your CI.
See our example projects with GitHub Actions:
https://github.com/testimio/screenplay-issues/blob/master/.github/workflows/screenplay-run-examples.yml.

To view the ScreenPlay CI results locally, you should download the artifacts folder, and use ScreenPlay CLI as explained above.

Updated 16 days ago

Getting Started with ScreenPlay


This page will help you get started with Screenplay

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.