Introduction to Playwright

By Syncfusion®, Inc. · Last updated November 13, 2026

What Playwright is and why it was made, its history and features, the browsers, languages and platforms it supports, how it works (architecture, browser contexts, the protocol, auto-waiting), its tools and its three npm packages.

Playwright Introduction

• Playwright is a free tool that controls a web browser with code.
• You use it to test websites. A test opens a page, clicks and types like a person, then checks the result.
• It works in Chrome, Edge, Firefox and Safari's engine.
• In this lesson, you will learn what Playwright is, how it works and which tools it has.

Simple lesson: Playwright is a robot user that tests your website for you.

A Real-World Example

• Priya builds a to-do list app.
• Every time she changes the code, she opens the app, types a task and presses Enter.
• Then she checks that the task appears and the counter says 1 item left.
• This takes two minutes. She does it ten times a day. Sometimes she forgets a step.
• With Playwright, she writes these steps once as a test. The test runs in about one second, every time, in every browser.

The test below does exactly what Priya does by hand. It uses TodoMVC, the practice app the Playwright team uses in its own docs. Press ▶ Run tests, then open the Browser and Steps tabs.

• What happened: the test opened the app, typed Buy milk, pressed Enter and checked two things.
• Both checks passed, so the terminal says 1 passed.
• Do not worry about every word yet. Your First Playwright Test explains each line.

What You Will Learn

1. What Playwright is and what an end-to-end test is.
2. Why Playwright was created, and a short history.
3. Its main features.
4. The browsers, languages and platforms it supports.
5. How it works: architecture, browser contexts, the protocol and auto-waiting.
6. The tools in the Playwright family.
7. The three npm packages, and which one you need.

What Is Playwright?

• Playwright = an open-source tool from Microsoft for browser automation and end-to-end testing.
• Browser automation = code that drives a browser: open pages, click, type, read text.
• End-to-end test (E2E test) = a test that uses the whole app, from the screen down to the server, like a real user.
• Open source = the code is public and free to use. Playwright uses the Apache 2.0 license.
• Playwright starts a browser, sends it commands, and reports what passed or failed.

Why Test in a Real Browser?

• Users do not read your code. They use your site in a browser.
• A real browser runs your HTML, CSS and JavaScript together, like users see them.
• So an E2E test catches problems that small code tests miss: a button hidden behind a banner, a broken link, a form that never sends.

Simple lesson: Playwright drives a real browser like a person, and tells you what broke.

Why Playwright Was Created

• Testing in browsers used to be painful. Testers had three big problems.
• Flaky tests: a test passed once and failed the next time, with no code change. Usually the test clicked before the page was ready.
• One browser only: many tools worked well in Chrome only. Safari and Firefox bugs reached users.
• Slow tests: starting a new browser for every test took seconds.
• Playwright was built to fix these three problems. It waits for the page by itself, it drives three browser engines with one API, and it gives every test a fresh, fast browser context.

Simple lesson: Playwright was made to make browser tests reliable, fast and cross-browser.

History of Playwright

• In 2017, a team at Google built Puppeteer, a tool that controls Chrome.
• Several people from that team moved to Microsoft and started Playwright.
• The first public version came out in January 2020. Version 1.0 followed in May 2020.
• Python, Java and .NET versions came next, so more teams could use it.
• In 2021, Playwright got its own test runner, Playwright Test, with the Trace Viewer.
• In 2023, UI Mode arrived for watching and fixing tests.
• In 2025, Playwright added tools for AI assistants: Playwright MCP and the Test Agents.
• Today, a new version comes out about once a month.

Simple lesson: Playwright grew from Puppeteer's ideas into Microsoft's full browser testing toolkit.

Features of Playwright

• Cross-browser: one test runs in Chromium, Firefox and WebKit.
• Auto-waiting: actions wait until an element is ready. You do not add sleeps.
• Web-first assertions: checks like toHaveText() keep retrying until they pass or time runs out.
• Isolation: every test gets a clean browser context. Tests do not affect each other.
• Parallel runs: many tests run at the same time to save time.
• Strong locators: find elements the way users see them, by role, label or text.
• Tools: Codegen, UI Mode, Trace Viewer and a VS Code extension.
• More than clicks: network mocking, API tests, screenshots, mobile emulation and accessibility checks.

