DEV Community

Cover image for #001 | Getting Started With Playwright
Nitya Narasimhan for Microsoft Azure

Posted on • Originally published at nitya.github.io on

#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.

#playwright

Playwright is an open-source framework for Web Testing and Automation. It enables reliable end-to-end testing for modern web apps across browsers and platforms, using one API! Playwright supports resilient testing (with features like auto-wait, web-first assertions and tracing) with powerful tooling for authoring, debugging and profiling your end-to-end tests!

🔖 | Today's Resources


🎯 | 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 2: - Understand Playwright testing fundamentals and learn how to write more complex test scripts. This includes:

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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');
});
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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:
    ...
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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)

Enter fullscreen mode Exit fullscreen mode

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'] },
    },
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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...]
Enter fullscreen mode Exit fullscreen mode

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! 🎭
Enter fullscreen mode Exit fullscreen mode

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:

Discussion (2)

Collapse
nmhummel profile image
Natalie Hummel

So glad I found you thru Twitter. I am beginning with Playwright this week for my job-- first tech job ever-- and am excited to have someone like you to follow along with.

Collapse
nitya profile image
Nitya Narasimhan Author

Thank you so much and definitely leave me questions or reach out here (or via Twitter @nitya ) if you have comments or would love to see specific features covered in more detail. I am finding it so much fun to explore..

And do let me know how you are using Playwright in your work!! Would be great to understand use cases or challenges you face for end to end testing.