#001 | Getting Started With Playwright

This post was originally published on the Learn Playwright blog. Reference the original post to get the most updated version of this content.

🔖 | Today's Resources

• Getting Started guide.
• Browser installation and management.
• Configuration options for Playwright Test.
• Command-line options for Playwright Test.
• Device Emulation and supported descriptors for configuration.

🎯 | Today's Objectives

Welcome to Day 1 of #30DaysOfPlaywright! Today's goal is to make progress on the Getting Started tutorial which should get us set up with the Playwright Test runner in our local development environment - and get us configured to do our first test run.

There's a lot covered in there, so I've decided to break this into multiple parts.

• Part 1: - Install the Playwright Test runner and validate setup by completing your first test run with the sample test script. This includes:

  • Installing Playwright Test - to use built-in test runner.
  • Running your first test - to explore headless and headed modes
  • Configuring test workflow - to support multi-browser testing
  • Understanding CLI options - to customize test runner execution

• Part 2: - Understand Playwright testing fundamentals and learn how to write more complex test scripts. This includes:
  • Writing assertions - to test if an expect-ed behavior holds true.
  • Using test fixtures - to set desired page/browser context for test run.
  • Using test hooks - to setup and tear down resources between tests.

We'll cover Part 1 today and dive deeper into the rest in subsequent posts.

1. Install Playwright Test

Playwright Test is written in Node and installed using NPM. Install the Playwright Test runner as follows:

$ npm i -D @playwright/test

The process is fairly straightforward once you have Node and NPM installed. (Hint: If you are installing Node for the first time, I recommend using the Node Version Manager to install and use different Node.js versions easily).

2. Install Browsers

By default, Playwright Test runs in headless mode (there is no visible browser graphical user interface during testing) - but it can be configured to run in headed mode using a command-line flag as we'll see later.

Each version of Playwright needs specific versions of browser binaries to operate. You can manage the browser install process to customize which binaries are installed locally (and where), or elect to not do fresh installs and use existing browser channels instead.

The command below installs all supported browser binaries by default.

$ npx playwright install

Browser binaries are installed in OS-specfic cache folders by default - it's useful to check that directory to see which binaries you currently have installed in your development environement. For example, here's my macOS device listing:

