First Steps into Automation: Building Your First Playwright Test

Microsoft

Jul 08, 2024

Web applications are becoming more complex, dynamic, and user-centric than ever before. They are also being deployed more frequently, often multiple times a day, thanks to continuous integration and delivery pipelines. To ensure that these applications deliver a reliable and consistent user experience, testing becomes a critical part of the development process.

However, traditional testing approaches that rely on manual testers or brittle scripts are not scalable or reliable enough to meet the demands of modern web development. We need a better way to automate testing of web applications, one that can handle complex user interactions, cross-browser compatibility, and fast feedback loops.

That's where Playwright comes in. Playwright is an open-source framework for end-to-end testing of web applications. It was released in 2020 by Microsoft and has been gaining popularity and adoption ever since. Playwright allows developers to write tests in .NET, Python or Java that can run across all modern browsers (Chromium, Firefox, WebKit) and emulated devices (desktop, mobile, tablet). Playwright also provides a rich set of features and tools to make testing easier, faster, and more resilient, such as auto-waiting, auto-retrying, test isolation, parallel execution, debugging, reporting, and more.

We recently released a new Microsoft Learn training module that walks you step-by-step through building your first end-to-end test with Playwright. In this article, we will create our first end-to-end test with Playwright using the module as our guide.

Check out the module here: Build Your first end-to-end test with Playwright - Training | Microsoft Learn

Getting Started with Playwright

Embarking on your Playwright adventure is straightforward. Before we can start writing tests with Playwright, we need to install and set up Playwright on our machine. In this article, we will be using TypeScript to write our tests, so we need to have node.js and npm installed. You can download and install Node.js here.

You can use the editor of your choice, but in this article, we will use Visual Studio Code. Visual Studio Code is a code editor and debugging tool. You can download and install Visual Studio Code from here.

Once we have Node.js and Visual Studio Code installed, we can go ahead to create a new project folder for our tests. We can use any name for our folder. In this article, we will use the name learn-playwright.

mkdir learn-playwright

When we have our project folder created, we would need to navigate into the new directory. The command below makes that happen.

cd learn-playwright

Now we can install Playwright and initialize our project. Playwright provides a convenient command to do both tasks at once.

npm init playwright@latest

When you run this command, you will be asked a few questions to configure our Playwright project

What language do you want to use for your tests? We can choose between JavaScript and TypeScript.
What is the name of the test directory? This is the folder where Playwright will look for our test files. We can use the default name, tests, or choose a different one.
Add a GitHub Action for automating tests? This is an optional feature that will create a file for us to run our tests on GitHub using GitHub Actions. We can choose yes or no, depending on whether we want to use GitHub Actions or not.
Install Playwright browsers? This is a required step that will download the browser binaries that Playwright needs to run our tests. We can choose the default option, true, or select specific browsers to download.

After answering these questions, we should see an output like the one here.

Initializing NPM project (npm init -y)…

Wrote to /learn-playwright/package.json:

