# Introduction to Playwright
Course: [Playwright](https://www.devtutorials.ai/learn/playwright) · Section: Playwright Foundations
Source: https://www.devtutorials.ai/learn/playwright/foundations/introduction-to-playwright
> 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.
Your test lists the steps. Playwright sends each one to the browser. At the end, you get a result.
### 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.
**Test** = code that checks your app works. A test **passes** when every check is true. It **fails** when one check is false or a step cannot finish.
**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.
From a Chrome-only tool to a full testing toolkit.
**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.
WebKit is why many teams pick Playwright. You can check Safari-like behaviour on Windows or Linux, with no Mac.
**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.
| Language | Package | Test runner |
|---|---|---|
| JavaScript and TypeScript | `@playwright/test` (npm) | Playwright Test (built in) |
| Python | `playwright` (pip) | pytest, with `pytest-playwright` |
| Java | `com.microsoft.playwright` (Maven) | JUnit or TestNG |
| .NET (C#) | `Microsoft.Playwright` (NuGet) | MSTest, NUnit or xUnit |
- The ideas are the same in every language. Only the spelling changes.
- Here is the same check in Python, for comparison:
```python
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.
Pick **TypeScript** or **JavaScript** in the top bar. Every code box in this course switches. TypeScript is the default for new Playwright projects.
**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.
Messages travel both ways on one open connection. That is why Playwright is fast and hears every page event.
### 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.
You do not need to learn CDP to use Playwright. It is useful to know the name, because error messages and advanced tools sometimes mention it. **Playwright Library and Advanced Browser Control** shows the rare cases where you use it directly.
### 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.
The button fades in and slides into place. Playwright waits until all four checks pass, then clicks.
- 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.
A fixed sleep guesses. On a slow day the guess is wrong. Auto-waiting checks again and again, and moves on as soon as the page is ready.
Do not add `page.waitForTimeout()` to make a test pass. A fixed sleep is too short on a slow computer and wastes time on a fast one. Let Playwright's auto-waiting do the job. **Actions and Auto-Waiting** covers every check in detail.
**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.
| Package | What it gives you | Use it for |
|---|---|---|
| `@playwright/test` | Test runner, `test`, `expect`, fixtures, reports | Writing tests (most people) |
| `playwright` | Browser control API, and downloads browsers | Scripts that are not tests |
| `playwright-core` | Browser control API only, no browser download | Using a browser you already have |
- For testing, install `@playwright/test`. It already includes the browser control API.
- Every test file starts by importing `test` and `expect` from it:
```ts
import { test, expect } from '@playwright/test';
```
Do not import `test` from `playwright`. That package has no test runner, so `test` and `expect` do not exist there. Import them 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
| Mistake | What happens | Fix |
|---|---|---|
| Adding `waitForTimeout(3000)` before a click | The test is slow, and still fails on a slow day | Remove it. Actions and `expect()` wait by themselves |
| Expecting one test to see data from another | The second test fails, because each test gets a fresh context | Make every test set up what it needs |
| Importing `test` from `playwright` | `test` is undefined and nothing runs | Import `test` and `expect` from `@playwright/test` |
| Testing only in Chromium | Safari and Firefox users meet bugs you never saw | Add Firefox and WebKit projects |
| Thinking a failing test is broken | You delete a test that found a real bug | Read Locator, Expected and Received first |
## 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**