$ du -hs ~/Library/Caches/ms-playwright/*
343M    chromium-930007
345M    chromium-939194
199M    firefox-1297
200M    firefox-1304
213M    webkit-1564
211M    webkit-1578

3. Write & Run Your First Test!

The tutorial provides a simple First Test script that you can copy into a file. I chose to use the JavaScript version but you can find similar guidance for other languages in the Playwright documentation.

const { test, expect } = require('@playwright/test');

test('basic test', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  const title = page.locator('.navbar__inner .navbar__title');
  await expect(title).toHaveText('Playwright');
});

The test script is readable for the most part. You can tell that this test involves visiting the specified page (Playwright website), selecting the element matching given classes, and asserting that it contains the expected text: Playwright. We'll unpack the syntax and semantics of this script in our next post - for now, let's validate the execution workflow.

To run the test, save the script and execute the command below. The output shows a successful run in a single worker thread.

$npx playwright test  

Running 1 test using 1 worker

  ✓  test.spec.js:3:1 › basic test (961ms)


  1 passed (1s)

Want to see what happens if a test fails?

Let's change the script to make it expect a different text string (e.g., "Play wright" instead of "Playwright"). Run the test again. Output now shows a meaningful error (expected X, received Y) along with a call log (truncated for clarity) to help you debug the cause.

$ npx playwright test 

Running 1 test using 1 worker

  ✘  test.spec.js:3:1 › basic test (6s)


  1) test.spec.js:3:1 › basic test =================================================================

    Error: expect(received).toHaveText(expected)

    Expected string: "Play wright"
    Received string: "Playwright"

    Call log:
    ...

4. Run in Headed mode

The default Playwright test runner runs in headless mode - but what if you want to see the browser UI as the test runs? Just add a simple --headed flag:

$npx playwright test --headed

Running 1 test using 1 worker

  ✓  test.spec.js:3:1 › basic test (2s)


  1 passed (3s)

The output is similar - but if you watch closely, you should see a browser window pop-up briefly, then close immediately on completion of the test run.

5. Configure Test Runs

You might have noticed that headed mode uses Chromium by default. What if I want to run the test with a different browser (Firefox, WebKit)? Or, I want to do cross-browser testing using multiple browsers in the same run? This is where having Configuration files can help.

Here is the default configuration file provide in the getting started tutorial. The main thing to notice is that the file has multiple named projects, each providing custom configuration parameters alongside the global parameters (e.g., retries) that precede them.

// playwright.config.js
// @ts-check
const { devices } = require('@playwright/test');

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  use: {
    trace: 'on-first-retry',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
  ],
};

module.exports = config;

You can now run all project configurations in the same test run (e.g., cross-browser testing) using:

$ npx playwright test       
Using config at tests/playwright.config.js

Running 3 tests using 3 workers

  ✓  [chromium] › test.spec.js:3:1 › basic test (1s)
  ✓  [firefox] › test.spec.js:3:1 › basic test (2s)
  ✓  [webkit] › test.spec.js:3:1 › basic test (1s)

  3 passed (3s)

You can add multiple configurations for the same browser - for instance, I added the following as a fourth project to test against desktop and mobile targets. Re-running the test should give a successful outcome with 4 tests using 4 workers.

(Sidebar: Want to know supported device profiles and the default Browser type they are associated with for testing? Check out the source!)

    {
      name: 'Mobile Chrome',
      use: { ...devices['Pixel 5'] },
    },

You can also select a specific configuration (from project options) to test solo:

$ npx playwright test --project="Mobile Chrome"
Using config at tests/playwright.config.js

Running 1 test using 1 worker

  ✓  [Mobile Chrome] › test.spec.js:3:1 › basic test (1s)


  1 passed (1s)

When testing multiple configurations in the same run, the default behavior allocates one worker thread to each project (so 4 tests for 4 workers). You can change that with a commandline flag, allowing you to control the degree of parallelization of test execution.

$ npx playwright test --workers=2
tests/playwright.config.js

Running 4 tests using 2 workers

  ✓  [chromium] › test.spec.js:3:1 › basic test (1s)
  ✓  [firefox] › test.spec.js:3:1 › basic test (2s)
  ✓  [webkit] › test.spec.js:3:1 › basic test (1s)
  ✓  [Mobile Chrome] › test.spec.js:3:1 › basic test (893ms)


  4 passed (4s)

We'll explore more configuration options in a future blog post.

6. Explore Command Line Options

That covers the basics of creating and executing a Playwright test run with a single test script file. But the command line tool supports more versatile execution requirements as well.

Use the following command to view and explore available options

# $ npx playwright test --help
Usage: npx playwright test [options] [test-filter...]

These include the ability to run tests that match specified regular expressions (at command line), limit the number of retries, control the degree of parallelization (with worker count) or choose the type of reporter to use for outcomes.

We'll explore Command line examples in more depth in a future post.

7. Scaffold e2e tests for project

If you watched the Introduction to Playwright Test runner talk, you may recall seeing the npm init playwright command being used to scaffold out a complete end-to-end testing setup for a new project.

This uses the create-playwright package to support quickstarts with a single command that installs Playwright (and dependencies) and sets up basic testing and configuration files for end-to-end testing workflows. This is a good way to also initialize existing projects to use Playwright for testing. Here's a quick look at how this works for intializing a new "demo" project.

$ npm init playwright demo  

Getting started with writing end-to-end tests with Playwright:
Initializing project in 'demo'
✔ Do you want to use TypeScript or JavaScript? · JavaScript
✔ Where to put your end-to-end tests? · e2e
✔ Add a GitHub Actions workflow? (Y/n) · true
Initializing NPM project (npm init -y)…

...

We suggest that you begin by typing:

  cd demo
  npm run test:e2e

And check out the following files:
  - ./demo/e2e/example.spec.js - Example end-to-end test
  - ./demo/playwright.config.js - Playwright Test configuration

Visit https://playwright.dev/docs/intro for more information. ✨

Happy hacking! 🎭

Day 1: Review

If you made it this far, congratulations! Here's a checklist of tasks that you should have completed.

• [X] Installed Playwright Test package
• [X] Created simple test script.
• [X] Executed (headless) Playwright Test run - successfully.
• [X] Executed (headless) Playright Test run - with failure.
• [X] Created Configuration file (with mutliple project options)
• [X] Ran Playwright Test in headed mode.
• [X] Ran Playwright Test in headed mode - with multiple browsers.
• [X] Ran Playwright Test - with different worker counts.
• [X] Explore Playwright Test - commandline options
• [X] Scaffolded new project for Playright Test (end-to-end)

Day 2: Up Next

Tomorrow we'll unpack part 2 of the tutorial - which includes:

• Writing assertions - to test if an expect-ed behavior holds true.
• Using test fixtures - to create the right page/browser context for a test run.
• Using test hooks - to setup and tear down resources between tests.