One Test, Three Browsers

• In a real project, the config file lists projects. Each project is one browser.
• Then npx playwright test runs every test once per project.
• Run this test. The report shows it three times, once for each browser.
• In this lab, all three rows run in your own browser. A real project starts real Chromium, Firefox and WebKit.

• Look at the [chromium], [firefox] and [webkit] labels in the terminal. Playwright Configuration shows how to set up projects.

Simple lesson: Playwright gives you reliable waits, clean tests and many browsers out of the box.

Supported Browsers

• Playwright drives three browser engines.
• Browser engine = the part of a browser that reads HTML and CSS and draws the page.
• Chromium powers Google Chrome and Microsoft Edge.
• Firefox is Mozilla's browser.
• WebKit powers Apple Safari.
• Playwright downloads its own tested build of each engine when you install it.

Simple lesson: three engines, Chromium, Firefox and WebKit, cover almost every browser your users have.

Supported Languages

• You can write Playwright tests in four languages.

• The ideas are the same in every language. Only the spelling changes.
• Here is the same check in Python, for comparison:

expect(page.get_by_test_id("todo-title")).to_have_text("Buy milk")

• This course uses TypeScript and JavaScript, because the Node.js version has the most features. The test runner, UI Mode and Test Agents are all built for it.

Simple lesson: four languages, one set of ideas. This course teaches the TypeScript and JavaScript version.

Supported Platforms

• Playwright runs on the three big desktop systems.
• Windows: Windows 11 and later, Windows Server 2019 and later, or WSL.
• macOS: macOS 14 (Sonoma) and later.
• Linux: Debian 12 or 13, and Ubuntu 22.04, 24.04 or 26.04.
• It also runs on CI servers and in Docker. CI/CD and Scaling shows how.
• These versions change over time. Always check the system requirements in the docs.

Simple lesson: Playwright runs on Windows, macOS and Linux, on your laptop and on CI.

How Playwright Works

Playwright Architecture

• Your test runs in Node.js, not inside the browser.
• Playwright opens one connection to the browser and keeps it open.
• It sends small messages over that connection: "go to this page", "click this button".
• The browser sends messages back: "done", "page loaded", "a request was sent".
• Chromium speaks the Chrome DevTools Protocol (CDP). For Firefox and WebKit, Playwright uses its own builds that speak a similar protocol.

Browser Contexts and Pages

• Playwright organizes the browser in three levels.
• Browser = one running browser program.
• Browser context = a fresh, private profile inside that browser, like a new incognito window. It has its own cookies and storage.
• Page = one tab inside a context.
• Making a new context takes milliseconds. Starting a browser takes much longer.
• So Playwright starts the browser once, and gives every test its own new context.

• Test this yourself. The first test adds a task. The second test opens the same app.
• Does the second test see the task from the first one? Run it and look at the Steps tab.

• What happened: both tests passed. The second test saw an empty list.
• Each test had its own context, so nothing leaked from the first test.
• Browser Contexts, Pages, and Emulation shows how to open several contexts in one test, for example a buyer and a seller.

The Playwright Protocol

• Protocol = an agreed set of messages two programs use to talk.
• Older tools often send a new web request for each command, and then ask again and again: "is it ready yet?"
• Playwright keeps one connection open. The browser tells Playwright when things happen.
• So Playwright knows the moment a page loads, a button appears or a request finishes.
• You never write protocol messages yourself. Playwright's API does it for you.

Auto-Waiting Overview

• Web pages load in pieces. A button may appear half a second after the page.
• Auto-waiting = before an action, Playwright waits until the element is ready.
• For a click, Playwright checks that the element is visible, stable (not moving), enabled and receives events (nothing covers it).
• When every check passes, it clicks. If time runs out, the test fails with a clear message.