{

  "name": "learn-playwright",
  "version": "1.0.0",*
  "description": "",*
  "main": "index.js",*
  "scripts": {*
    "test": "echo \"Error: no test specified\" && exit 1"*
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Installing Playwright Test (npm install --save-dev @playwright/test)…

added 4 packages, and audited 5 packages in 2s

found 0 vulnerabilities
Installing Types (npm install --save-dev @types/node)…

added 2 packages, and audited 7 packages in 580ms

found 0 vulnerabilities
Writing playwright.config.ts.
Writing .github/workflows/playwright.yml.
Writing tests/example.spec.ts.
Writing tests-examples/demo-todo-app.spec.ts.
Writing package.json.
Downloading browsers (npx playwright install)…
✔ Success! Created a Playwright Test project at /learn-playwright

Inside that directory, you can run several commands:

  npx playwright test
    Runs the end-to-end tests.

  npx playwright test --ui
    Starts the interactive UI mode.

  npx playwright test --project=chromium
    Runs the tests only on Desktop Chrome.

  npx playwright test example
    Runs the tests in a specific file.

  npx playwright test --debug
    Runs the tests in debug mode.

  npx playwright codegen
    Auto generate tests with Codegen.

We suggest that you begin by typing:

    npx playwright test

And check out the following files:
  - ./tests/example.spec.ts - Example end-to-end test
  - ./tests-examples/demo-todo-app.spec.ts - Demo Todo App end-to-end tests
  - ./playwright.config.ts - Playwright Test configuration

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

Happy hacking!

This tells us that a new npm project has been created with a package.json file, and that Playwright Test has been installed. Playwright Test is the built-in test runner for Playwright, which provides a simple and flexible way to write and run tests. It also tells us which files have been created for us. Next, it tells us that Playwright is downloading browsers. Playwright will download the latest version of the browsers that we can use to run our tests on. It uses browser binaries that are installed locally, so we don't need to have the browsers installed on our machine.

Once finished, we get a success message and a list of commands we can run to interact with the Playwright Test project. We also get some suggestions on which files to check out and where to find more information.

Running Tests with Playwright Test

Now that we have installed and set up Playwright, we can start writing and running tests with Playwright Test. Playwright Test is a test runner that provides a simple and flexible way to write and run tests. It has a minimal API that is easy to learn and use, and it supports various features and options to make testing easier, faster, and more resilient.

The example test script that Playwright created for us, tests/example.spec.ts, contains two simple tests that check the title and the get started link of the Playwright website. Let's take a look at the code in this unit: Understand Test Specification - Training | Microsoft Learn.

import { test, expect } from '@playwright/test';
test('has title', async ({ page }) => {
  await page.goto('https://playwright.dev/');

  // Expect a title "to contain" a substring.
  await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');

  // Click the get started link.
  await page.getByRole('link', { name: 'Get started' }).click();

  // Expects page to have a heading with the name of Installation.
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

The first line imports the test and expect objects from the Playwright Test module. The test object is used to define and run tests, and the expect object is used to make assertions.
The next two lines define the first test, which is called “has title”. The test function takes a name and a callback function as arguments. The callback function is an async function that takes a parameter called “{ page }”. This is a fixture that provides a page object, which represents a web page in the browser. We can use the page object to perform various actions and assertions on the page.
The first action we perform on the page is to navigate to the Playwright website, using the "page.goto" method. This method takes a URL as an argument and waits for the page to load. The next action we make on the page is to check the title, using the expect object and the “toHaveTitle” matcher. This matcher takes a regular expression as an argument and waits for the page title to match it.
The next four lines define the second test, called “get started link”. This test also navigates to the Playwright website, but then clicks on the “get started link”, using the “page.getByRole” locator and the click method. The “page.getByRole” is a locator that finds an element on the page by its accessible role. The click method performs a mouse click on the element. Next, we make an assertion to check the visibility of the heading with the name of Installation, using the expect object and the “toBeVisible" matcher. This matcher waits for the element to be visible on the page.

Now that we have walked through the code, let's run the tests and see the results. To run the code, we will use the command below.

npx playwright test

Running the code tells us that 6 tests were run using 5 workers. By default, Playwright runs tests in parallel. To do this it uses workers. The number of workers is determined by the number of CPU cores available. Playwright will use half of the available CPU cores.

But wait, why did we get 6 tests when we only defined 2 tests in our script? That's because Playwright runs each test on three different browser engines: Chromium, Firefox, and WebKit. This way, we can test our web application across all modern browsers with a single API. Playwright also supports device emulation for mobile testing.

Let's open the HTML report to see more details about the test run. To do that, we can run the command below in the terminal.

npx playwright show-report

This command will open a browser window with the HTML report, which looks like this:

The report gives us the following insights:

We have 2 test cases ("has title", "get started link")
We ran each test across 3 browser engines (chromium, firefox, webkit)
The test cases were defined in the example.spec.ts file
The test run took 4.0s with all 6 tests passing (none skipped)

Clicking on a particular row gives us a detailed view of that test case. For example, if we click on the first one, we get the following details:

The test is called "has title"
The file name is example.spec.ts and the line number is 3
This test case was run on Chromium
The "Before Hooks" ran first. This launches the browser and sets the browser and page context (fixtures) for test isolation.
The Test "Action" on line 4 ran next. This resulted in a navigation to a specific page.
Then the Test "Assertion" on line 7 executes. This validates that the page has a specific title.
The "After Hooks" run last. They take any context cleanup actions needed.
This test case took "424 ms" to complete.

That's it for running the example test.

Conclusion

In this article, you learned how to write and run your first Playwright test using TypeScript. You saw how Playwright lets you test your web application across different browsers with a single API, and also learned about the basic concepts of Playwright, such as fixtures, locators, matchers, and workers.

If you want to learn more about Playwright and how to use it for end-to-end testing, check out the Microsoft Learn module - Build Your first end-to-end test with Playwright - Training | Microsoft Learn. get started and generate your first test.