• Assertions wait too. expect(...).toHaveText() keeps checking until the text matches, up to 5 seconds by default.
• On the practice shop page below, the order is confirmed 1.2 seconds after the click. There is no sleep in the test. Run it.

• What happened: the status said "Placing your order…" first. The assertion kept retrying. It passed when the text changed.
• Look at the time in the terminal. The test took a bit more than one second, the time the page really needed.

Simple lesson: Playwright talks to the browser on one open line, gives each test a clean context, and waits for the page so you do not have to.

The Playwright Ecosystem

• Playwright is a family of tools. Click each one to see what it does.

Playwright Test Runner

• @playwright/test finds your test files, runs them in parallel in each browser, retries if you ask, and writes a report.
• You will use it in almost every lesson.

Playwright Library

• The library is the browser control part on its own, with no test runner.
• You use it in scripts: take screenshots, save PDFs, fill a form every morning.

Codegen

• npx playwright codegen opens a browser. As you click, it writes the test code for you.
• It picks good locators. You still clean up the code and add checks. Your First Playwright Test shows how.

UI Mode and Trace Viewer

• UI Mode is a window to run tests, watch each step and jump back in time.
• Trace Viewer replays a finished run: actions, page snapshots, network calls and console logs.
• Debugging and Tracing teaches both.

VS Code Extension

• The Playwright Test for VS Code extension adds run and debug buttons next to each test.
• It can also pick a locator when you click on the page.

Test Agents, MCP and CLI

• These tools let AI assistants work with Playwright.
• Test Agents: a planner, a generator and a healer that plan, write and fix tests.
• Playwright MCP: lets an AI assistant drive a real browser.
• Playwright CLI (playwright-cli): browser commands made for AI coding agents.
• AI-Assisted Testing with Agents, MCP, and CLI covers them. Learn the basics first, so you can judge what an AI writes.

Simple lesson: the test runner is the heart. The other tools help you write, watch and fix tests.

Playwright Packages

• On npm, Playwright comes in three packages. Each one holds the one below it.

• For testing, install @playwright/test. It already includes the browser control API.
• Every test file starts by importing test and expect from it:

import { test, expect } from '@playwright/test';

Simple lesson: for tests, you need @playwright/test. It includes everything else.

Reading a Failing Test

• A test that fails is not bad news. It tells you exactly what broke.
• The test below has a mistake on purpose. Run it, open the Terminal tab and read the error.

• Locator tells you which element Playwright checked: the level 1 heading.
• Expected is what the test wanted: "Todos".
• Received is what the page had: "todos", with a small t.
• toHaveText() with a string is case-sensitive. Change 'Todos' to 'todos' and run it again.
• The test waited 5 seconds before it failed. It kept retrying, in case the text changed.

Simple lesson: read Locator, Expected and Received. They tell you what went wrong.

Try It in Your Project

• These steps take the lesson from the lab to your own app.
• Pick one important flow in your app, like log in or search, and write down its steps as a user would.
• List which browsers your users really use. That decides your projects later.
• Bookmark the Playwright release notes. You will update often.

Simple lesson: use one idea from this lesson on your own app this week.

TL;DR

• Playwright is a free Microsoft tool that drives real browsers for end-to-end tests.
• It was built to fix flaky, slow, one-browser tests.
• It supports Chromium, Firefox and WebKit, four languages, and Windows, macOS and Linux.
• Your test runs in Node.js and talks to the browser over one open connection.
• Each test gets its own browser context, so tests never share state.
• Actions and assertions wait automatically. Do not add sleeps.
• For tests, install and import from @playwright/test.

Common mistakes

Check Yourself

Exercises

What to Remember

• Playwright drives Chromium, Firefox and WebKit to test sites like a real user.
• Every test gets a clean browser context.
• Actions and assertions wait by themselves. Never add fixed sleeps.
• Read Locator, Expected and Received when a test fails.
• For tests, use @playwright/test.

Next: Installation and Project Setup