Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

docs: Getting started revamp docs and images (#36987)

Debbie O'Brien1f2047f684dd
diff --git a/docs/src/ci-intro.md b/docs/src/ci-intro.md
index 2376cb6e4b..e49d0d76fc 100644
--- a/docs/src/ci-intro.md
+++ b/docs/src/ci-intro.md
@@ -6,7 +6,7 @@ title: "Setting up CI"
## Introduction
* langs: js
-Playwright tests can be run on any CI provider. This guide covers one way of running tests on GitHub using GitHub actions. If you would like to learn more, or how to configure other CI providers, check out our detailed [doc on Continuous Integration](./ci.md).
+Playwright tests can be run on any CI provider. This guide covers one way of running tests on GitHub using GitHub Actions. If you would like to learn more, or how to configure other CI providers, check out our detailed [doc on Continuous Integration](./ci.md).
#### You will learn
* langs: js
@@ -21,7 +21,7 @@ Playwright tests can be run on any CI provider. This guide covers one way of run
## Introduction
* langs: python, java, csharp
-Playwright tests can be run on any CI provider. In this section we will cover running tests on GitHub using GitHub actions. If you would like to see how to configure other CI providers check out our detailed doc on Continuous Integration.
+Playwright tests can be run on any CI provider. In this section we cover running tests on GitHub using GitHub Actions. If you would like to see how to configure other CI providers, check out our detailed doc on Continuous Integration.
#### You will learn
* langs: python, java, csharp
@@ -34,7 +34,7 @@ Playwright tests can be run on any CI provider. In this section we will cover ru
## Setting up GitHub Actions
* langs: js
-When [installing Playwright](./intro.md) using the [VS Code extension](./getting-started-vscode.md) or with `npm init playwright@latest` you are given the option to add a [GitHub Actions](https://docs.github.com/en/actions) workflow. This creates a `playwright.yml` file inside a `.github/workflows` folder containing everything you need so that your tests run on each push and pull request into the main/master branch. Here's how that file looks:
+When [installing Playwright](./intro.md) using the [VS Code extension](./getting-started-vscode.md) or with `npm init playwright@latest`, you are given the option to add a [GitHub Actions](https://docs.github.com/en/actions) workflow. This creates a `playwright.yml` file inside a `.github/workflows` folder containing everything you need so that your tests run on each push and pull request into the main/master branch. Here's how that file looks:
```yml js title=".github/workflows/playwright.yml"
name: Playwright Tests
@@ -80,7 +80,7 @@ To learn more about this, see ["Understanding GitHub Actions"](https://docs.gith
## Setting up GitHub Actions
* langs: python, java, csharp
-To add a [GitHub Actions](https://docs.github.com/en/actions) file first create `.github/workflows` folder and inside it add a `playwright.yml` file containing the example code below so that your tests will run on each push and pull request for the main/master branch.
+To add a [GitHub Actions](https://docs.github.com/en/actions) file, first create `.github/workflows` folder and inside it add a `playwright.yml` file containing the example code below so that your tests run on each push and pull request for the main/master branch.
```yml python title=".github/workflows/playwright.yml"
name: Playwright Tests
@@ -176,7 +176,7 @@ Looking at the list of steps in `jobs.test.steps`, you can see that the workflow
## Create a Repo and Push to GitHub
-Once you have your [GitHub actions workflow](#setting-up-github-actions) setup then all you need to do is [Create a repo on GitHub](https://docs.github.com/en/get-started/quickstart/create-a-repo) or push your code to an existing repository. Follow the instructions on GitHub and don't forget to [initialize a git repository](https://github.com/git-guides/git-init) using the `git init` command so you can [add](https://github.com/git-guides/git-add), [commit](https://github.com/git-guides/git-commit) and [push](https://github.com/git-guides/git-push) your code.
+Once you have your [GitHub Actions workflow](#setting-up-github-actions) setup, then all you need to do is [Create a repo on GitHub](https://docs.github.com/en/get-started/quickstart/create-a-repo) or push your code to an existing repository. Follow the instructions on GitHub and don't forget to [initialize a git repository](https://github.com/git-guides/git-init) using the `git init` command so you can [add](https://github.com/git-guides/git-add), [commit](https://github.com/git-guides/git-commit), and [push](https://github.com/git-guides/git-push) your code.
######
* langs: js, java, python
@@ -191,7 +191,7 @@ Once you have your [GitHub actions workflow](#setting-up-github-actions) setup t
## Opening the Workflows
-Click on the **Actions** tab to see the workflows. Here you will see if your tests have passed or failed.
+Click on the **Actions** tab to see the workflows. Here you see if your tests have passed or failed.
######
* langs: js, python, java
@@ -210,7 +210,7 @@ On Pull Requests you can also click on the **Details** link in the [PR status ch
## Viewing Test Logs
-Clicking on the workflow run will show you the all the actions that GitHub performed and clicking on **Run Playwright tests** will show the error messages, what was expected and what was received as well as the call log.
+Clicking on the workflow run shows you all the actions that GitHub performed and clicking on **Run Playwright tests** shows the error messages, what was expected and what was received as well as the call log.
######
* langs: js, python, java
@@ -226,19 +226,19 @@ Clicking on the workflow run will show you the all the actions that GitHub perfo
## HTML Report
* langs: js
-The HTML Report shows you a full report of your tests. You can filter the report by browsers, passed tests, failed tests, skipped tests and flaky tests.
+The HTML Report shows you a full report of your tests. You can filter the report by browsers, passed tests, failed tests, skipped tests, and flaky tests.
### Downloading the HTML Report
* langs: js
-In the Artifacts section click on the **playwright-report** to download your report in the format of a zip file.
+In the Artifacts section, click on the **playwright-report** to download your report in the format of a zip file.
<img width="972" alt="Downloading the HTML Report" src="https://user-images.githubusercontent.com/13063165/183437023-524f1803-84e4-4862-9ce3-1d55af0e023e.png" />
### Viewing the HTML Report
* langs: js
-Locally opening the report will not work as expected as you need a web server in order for everything to work correctly. First, extract the zip, preferably in a folder that already has Playwright installed. Using the command line change into the directory where the report is and use `npx playwright show-report` followed by the name of the extracted folder. This will serve up the report and enable you to view it in your browser.
+Locally opening the report does not work as expected as you need a web server for everything to work correctly. First, extract the zip, preferably in a folder that already has Playwright installed. Using the command line, change into the directory where the report is and use `npx playwright show-report` followed by the name of the extracted folder. This serves up the report and enables you to view it in your browser.
```bash
@@ -247,7 +247,7 @@ npx playwright show-report name-of-my-extracted-playwright-report
![viewing the HTML report](https://github.com/microsoft/playwright/assets/13063165/c5f60e56-fb75-4a2d-a4b6-054b8c5d69c1)
-To learn more about reports check out our detailed guide on [HTML Reporter](/test-reporters.md#html-reporter)
+To learn more about reports, check out our detailed guide on [HTML Reporter](/test-reporters.md#html-reporter)
## Viewing the Trace
* langs: js
@@ -261,7 +261,7 @@ Once you have served the report using `npx playwright show-report`, click on the
[trace.playwright.dev](https://trace.playwright.dev) is a statically hosted variant of the Trace Viewer. You can upload trace files using drag and drop.
-![playwright trace viewer](https://github.com/microsoft/playwright/assets/13063165/6d5885dc-d511-4c20-b728-040a7ef6cea4)
+![playwright trace viewer](./images/getting-started/trace-viewer-failed-test.webp)
## Viewing the Trace
* langs: csharp
@@ -271,7 +271,7 @@ You can upload Traces which get created on your CI like GitHub Actions as artifa
######
* langs: csharp
-![playwright trace viewer](https://github.com/microsoft/playwright/assets/13063165/84150084-5019-470a-8449-b61d206bfbb0)
+![playwright trace viewer](./images/getting-started/trace-viewer-failed-test.webp)
## Publishing report on the web
* langs: js
@@ -319,14 +319,14 @@ This step will not work for pull requests created from a forked repository becau
* langs: js
Artifacts like trace files, HTML reports or even the console logs contain information about your test execution.
-They can contain sensitive data like user credentials for a test user, access tokens to a staging backend, testing source code or sometimes even your application source code. Treat these files just as careful as you treat that sensitive data.
+They can contain sensitive data like user credentials for a test user, access tokens to a staging backend, testing source code, or sometimes even your application source code. Treat these files just as carefully as you treat that sensitive data.
If you upload reports and traces as part of your CI workflow, make sure that you only upload them to trusted artifact stores, or that you encrypt the files before upload. The same is true for sharing artifacts with team members: Use a trusted file share or encrypt the files before sharing.
## Properly handling Secrets
* langs: python, java, csharp
Artifacts like trace files or console logs contain information about your test execution.
-They can contain sensitive data like user credentials for a test user, access tokens to a staging backend, testing source code or sometimes even your application source code. Treat these files just as careful as you treat that sensitive data.
+They can contain sensitive data like user credentials for a test user, access tokens to a staging backend, testing source code, or sometimes even your application source code. Treat these files just as carefully as you treat that sensitive data.
If you upload reports and traces as part of your CI workflow, make sure that you only upload them to trusted artifact stores, or that you encrypt the files before upload. The same is true for sharing artifacts with team members: Use a trusted file share or encrypt the files before sharing.
## What's Next
diff --git a/docs/src/codegen-intro.md b/docs/src/codegen-intro.md
index fe5457c212..0ee74d42b4 100644
--- a/docs/src/codegen-intro.md
+++ b/docs/src/codegen-intro.md
@@ -5,7 +5,7 @@ title: "Generating tests"
## Introduction
-Playwright comes with the ability to generate tests out of the box and is a great way to quickly get started with testing. It will open two windows, a browser window where you interact with the website you wish to test and the Playwright Inspector window where you can record your tests, copy the tests, clear your tests as well as change the language of your tests.
+Playwright can generate tests automatically, providing a quick way to get started with testing. Codegen opens a browser window for interaction and the Playwright Inspector for recording, copying, and managing your generated tests.
**You will learn**
@@ -14,7 +14,7 @@ Playwright comes with the ability to generate tests out of the box and is a grea
## Running Codegen
-Use the `codegen` command to run the test generator followed by the URL of the website you want to generate tests for. The URL is optional and you can always run the command without it and then add the URL directly into the browser window instead.
+Use the `codegen` command to run the test generator followed by the URL of the website you want to generate tests for. The URL is optional and can be added directly in the browser window if omitted.
```bash js
npx playwright codegen demo.playwright.dev/todomvc
@@ -34,11 +34,11 @@ pwsh bin/Debug/net8.0/playwright.ps1 codegen demo.playwright.dev/todomvc
### Recording a test
-Run `codegen` and perform actions in the browser. Playwright will generate the code for the user interactions. `Codegen` will look at the rendered page and figure out the recommended locator, prioritizing role, text and test id locators. If the generator identifies multiple elements matching the locator, it will improve the locator to make it resilient and uniquely identify the target element, therefore eliminating and reducing test(s) failing and flaking due to locators.
+Run `codegen` and perform actions in the browser. Playwright generates code for your interactions automatically. Codegen analyzes the rendered page and recommends the best locator, prioritizing role, text, and test id locators. When multiple elements match a locator, the generator improves it to uniquely identify the target element, reducing test failures and flakiness.
With the test generator you can record:
-* Actions like click or fill by simply interacting with the page
-* Assertions by clicking on one of the icons in the toolbar and then clicking on an element on the page to assert against. You can choose:
+* Actions like click or fill by interacting with the page
+* Assertions by clicking a toolbar icon, then clicking a page element to assert against. You can choose:
* `'assert visibility'` to assert that an element is visible
* `'assert text'` to assert that an element contains specific text
* `'assert value'` to assert that an element has a specific value
@@ -46,65 +46,65 @@ With the test generator you can record:
######
* langs: js
-![Recording a test](https://github.com/microsoft/playwright/assets/13063165/34a79ea1-639e-4cb3-8115-bfdc78e3d34d)
+![Recording a test](./images/getting-started/record-test-js.webp)
######
* langs: java
-![recording a test](https://github.com/microsoft/playwright/assets/13063165/ec9c4071-4af8-4ae7-8b36-aebcc29bdbbb)
+![recording a test](./images/getting-started/record-test-java.webp)
######
* langs: python
-![recording a test](https://github.com/microsoft/playwright/assets/13063165/9751b609-6e4c-486b-a961-f86f177b1d58)
+![recording a test](./images/getting-started/record-test-python.webp)
######
* langs: csharp
-![recording a test](https://github.com/microsoft/playwright/assets/13063165/53bdfb6f-d462-4ce0-ab95-0619faaebf1e)
+![recording a test](./images/getting-started/record-test-csharp.webp)
######
* langs: js, java, python, csharp
-When you have finished interacting with the page, press the `'record'` button to stop the recording and use the `'copy'` button to copy the generated code to your editor.
+When you finish interacting with the page, press the `'record'` button to stop recording and use the `'copy'` button to copy the generated code to your editor.
-Use the `'clear'` button to clear the code to start recording again. Once finished close the Playwright inspector window or stop the terminal command.
+Use the `'clear'` button to clear the code and start recording again. Once finished, close the Playwright Inspector window or stop the terminal command.
-To learn more about generating tests check out or detailed guide on [Codegen](./codegen.md).
+To learn more about generating tests, check out our detailed guide on [Codegen](./codegen.md).
### Generating locators
You can generate [locators](/locators.md) with the test generator.
-* Press the `'Record'` button to stop the recording and the `'Pick Locator'` button will appear.
-* Click on the `'Pick Locator'` button and then hover over elements in the browser window to see the locator highlighted underneath each element.
-* To choose a locator click on the element you would like to locate and the code for that locator will appear in the locator playground next to the Pick Locator button.
-* You can then edit the locator in the locator playground to fine tune it and see the matching element highlighted in the browser window.
-* Use the copy button to copy the locator and paste it into your code.
+* Press the `'Record'` button to stop recording and the `'Pick Locator'` button will appear
+* Click the `'Pick Locator'` button and hover over elements in the browser window to see the locator highlighted underneath each element
+* Click the element you want to locate and the code for that locator will appear in the locator playground next to the Pick Locator button
+* Edit the locator in the locator playground to fine-tune it and see the matching element highlighted in the browser window
+* Use the copy button to copy the locator and paste it into your code
######
* langs: js
-![picking a locator](https://github.com/microsoft/playwright/assets/13063165/2c8a12e2-4e98-4fdd-af92-1d73ae696d86)
+![picking a locator](./images/getting-started/pick-locator-js.webp)
######
* langs: java
-![picking a locator](https://github.com/microsoft/playwright/assets/13063165/733b48fd-5edf-4150-93f0-018adc52b6ff)
+![picking a locator](./images/getting-started/pick-locator-java.webp)
######
* langs: python
-![picking a locator](https://github.com/microsoft/playwright/assets/13063165/95d11f48-96a4-46b9-9c2a-63c3aa4fdce7)
+![picking a locator](./images/getting-started/pick-locator-python.webp)
######
* langs: csharp
-![picking a locator](https://github.com/microsoft/playwright/assets/13063165/1478f56f-422f-4276-9696-0674041f11dc)
+![picking a locator](./images/getting-started/pick-locator-csharp.webp)
### Emulation
-You can also generate tests using emulation so as to generate a test for a specific viewport, device, color scheme, as well as emulate the geolocation, language or timezone. The test generator can also generate a test while preserving authenticated state. Check out the [Test Generator](./codegen.md#emulation) guide to learn more.
+You can generate tests using emulation for specific viewports, devices, color schemes, geolocation, language, or timezone. The test generator can also preserve authenticated state. Check out the [Test Generator](./codegen.md#emulation) guide to learn more.
## What's Next
diff --git a/docs/src/getting-started-vscode-js.md b/docs/src/getting-started-vscode-js.md
index 31977b32e7..9b98930804 100644
--- a/docs/src/getting-started-vscode-js.md
+++ b/docs/src/getting-started-vscode-js.md
@@ -27,22 +27,22 @@ Before you begin, make sure you have the following installed:
1. **Install the Extension**: Open the Extensions view in VS Code (`Ctrl+Shift+X` or `Cmd+Shift+X`) and search for "Playwright". [Install the official extension from Microsoft](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright).
-![install playwright extension](./images/getting-started/vscode-extension.png)
+![install playwright extension](./images/getting-started/vscode-extension.webp)
1. **Install Playwright**: Once the extension is installed, open the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) and run the **Test: Install Playwright** command.
-![install playwright](./images/getting-started/install-playwright.png)
+![install playwright](./images/getting-started/install-playwright.webp)
3. **Select Browsers**: Choose the browsers you want for your tests (e.g., Chromium, Firefox, WebKit). You can also add a GitHub Actions workflow to run tests in CI. These settings can be changed later in your `playwright.config.ts` file.
-![install browsers](./images/getting-started/install-browsers.png)
+![install browsers](./images/getting-started/install-browsers.webp)
### Opening the Testing Sidebar
Click the **Testing icon** in the VS Code Activity Bar to open the Test Explorer. Here, you'll find your tests, as well as the Playwright sidebar for managing projects, tools, and settings.
-![Testing Sidebar](./images/getting-started/testing-sidebar.png)
+![Testing Sidebar](./images/getting-started/testing-sidebar.webp)
## Core Features
@@ -55,19 +55,19 @@ Click the **Testing icon** in the VS Code Activity Bar to open the Test Explorer
- **Run a Single Test**: Click the green "play" icon next to any test to run it. The play button will change to a green checkmark if the test passes or a red X if the test fails. You'll be able to see how long the test took to run displayed next to the test name. Additionally, the Test Results panel will automatically open at the bottom of VS Code, showing a summary of the test execution including how many tests ran, how many passed, failed, or were skipped, along with the total execution time.
-![run a single test](./images/getting-started/run-single-test.png)
+![run a single test](./images/getting-started/run-single-test.webp)
- **Run All Tests**: You can run all tests at different levels. Click the play icon next to a specific test file to run all tests within that file, or click the play icon at the very top of the Test Explorer to run all tests across your entire project.
-![run all tests](./images/getting-started/run-all-tests.png)
+![run all tests](./images/getting-started/run-all-tests.webp)
- **Run on Multiple Browsers**: In the Playwright sidebar, check the boxes for the projects (browsers) you want to test against. Projects in Playwright represent different browser configurations - each project typically corresponds to a specific browser (like Chromium, Firefox, or WebKit) with its own settings such as viewport size, device emulation, or other browser-specific options. When you run a test, it will execute across all selected projects, allowing you to verify your application works consistently across different browsers and configurations.
-![Selecting projects to run tests on](./images/getting-started/select-projects.png)
+![Selecting projects to run tests on](./images/getting-started/select-projects.webp)
- **Show Browser**: To watch your tests execute in a live browser window, enable the **Show Browser** option in the sidebar. Disable it to run in headless mode (where tests run in the background without opening a visible browser window).
-![show browsers while running tests](./images/getting-started/show-browser.png)
+![show browsers while running tests](./images/getting-started/show-browser.webp)
### Debugging Your Tests
@@ -80,19 +80,19 @@ The VS Code extension provides powerful debugging tools to help you identify and
- **Using Breakpoints**: Set a breakpoint by clicking in the gutter next to a line number. Right-click the test and select **Debug Test**. The test will pause at your breakpoint, allowing you to inspect variables and step through the code.
- ![setting debug mode](./images/getting-started/debug-mode.png)
+ ![setting debug mode](./images/getting-started/debug-mode.webp)
- **Live Debugging**: With **Show Browsers** enabled, click on a locator in your code. Playwright will highlight the corresponding element in the browser, making it easy to verify locators.
- ![live debugging in vs code](./images/getting-started/live-debugging.png)
+ ![live debugging in vs code](./images/getting-started/live-debugging.webp)
- **Viewing Error Messages**: If a test fails, the extension displays detailed error messages, including the expected vs. received values and a full call log, directly in the editor.
-![error messaging in vs code](./images/getting-started/error-messaging.png)
+![error messaging in vs code](./images/getting-started/error-messaging.webp)
- **Fix with AI**: When a test fails, click the sparkle icon next to the error to get an AI-powered fix suggestion from Copilot. Copilot analyzes the error and suggests a code change to resolve the issue.
-![fix with ai in vs code](./images/getting-started/fix-with-ai.png)
+![fix with ai in vs code](./images/getting-started/fix-with-ai.webp)
- **Debugging with Trace Viewer**: For comprehensive debugging, enable the **Show Trace Viewer** option in the Playwright sidebar. When your test finishes, a detailed trace will automatically open, providing you with a complete timeline of your test execution. The trace viewer is particularly useful for:
- **Step-by-step analysis**: Navigate through each action your test performed with precise timestamps
@@ -104,7 +104,7 @@ The VS Code extension provides powerful debugging tools to help you identify and
The trace viewer is especially valuable when debugging flaky tests or understanding complex user interactions.
-![trace viewer debugging](./images/getting-started/trace-viewer-debug.png)
+![trace viewer debugging](./images/getting-started/trace-viewer-debug.webp)
To learn more, see our [Trace Viewer guide](./trace-viewer.md).
@@ -119,14 +119,14 @@ CodeGen is Playwright's powerful test generation tool that automatically creates
- **Record a New Test**: Click **Record new** in the sidebar. A browser window will open. As you interact with the page, Playwright will automatically generate the test code. You can also generate assertions from the recording toolbar.
-![record a new test](./images/getting-started/record-new-test.png)
+![record a new test](./images/getting-started/record-new-test.webp)
- **Record at Cursor**: Place your cursor inside an existing test and click **Record at cursor** to add new actions at that specific point.
-![record at cursor](./images/getting-started/record-at-cursor.png)
+![record at cursor](./images/getting-started/record-at-cursor.webp)
- **Pick a Locator**: Use the **Pick locator** tool to click on any element in the opened browser. Playwright will determine the best locator and copy it to your clipboard, ready to be pasted into your code.
-![pick locators](./images/getting-started/pick-locator.png)
+![pick locators](./images/getting-started/pick-locator.webp)
To learn more, see our [CodeGen guide](./codegen.md).
@@ -137,7 +137,7 @@ To learn more, see our [CodeGen guide](./codegen.md).
Use [project dependencies](./test-projects.md) to define setup tests that run before other tests. For example, you can create a login test that runs first, then reuse that authenticated state across multiple tests without having to log in again for each test. In VS Code, you can see these setup tests in the Test Explorer and run them independently when needed.
-![setup tests in vscode](./images/getting-started/setup-tests.png)
+![setup tests in vscode](./images/getting-started/setup-tests.webp)
To learn more, see our [Project Dependencies guide](./test-projects.md).
@@ -145,13 +145,13 @@ To learn more, see our [Project Dependencies guide](./test-projects.md).
For tasks that need to run only once before all tests (like seeding a database), use **Global Setup**. You can trigger the global setup and teardown manually from the Playwright sidebar.
-![running global setup](./images/getting-started/global-setup.png)
+![running global setup](./images/getting-started/global-setup.webp)
### Multiple Configurations
If you have multiple `playwright.config.ts` files, you can switch between them using the gear icon in the Playwright sidebar. This allows you to easily work with different test suites or environments.
-![Selecting a configuration file](./images/getting-started/selecting-configuration.png)
+![Selecting a configuration file](./images/getting-started/selecting-configuration.webp)
## Quick Reference
diff --git a/docs/src/images/getting-started/codegen-csharp.webp b/docs/src/images/getting-started/codegen-csharp.webp
new file mode 100644
index 0000000000..f6f9c3038f
Binary files /dev/null and b/docs/src/images/getting-started/codegen-csharp.webp differ
diff --git a/docs/src/images/getting-started/codegen-java.webp b/docs/src/images/getting-started/codegen-java.webp
new file mode 100644
index 0000000000..d46abe1a42
Binary files /dev/null and b/docs/src/images/getting-started/codegen-java.webp differ
diff --git a/docs/src/images/getting-started/codgen-js.webp b/docs/src/images/getting-started/codgen-js.webp
new file mode 100644
index 0000000000..3304a6355d
Binary files /dev/null and b/docs/src/images/getting-started/codgen-js.webp differ
diff --git a/docs/src/images/getting-started/codgen-python.webp b/docs/src/images/getting-started/codgen-python.webp
new file mode 100644
index 0000000000..341cb60da3
Binary files /dev/null and b/docs/src/images/getting-started/codgen-python.webp differ
diff --git a/docs/src/images/getting-started/debug-mode.png b/docs/src/images/getting-started/debug-mode.png
deleted file mode 100644
index 73c48a568d..0000000000
Binary files a/docs/src/images/getting-started/debug-mode.png and /dev/null differ
diff --git a/docs/src/images/getting-started/debug-mode.webp b/docs/src/images/getting-started/debug-mode.webp
new file mode 100644
index 0000000000..b7da19c2e5
Binary files /dev/null and b/docs/src/images/getting-started/debug-mode.webp differ
diff --git a/docs/src/images/getting-started/error-messaging.png b/docs/src/images/getting-started/error-messaging.png
deleted file mode 100644
index ced1f2f8c8..0000000000
Binary files a/docs/src/images/getting-started/error-messaging.png and /dev/null differ
diff --git a/docs/src/images/getting-started/error-messaging.webp b/docs/src/images/getting-started/error-messaging.webp
new file mode 100644
index 0000000000..cef670d35d
Binary files /dev/null and b/docs/src/images/getting-started/error-messaging.webp differ
diff --git a/docs/src/images/getting-started/fix-with-ai.png b/docs/src/images/getting-started/fix-with-ai.png
deleted file mode 100644
index d1adcdbe38..0000000000
Binary files a/docs/src/images/getting-started/fix-with-ai.png and /dev/null differ
diff --git a/docs/src/images/getting-started/fix-with-ai.webp b/docs/src/images/getting-started/fix-with-ai.webp
new file mode 100644
index 0000000000..fe8a776610
Binary files /dev/null and b/docs/src/images/getting-started/fix-with-ai.webp differ
diff --git a/docs/src/images/getting-started/global-setup.png b/docs/src/images/getting-started/global-setup.png
deleted file mode 100644
index 35d6aa8857..0000000000
Binary files a/docs/src/images/getting-started/global-setup.png and /dev/null differ
diff --git a/docs/src/images/getting-started/global-setup.webp b/docs/src/images/getting-started/global-setup.webp
new file mode 100644
index 0000000000..b8bb3d9630
Binary files /dev/null and b/docs/src/images/getting-started/global-setup.webp differ
diff --git a/docs/src/images/getting-started/html-report-basic.webp b/docs/src/images/getting-started/html-report-basic.webp
new file mode 100644
index 0000000000..18e5df9288
Binary files /dev/null and b/docs/src/images/getting-started/html-report-basic.webp differ
diff --git a/docs/src/images/getting-started/html-report-detail.webp b/docs/src/images/getting-started/html-report-detail.webp
new file mode 100644
index 0000000000..acffc4df3d
Binary files /dev/null and b/docs/src/images/getting-started/html-report-detail.webp differ
diff --git a/docs/src/images/getting-started/html-report-failed-tests.webp b/docs/src/images/getting-started/html-report-failed-tests.webp
new file mode 100644
index 0000000000..360b4b071d
Binary files /dev/null and b/docs/src/images/getting-started/html-report-failed-tests.webp differ
diff --git a/docs/src/images/getting-started/html-report-open.webp b/docs/src/images/getting-started/html-report-open.webp
new file mode 100644
index 0000000000..acffc4df3d
Binary files /dev/null and b/docs/src/images/getting-started/html-report-open.webp differ
diff --git a/docs/src/images/getting-started/html-report-trace.webp b/docs/src/images/getting-started/html-report-trace.webp
new file mode 100644
index 0000000000..01994821f7
Binary files /dev/null and b/docs/src/images/getting-started/html-report-trace.webp differ
diff --git a/docs/src/images/getting-started/html-report.webp b/docs/src/images/getting-started/html-report.webp
new file mode 100644
index 0000000000..986416fd54
Binary files /dev/null and b/docs/src/images/getting-started/html-report.webp differ
diff --git a/docs/src/images/getting-started/install-browsers.png b/docs/src/images/getting-started/install-browsers.png
deleted file mode 100644
index 715e620229..0000000000
Binary files a/docs/src/images/getting-started/install-browsers.png and /dev/null differ
diff --git a/docs/src/images/getting-started/install-browsers.webp b/docs/src/images/getting-started/install-browsers.webp
new file mode 100644
index 0000000000..6af4045e8b
Binary files /dev/null and b/docs/src/images/getting-started/install-browsers.webp differ
diff --git a/docs/src/images/getting-started/install-playwright.png b/docs/src/images/getting-started/install-playwright.png
deleted file mode 100644
index 38c2363909..0000000000
Binary files a/docs/src/images/getting-started/install-playwright.png and /dev/null differ
diff --git a/docs/src/images/getting-started/install-playwright.webp b/docs/src/images/getting-started/install-playwright.webp
new file mode 100644
index 0000000000..b6aba78b30
Binary files /dev/null and b/docs/src/images/getting-started/install-playwright.webp differ
diff --git a/docs/src/images/getting-started/live-debugging.png b/docs/src/images/getting-started/live-debugging.png
deleted file mode 100644
index 41f6d8e7e4..0000000000
Binary files a/docs/src/images/getting-started/live-debugging.png and /dev/null differ
diff --git a/docs/src/images/getting-started/live-debugging.webp b/docs/src/images/getting-started/live-debugging.webp
new file mode 100644
index 0000000000..3ece71ade7
Binary files /dev/null and b/docs/src/images/getting-started/live-debugging.webp differ
diff --git a/docs/src/images/getting-started/pick-locator-csharp.webp b/docs/src/images/getting-started/pick-locator-csharp.webp
new file mode 100644
index 0000000000..b3c559ed8e
Binary files /dev/null and b/docs/src/images/getting-started/pick-locator-csharp.webp differ
diff --git a/docs/src/images/getting-started/pick-locator-java.webp b/docs/src/images/getting-started/pick-locator-java.webp
new file mode 100644
index 0000000000..11e2b081ee
Binary files /dev/null and b/docs/src/images/getting-started/pick-locator-java.webp differ
diff --git a/docs/src/images/getting-started/pick-locator-js.webp b/docs/src/images/getting-started/pick-locator-js.webp
new file mode 100644
index 0000000000..6c7fc9b3af
Binary files /dev/null and b/docs/src/images/getting-started/pick-locator-js.webp differ
diff --git a/docs/src/images/getting-started/pick-locator-python.webp b/docs/src/images/getting-started/pick-locator-python.webp
new file mode 100644
index 0000000000..8c5e5fc7a1
Binary files /dev/null and b/docs/src/images/getting-started/pick-locator-python.webp differ
diff --git a/docs/src/images/getting-started/pick-locator.png b/docs/src/images/getting-started/pick-locator.png
deleted file mode 100644
index 26408dd356..0000000000
Binary files a/docs/src/images/getting-started/pick-locator.png and /dev/null differ
diff --git a/docs/src/images/getting-started/pick-locator.webp b/docs/src/images/getting-started/pick-locator.webp
new file mode 100644
index 0000000000..141d9581c1
Binary files /dev/null and b/docs/src/images/getting-started/pick-locator.webp differ
diff --git a/docs/src/images/getting-started/record-at-cursor.png b/docs/src/images/getting-started/record-at-cursor.png
deleted file mode 100644
index 0ab2fc0939..0000000000
Binary files a/docs/src/images/getting-started/record-at-cursor.png and /dev/null differ
diff --git a/docs/src/images/getting-started/record-at-cursor.webp b/docs/src/images/getting-started/record-at-cursor.webp
new file mode 100644
index 0000000000..cba4eb3954
Binary files /dev/null and b/docs/src/images/getting-started/record-at-cursor.webp differ
diff --git a/docs/src/images/getting-started/record-new-test.png b/docs/src/images/getting-started/record-new-test.png
deleted file mode 100644
index 085ff97aa5..0000000000
Binary files a/docs/src/images/getting-started/record-new-test.png and /dev/null differ
diff --git a/docs/src/images/getting-started/record-new-test.webp b/docs/src/images/getting-started/record-new-test.webp
new file mode 100644
index 0000000000..50608ddcfc
Binary files /dev/null and b/docs/src/images/getting-started/record-new-test.webp differ
diff --git a/docs/src/images/getting-started/record-test-csharp.webp b/docs/src/images/getting-started/record-test-csharp.webp
new file mode 100644
index 0000000000..f6f9c3038f
Binary files /dev/null and b/docs/src/images/getting-started/record-test-csharp.webp differ
diff --git a/docs/src/images/getting-started/record-test-java.webp b/docs/src/images/getting-started/record-test-java.webp
new file mode 100644
index 0000000000..d46abe1a42
Binary files /dev/null and b/docs/src/images/getting-started/record-test-java.webp differ
diff --git a/docs/src/images/getting-started/record-test-js.webp b/docs/src/images/getting-started/record-test-js.webp
new file mode 100644
index 0000000000..3304a6355d
Binary files /dev/null and b/docs/src/images/getting-started/record-test-js.webp differ
diff --git a/docs/src/images/getting-started/record-test-python.webp b/docs/src/images/getting-started/record-test-python.webp
new file mode 100644
index 0000000000..341cb60da3
Binary files /dev/null and b/docs/src/images/getting-started/record-test-python.webp differ
diff --git a/docs/src/images/getting-started/run-all-tests.png b/docs/src/images/getting-started/run-all-tests.png
deleted file mode 100644
index d339bf77b5..0000000000
Binary files a/docs/src/images/getting-started/run-all-tests.png and /dev/null differ
diff --git a/docs/src/images/getting-started/run-all-tests.webp b/docs/src/images/getting-started/run-all-tests.webp
new file mode 100644
index 0000000000..0c1a73da38
Binary files /dev/null and b/docs/src/images/getting-started/run-all-tests.webp differ
diff --git a/docs/src/images/getting-started/run-single-test.png b/docs/src/images/getting-started/run-single-test.png
deleted file mode 100644
index 32c226c960..0000000000
Binary files a/docs/src/images/getting-started/run-single-test.png and /dev/null differ
diff --git a/docs/src/images/getting-started/run-single-test.webp b/docs/src/images/getting-started/run-single-test.webp
new file mode 100644
index 0000000000..bccfe6e945
Binary files /dev/null and b/docs/src/images/getting-started/run-single-test.webp differ
diff --git a/docs/src/images/getting-started/run-tests-cli.webp b/docs/src/images/getting-started/run-tests-cli.webp
new file mode 100644
index 0000000000..7a4232d91e
Binary files /dev/null and b/docs/src/images/getting-started/run-tests-cli.webp differ
diff --git a/docs/src/images/getting-started/run-tests-debug.webp b/docs/src/images/getting-started/run-tests-debug.webp
new file mode 100644
index 0000000000..a85fcdddbc
Binary files /dev/null and b/docs/src/images/getting-started/run-tests-debug.webp differ
diff --git a/docs/src/images/getting-started/run-tests-pick-locator.webp b/docs/src/images/getting-started/run-tests-pick-locator.webp
new file mode 100644
index 0000000000..0970a5ba0e
Binary files /dev/null and b/docs/src/images/getting-started/run-tests-pick-locator.webp differ
diff --git a/docs/src/images/getting-started/select-projects.png b/docs/src/images/getting-started/select-projects.png
deleted file mode 100644
index 813b8553f0..0000000000
Binary files a/docs/src/images/getting-started/select-projects.png and /dev/null differ
diff --git a/docs/src/images/getting-started/select-projects.webp b/docs/src/images/getting-started/select-projects.webp
new file mode 100644
index 0000000000..4de9c5e6fe
Binary files /dev/null and b/docs/src/images/getting-started/select-projects.webp differ
diff --git a/docs/src/images/getting-started/selecting-configuration.png b/docs/src/images/getting-started/selecting-configuration.png
deleted file mode 100644
index 6fa106d57d..0000000000
Binary files a/docs/src/images/getting-started/selecting-configuration.png and /dev/null differ
diff --git a/docs/src/images/getting-started/selecting-configuration.webp b/docs/src/images/getting-started/selecting-configuration.webp
new file mode 100644
index 0000000000..b051b5a0cc
Binary files /dev/null and b/docs/src/images/getting-started/selecting-configuration.webp differ
diff --git a/docs/src/images/getting-started/setup-tests.png b/docs/src/images/getting-started/setup-tests.png
deleted file mode 100644
index f90faa7190..0000000000
Binary files a/docs/src/images/getting-started/setup-tests.png and /dev/null differ
diff --git a/docs/src/images/getting-started/setup-tests.webp b/docs/src/images/getting-started/setup-tests.webp
new file mode 100644
index 0000000000..1454057af6
Binary files /dev/null and b/docs/src/images/getting-started/setup-tests.webp differ
diff --git a/docs/src/images/getting-started/show-browser.png b/docs/src/images/getting-started/show-browser.png
deleted file mode 100644
index c5389d371e..0000000000
Binary files a/docs/src/images/getting-started/show-browser.png and /dev/null differ
diff --git a/docs/src/images/getting-started/show-browser.webp b/docs/src/images/getting-started/show-browser.webp
new file mode 100644
index 0000000000..af11373998
Binary files /dev/null and b/docs/src/images/getting-started/show-browser.webp differ
diff --git a/docs/src/images/getting-started/testing-sidebar.png b/docs/src/images/getting-started/testing-sidebar.png
deleted file mode 100644
index 3dcc449cca..0000000000
Binary files a/docs/src/images/getting-started/testing-sidebar.png and /dev/null differ
diff --git a/docs/src/images/getting-started/testing-sidebar.webp b/docs/src/images/getting-started/testing-sidebar.webp
new file mode 100644
index 0000000000..8cca4d1492
Binary files /dev/null and b/docs/src/images/getting-started/testing-sidebar.webp differ
diff --git a/docs/src/images/getting-started/trace-viewer-debug.png b/docs/src/images/getting-started/trace-viewer-debug.png
deleted file mode 100644
index 9dbcbcaf1f..0000000000
Binary files a/docs/src/images/getting-started/trace-viewer-debug.png and /dev/null differ
diff --git a/docs/src/images/getting-started/trace-viewer-debug.webp b/docs/src/images/getting-started/trace-viewer-debug.webp
new file mode 100644
index 0000000000..95c613d33c
Binary files /dev/null and b/docs/src/images/getting-started/trace-viewer-debug.webp differ
diff --git a/docs/src/images/getting-started/trace-viewer-failed-test.webp b/docs/src/images/getting-started/trace-viewer-failed-test.webp
new file mode 100644
index 0000000000..f078dd2f7a
Binary files /dev/null and b/docs/src/images/getting-started/trace-viewer-failed-test.webp differ
diff --git a/docs/src/images/getting-started/trace-viewer.png b/docs/src/images/getting-started/trace-viewer.png
deleted file mode 100644
index cb282aa18c..0000000000
Binary files a/docs/src/images/getting-started/trace-viewer.png and /dev/null differ
diff --git a/docs/src/images/getting-started/trace-viewer.webp b/docs/src/images/getting-started/trace-viewer.webp
new file mode 100644
index 0000000000..6ea574d9fb
Binary files /dev/null and b/docs/src/images/getting-started/trace-viewer.webp differ
diff --git a/docs/src/images/getting-started/ui-mode-error.webp b/docs/src/images/getting-started/ui-mode-error.webp
new file mode 100644
index 0000000000..5b6b2dfec4
Binary files /dev/null and b/docs/src/images/getting-started/ui-mode-error.webp differ
diff --git a/docs/src/images/getting-started/ui-mode-pick-locator.webp b/docs/src/images/getting-started/ui-mode-pick-locator.webp
new file mode 100644
index 0000000000..4fcf369343
Binary files /dev/null and b/docs/src/images/getting-started/ui-mode-pick-locator.webp differ
diff --git a/docs/src/images/getting-started/ui-mode.webp b/docs/src/images/getting-started/ui-mode.webp
new file mode 100644
index 0000000000..21a1793299
Binary files /dev/null and b/docs/src/images/getting-started/ui-mode.webp differ
diff --git a/docs/src/images/getting-started/vscode-extension.png b/docs/src/images/getting-started/vscode-extension.png
deleted file mode 100644
index 9f360e5a0d..0000000000
Binary files a/docs/src/images/getting-started/vscode-extension.png and /dev/null differ
diff --git a/docs/src/images/getting-started/vscode-extension.webp b/docs/src/images/getting-started/vscode-extension.webp
new file mode 100644
index 0000000000..2e2a5c66f3
Binary files /dev/null and b/docs/src/images/getting-started/vscode-extension.webp differ
diff --git a/docs/src/images/vscode-projects-section.png b/docs/src/images/vscode-projects-section.png
deleted file mode 100644
index d304dd04f9..0000000000
Binary files a/docs/src/images/vscode-projects-section.png and /dev/null differ
diff --git a/docs/src/intro-js.md b/docs/src/intro-js.md
index bb0df9a8e8..b424822983 100644
--- a/docs/src/intro-js.md
+++ b/docs/src/intro-js.md
@@ -5,23 +5,22 @@ title: "Installation"
## Introduction
-Playwright Test was created specifically to accommodate the needs of end-to-end testing. Playwright supports all modern rendering engines including Chromium, WebKit, and Firefox. Test on Windows, Linux, and macOS, locally or on CI, headless or headed with native mobile emulation of Google Chrome for Android and Mobile Safari.
+Playwright Test is an end-to-end test framework for modern web apps. It bundles test runner, assertions, isolation, parallelization and rich tooling. Playwright supports Chromium, WebKit and Firefox on Windows, Linux and macOS, locally or in CI, headless or headed, with native mobile emulation for Chrome (Android) and Mobile Safari.
**You will learn**
- [How to install Playwright](/intro.md#installing-playwright)
-- [What's Installed](/intro.md#whats-installed)
+- [What's installed](/intro.md#whats-installed)
- [How to run the example test](/intro.md#running-the-example-test)
- [How to open the HTML test report](/intro.md#html-test-reports)
-
## Installing Playwright
Get started by installing Playwright using one of the following methods.
### Using npm, yarn or pnpm
-The command below either initializes a new project with Playwright, or adds Playwright setup to your current project.
+The command below either initializes a new project or adds Playwright to an existing one.
<Tabs
groupId="js-package-manager"
@@ -58,37 +57,39 @@ pnpm create playwright
</Tabs>
-Run the install command and select the following to get started:
- - Choose between TypeScript or JavaScript (default is TypeScript)
- - Name of your Tests folder (default is `tests`, or `e2e` if you already have a `tests` folder in your project)
- - Add a GitHub Actions workflow to easily run tests on CI
- - Install Playwright browsers (default is true)
+When prompted, choose / confirm:
+- TypeScript or JavaScript (default: TypeScript)
+- Tests folder name (default: `tests`, or `e2e` if `tests` already exists)
+- Add a GitHub Actions workflow (recommended for CI)
+- Install Playwright browsers (default: yes)
+
+You can re-run the command later; it does not overwrite existing tests.
### Using the VS Code Extension
-Alternatively you can also get started and run your tests using the [VS Code Extension](./getting-started-vscode.md).
+You can also create and run tests with the [VS Code Extension](./getting-started-vscode.md).
## What's Installed
-Playwright will download the browsers needed as well as create the following files.
+Playwright downloads required browser binaries and creates the scaffold below.
```bash
-playwright.config.ts
+playwright.config.ts # Test configuration
package.json
-package-lock.json
+package-lock.json # Or yarn.lock / pnpm-lock.yaml
tests/
- example.spec.ts
+ example.spec.ts # Minimal example test
tests-examples/
- demo-todo-app.spec.ts
+ demo-todo-app.spec.ts # Richer example tests
```
-The [playwright.config](./test-configuration.md) is where you can add configuration for Playwright including modifying which browsers you would like to run Playwright on. If you are running tests inside an already existing project then dependencies will be added directly to your `package.json`.
+The [playwright.config](./test-configuration.md) centralizes configuration: target browsers, timeouts, retries, projects, reporters and more. In existing projects dependencies are added to your current `package.json`.
-The `tests` folder contains a basic example test to help you get started with testing. For a more detailed example check out the `tests-examples` folder which contains tests written to test a todo app.
+`tests/` contains a minimal starter test. `tests-examples/` provides richer samples (e.g. a todo app) to explore patterns.
## Running the Example Test
-By default tests will be run on all 3 browsers, Chromium, Firefox and WebKit using several workers. This can be configured in the [playwright.config file](./test-configuration.md). Tests are run in headless mode meaning no browser will open up when running the tests. Results of the tests and test logs will be shown in the terminal.
+By default tests run headless in parallel across Chromium, Firefox and WebKit (configurable in [playwright.config](./test-configuration.md)). Output and aggregated results display in the terminal.
<Tabs
groupId="js-package-manager"
@@ -125,12 +126,19 @@ pnpm exec playwright test
</Tabs>
-![tests running in command line](https://github.com/microsoft/playwright/assets/13063165/981c1b2b-dc7e-4b85-b241-272b44da6628)
-See our doc on [Running Tests](./running-tests.md) to learn more about running tests in headed mode, running multiple tests, running specific tests etc.
+![tests running in command line](./images/getting-started/run-tests-cli.webp)
+
+Tips:
+- See the browser window: add `--headed`.
+- Run a single project/browser: `--project=chromium`.
+- Run one file: `npx playwright test tests/example.spec.ts`.
+- Open testing UI: `--ui`.
+
+See [Running Tests](./running-tests.md) for details on filtering, headed mode, sharding and retries.
## HTML Test Reports
-After your test completes, an [HTML Reporter](./test-reporters.md#html-reporter) will be generated, which shows you a full report of your tests allowing you to filter the report by browsers, passed tests, failed tests, skipped tests and flaky tests. You can click on each test and explore the test's errors as well as each step of the test. By default, the HTML report is opened automatically if some of the tests failed.
+After a test run, the [HTML Reporter](./test-reporters.md#html-reporter) provides a dashboard filterable by the browser, passed, failed, skipped, flaky and more. Click a test to inspect errors, attachments and steps. It auto-opens only when failures occur; open manually with the command below.
<Tabs
groupId="js-package-manager"
@@ -167,11 +175,11 @@ pnpm exec playwright show-report
</Tabs>
-![HTML Report](https://github.com/microsoft/playwright/assets/13063165/38ec17a7-9e61-4002-b137-a93812765501)
+![HTML Report](./images/getting-started/html-report-basic.webp)
## Running the Example Test in UI Mode
-Run your tests with [UI Mode](./test-ui-mode.md) for a better developer experience with time travel debugging, watch mode and more.
+Run tests with [UI Mode](./test-ui-mode.md) for watch mode, live step view, time travel debugging and more.
<Tabs
groupId="js-package-manager"
@@ -209,13 +217,13 @@ pnpm exec playwright test --ui
</Tabs>
-![UI Mode](https://github.com/microsoft/playwright/assets/13063165/c5b501cc-4f5d-485a-87cc-66044c651786)
+![UI Mode](./images/getting-started/ui-mode.webp)
-Check out or [detailed guide on UI Mode](./test-ui-mode.md) to learn more about its features.
+See the [detailed guide on UI Mode](./test-ui-mode.md) for watch filters, step details and trace integration.
## Updating Playwright
-To update Playwright to the latest version run the following command:
+Update Playwright and download new browser binaries and their dependencies:
<Tabs
groupId="js-package-manager"
@@ -231,7 +239,6 @@ To update Playwright to the latest version run the following command:
```bash
npm install -D @playwright/test@latest
-# Also download new browser binaries and their dependencies:
npx playwright install --with-deps
```
@@ -241,7 +248,6 @@ npx playwright install --with-deps
```bash
yarn add --dev @playwright/test@latest
-# Also download new browser binaries and their dependencies:
yarn playwright install --with-deps
```
@@ -251,7 +257,6 @@ yarn playwright install --with-deps
```bash
pnpm install --save-dev @playwright/test@latest
-# Also download new browser binaries and their dependencies:
pnpm exec playwright install --with-deps
```
@@ -259,7 +264,7 @@ pnpm exec playwright install --with-deps
</Tabs>
-You can always check which version of Playwright you have by running the following command:
+Check your installed version:
<Tabs
groupId="js-package-manager"
@@ -299,14 +304,14 @@ pnpm exec playwright --version
## System requirements
-- Latest version of Node.js 20, 22 or 24.
+- Node.js: latest 20.x, 22.x or 24.x.
- Windows 10+, Windows Server 2016+ or Windows Subsystem for Linux (WSL).
-- macOS 14 Ventura, or later.
-- Debian 12, Debian 13, Ubuntu 22.04, Ubuntu 24.04, on x86-64 and arm64 architecture.
+- macOS 14 (Ventura) or later.
+- Debian 12 / 13, Ubuntu 22.04 / 24.04 (x86-64 or arm64).
## What's next
-- [Write tests using web first assertions, page fixtures and locators](./writing-tests.md)
-- [Run single test, multiple tests, headed mode](./running-tests.md)
+- [Write tests using web-first assertions, fixtures and locators](./writing-tests.md)
+- [Run single or multiple tests; headed mode](./running-tests.md)
- [Generate tests with Codegen](./codegen-intro.md)
-- [See a trace of your tests](./trace-viewer-intro.md)
+- [View a trace of your tests](./trace-viewer-intro.md)
diff --git a/docs/src/running-tests-js.md b/docs/src/running-tests-js.md
index 5cdc008bdc..a1d020cd3c 100644
--- a/docs/src/running-tests-js.md
+++ b/docs/src/running-tests-js.md
@@ -4,7 +4,7 @@ title: "Running and debugging tests"
---
## Introduction
-With Playwright you can run a single test, a set of tests or all tests. Tests can be run on one browser or multiple browsers by using the `--project` flag. Tests are run in parallel by default and are run in a headless manner, meaning no browser window will be opened while running the tests and results will be seen in the terminal. However, you can run tests in headed mode by using the `--headed` CLI argument, or you can run your tests in [UI mode](./test-ui-mode.md) by using the `--ui` flag. See a full trace of your tests complete with watch mode, time travel debugging and more.
+With Playwright you can run a single test, a set of tests, or all tests. Tests can be run on one browser or multiple browsers using the `--project` flag. Tests run in parallel by default and in headless mode, meaning no browser window opens while running the tests and results appear in the terminal. You can run tests in headed mode using the `--headed` CLI argument, or run your tests in [UI mode](./test-ui-mode.md) using the `--ui` flag to see a full trace of your tests.
**You will learn**
@@ -15,13 +15,13 @@ With Playwright you can run a single test, a set of tests or all tests. Tests ca
## Running tests
### Command line
-You can run your tests with the `playwright test` command. This will run your tests on all browsers as configured in the `playwright.config` file. Tests run in headless mode by default meaning no browser window will be opened while running the tests and results will be seen in the terminal.
+You can run your tests with the `playwright test` command. This runs your tests on all browsers as configured in the `playwright.config` file, and results appear in the terminal. Tests run in headless mode by default, meaning no browser window opens while running the tests.
```bash
npx playwright test
```
-![tests running in command line](https://github.com/microsoft/playwright/assets/13063165/981c1b2b-dc7e-4b85-b241-272b44da6628)
+![tests running in command line](./images/getting-started/run-tests-cli.webp)
### Run tests in UI mode
@@ -31,13 +31,13 @@ We highly recommend running your tests with [UI Mode](./test-ui-mode.md) for a b
npx playwright test --ui
```
-![UI Mode](https://github.com/microsoft/playwright/assets/13063165/c5b501cc-4f5d-485a-87cc-66044c651786)
+![UI Mode](./images/getting-started/ui-mode.webp)
-Check out or [detailed guide on UI Mode](./test-ui-mode.md) to learn more about its features.
+Check out our [detailed guide on UI Mode](./test-ui-mode.md) to learn more about its features.
### Run tests in headed mode
-To run your tests in headed mode, use the `--headed` flag. This will give you the ability to visually see how Playwright interacts with the website.
+To run your tests in headed mode, use the `--headed` flag. This gives you the ability to visually see how Playwright interacts with the website.
```bash
npx playwright test --headed
@@ -45,13 +45,13 @@ npx playwright test --headed
### Run tests on different browsers
-To specify which browser you would like to run your tests on, use the `--project` flag followed by the name of the browser.
+To specify which browser you would like to run your tests on, use the `--project` flag followed by the browser name.
```bash
npx playwright test --project webkit
```
-To specify multiple browsers to run your tests on, use the `--project` flag multiple times followed by the name of each browser.
+To specify multiple browsers to run your tests on, use the `--project` flag multiple times followed by each browser name.
```bash
npx playwright test --project webkit --project firefox
@@ -59,13 +59,13 @@ npx playwright test --project webkit --project firefox
### Run specific tests
-To run a single test file, pass in the name of the test file that you want to run.
+To run a single test file, pass in the test file name that you want to run.
```bash
npx playwright test landing-page.spec.ts
```
-To run a set of test files from different directories, pass in the names of the directories that you want to run the tests in.
+To run a set of test files from different directories, pass in the directory names that you want to run the tests in.
```bash
npx playwright test tests/todo-page/ tests/landing-page/
@@ -96,25 +96,25 @@ npx playwright test --last-failed
Tests can be run right from VS Code using the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright). Once installed you can simply click the green triangle next to the test you want to run or run all tests from the testing sidebar. Check out our [Getting Started with VS Code](./getting-started-vscode.md) guide for more details.
-![install playwright extension](./images/getting-started/vscode-extension.png)
+![install playwright extension](./images/getting-started/vscode-extension.webp)
## Debugging tests
-Since Playwright runs in Node.js, you can debug it with your debugger of choice e.g. using `console.log` or inside your IDE or directly in VS Code with the [VS Code Extension](./getting-started-vscode.md). Playwright comes with [UI Mode](./test-ui-mode.md), where you can easily walk through each step of the test, see logs, errors, network requests, inspect the DOM snapshot and more. You can also use the [Playwright Inspector](./debug.md#playwright-inspector), which allows you to step through Playwright API calls, see their debug logs and explore [locators](./locators.md).
+Since Playwright runs in Node.js, you can debug it with your debugger of choice, e.g. using `console.log`, inside your IDE, or directly in VS Code with the [VS Code Extension](./getting-started-vscode.md). Playwright comes with [UI Mode](./test-ui-mode.md), where you can easily walk through each step of the test, see logs, errors, network requests, inspect the DOM snapshot, and more. You can also use the [Playwright Inspector](./debug.md#playwright-inspector), which allows you to step through Playwright API calls, see their debug logs, and explore [locators](./locators.md).
### Debug tests in UI mode
-We highly recommend debugging your tests with [UI Mode](./test-ui-mode.md) for a better developer experience where you can easily walk through each step of the test and visually see what was happening before, during and after each step. UI mode also comes with many other features such as the locator picker, watch mode and more.
+We highly recommend debugging your tests with [UI Mode](./test-ui-mode.md) for a better developer experience where you can easily walk through each step of the test and visually see what was happening before, during, and after each step. UI mode also comes with many other features such as the locator picker, watch mode, and more.
```bash
npx playwright test --ui
```
-![showing errors in ui mode](https://github.com/microsoft/playwright/assets/13063165/ffca2fd1-5349-41fb-ade9-ace143bb2c58)
+![showing errors in ui mode](./images/getting-started/ui-mode-error.webp)
-While debugging you can use the Pick Locator button to select an element on the page and see the locator that Playwright would use to find that element. You can also edit the locator in the locator playground and see it highlighting live on the Browser window. Use the Copy Locator button to copy the locator to your clipboard and then paste it into your test.
+While debugging you can use the Pick Locator button to select an element on the page and see the locator that Playwright would use to find that element. You can also edit the locator in the locator playground and see it highlighting live in the browser window. Use the Copy Locator button to copy the locator to your clipboard and then paste it into your test.
-![pick locator in ui mode](https://github.com/microsoft/playwright/assets/13063165/9e7eeb84-bd26-4010-8614-75e24b56c716)
+![pick locator in ui mode](./images/getting-started/ui-mode-pick-locator.webp)
Check out our [detailed guide on UI Mode](./test-ui-mode.md) to learn more about its features.
@@ -126,11 +126,11 @@ To debug all tests, run the Playwright test command followed by the `--debug` fl
npx playwright test --debug
```
-![Debugging Tests with the Playwright inspector](https://github.com/microsoft/playwright/assets/13063165/6b3b3caa-d258-4cb8-aa05-cd407f501626)
+![Debugging Tests with the Playwright inspector](./images/getting-started/run-tests-debug.webp)
-This command will open up a Browser window as well as the Playwright Inspector. You can use the step over button at the top of the inspector to step through your test. Or, press the play button to run your test from start to finish. Once the test has finished, the browser window will close.
+This command opens a browser window as well as the Playwright Inspector. You can use the step over button at the top of the inspector to step through your test. Or, press the play button to run your test from start to finish. Once the test finishes, the browser window closes.
-To debug one test file, run the Playwright test command with the name of the test file that you want to debug followed by the `--debug` flag.
+To debug one test file, run the Playwright test command with the test file name that you want to debug followed by the `--debug` flag.
```bash
npx playwright test example.spec.ts --debug
@@ -142,27 +142,27 @@ To debug a specific test from the line number where the `test(..` is defined, ad
npx playwright test example.spec.ts:10 --debug
```
-While debugging you can use the Pick Locator button to select an element on the page and see the locator that Playwright would use to find that element. You can also edit the locator and see it highlighting live on the Browser window. Use the Copy Locator button to copy the locator to your clipboard and then paste it into your test.
+While debugging you can use the Pick Locator button to select an element on the page and see the locator that Playwright would use to find that element. You can also edit the locator and see it highlighting live in the browser window. Use the Copy Locator button to copy the locator to your clipboard and then paste it into your test.
-![Locator picker in the Playwright Inspector](https://github.com/microsoft/playwright/assets/13063165/013d5edb-583e-423a-bb53-9f57bab7f3e1)
+![Locator picker in the Playwright Inspector](./images/getting-started/run-tests-pick-locator.webp)
-Check out our [debugging guide](./debug.md) to learn more about debugging with the [VS Code debugger](./debug.md#vs-code-debugger), UI Mode and the [Playwright Inspector](./debug.md#playwright-inspector) as well as debugging with [Browser Developer tools](./debug.md#browser-developer-tools).
+Check out our [debugging guide](./debug.md) to learn more about debugging with the [VS Code debugger](./debug.md#vs-code-debugger), UI Mode, and the [Playwright Inspector](./debug.md#playwright-inspector) as well as debugging with [Browser Developer tools](./debug.md#browser-developer-tools).
## Test reports
-The [HTML Reporter](./test-reporters.md#html-reporter) shows you a full report of your tests allowing you to filter the report by browsers, passed tests, failed tests, skipped tests and flaky tests. By default, the HTML report is opened automatically if some of the tests failed, otherwise you can open it with the following command.
+The [HTML Reporter](./test-reporters.md#html-reporter) shows you a full report of your tests allowing you to filter the report by browsers, passed tests, failed tests, skipped tests, and flaky tests. By default, the HTML report opens automatically if some tests failed, otherwise you can open it with the following command.
```bash
npx playwright show-report
```
-![HTML Report](https://github.com/microsoft/playwright/assets/13063165/c5f60e56-fb75-4a2d-a4b6-054b8c5d69c1)
+![HTML Report](./images/getting-started/html-report.webp)
-You can filter and search for tests as well as click on each test to see the tests errors and explore each step of the test.
+You can filter and search for tests as well as click on each test to see the test errors and explore each step of the test.
-![HTML Reporter detail view](https://github.com/microsoft/playwright/assets/13063165/f36ada14-4701-4534-a3be-ed22c2b16cf5)
+![HTML Reporter detail view](./images/getting-started/html-report-detail.webp)
## What's next
diff --git a/docs/src/trace-viewer-intro-js.md b/docs/src/trace-viewer-intro-js.md
index 86b4f0b6bd..66802fb312 100644
--- a/docs/src/trace-viewer-intro-js.md
+++ b/docs/src/trace-viewer-intro-js.md
@@ -7,7 +7,7 @@ import LiteYouTube from '@site/src/components/LiteYouTube';
## Introduction
-Playwright Trace Viewer is a GUI tool that lets you explore recorded Playwright traces of your tests meaning you can go back and forward through each action of your test and visually see what was happening during each action.
+Playwright Trace Viewer is a GUI tool that lets you explore recorded Playwright traces of your tests, meaning you can go back and forward through each action of your test and visually see what was happening during each action.
**You will learn**
@@ -22,7 +22,7 @@ Playwright Trace Viewer is a GUI tool that lets you explore recorded Playwright
## Recording a Trace
-By default the [playwright.config](./trace-viewer.md#tracing-on-ci) file will contain the configuration needed to create a `trace.zip` file for each test. Traces are setup to run `on-first-retry` meaning they will be run on the first retry of a failed test. Also `retries` are set to 2 when running on CI and 0 locally. This means the traces will be recorded on the first retry of a failed test but not on the first run and not on the second retry.
+By default the [playwright.config](./trace-viewer.md#tracing-on-ci) file contains the configuration needed to create a `trace.zip` file for each test. Traces are setup to run `on-first-retry`, meaning they run on the first retry of a failed test. Also `retries` are set to 2 when running on CI and 0 locally. This means the traces are recorded on the first retry of a failed test but not on the first run and not on the second retry.
```js title="playwright.config.ts"
import { defineConfig } from '@playwright/test';
@@ -37,7 +37,7 @@ export default defineConfig({
To learn more about available options to record a trace check out our detailed guide on [Trace Viewer](/trace-viewer.md).
-Traces are normally run in a Continuous Integration(CI) environment, because locally you can use [UI Mode](/test-ui-mode.md) for developing and debugging tests. However, if you want to run traces locally without using [UI Mode](/test-ui-mode.md), you can force tracing to be on with `--trace on`.
+Traces are normally run in a Continuous Integration (CI) environment, because locally you can use [UI Mode](/test-ui-mode.md) for developing and debugging tests. However, if you want to run traces locally without using [UI Mode](/test-ui-mode.md), you can force tracing to be on with `--trace on`.
```bash
npx playwright test --trace on
@@ -45,7 +45,7 @@ npx playwright test --trace on
## Opening the HTML report
-The HTML report shows you a report of all your tests that have been run and on which browsers as well as how long they took. Tests can be filtered by passed tests, failed, flaky or skipped tests. You can also search for a particular test. Clicking on a test will open the detailed view where you can see more information on your tests such as the errors, the test steps and the trace.
+The HTML report shows you a report of all your tests that have been run and on which browsers as well as how long they took. Tests can be filtered by passed tests, failed, flaky, or skipped tests. You can also search for a particular test. Clicking on a test opens the detailed view where you can see more information on your tests such as the errors, the test steps, and the trace.
```bash
npx playwright show-report
@@ -53,25 +53,25 @@ npx playwright show-report
## Opening the trace
-In the HTML report click on the trace icon next to the test name file name to directly open the trace for the required test.
+In the HTML report, click on the trace icon next to the test file name to directly open the trace for the required test.
-![playwright html report](https://github.com/microsoft/playwright/assets/13063165/a3da1fb5-6619-4c03-98aa-adf65c376525)
+![playwright html report](./images/getting-started/html-report-failed-tests.webp)
-You can also click open the detailed view of the test and scroll down to the `'Traces'` tab and open the trace by clicking on the trace screenshot.
+You can also click to open the detailed view of the test and scroll down to the `'Traces'` tab and open the trace by clicking on the trace screenshot.
-![playwright html report detailed view](https://github.com/microsoft/playwright/assets/13063165/2b583d6f-5241-4ecf-83a8-650072d4a201)
+![playwright html report detailed view](./images/getting-started/html-report-trace.webp)
-To learn more about reporters check out our detailed guide on reporters including the [HTML Reporter](/test-reporters.md#html-reporter).
+To learn more about reporters, check out our detailed guide on reporters including the [HTML Reporter](/test-reporters.md#html-reporter).
## Viewing the trace
-View traces of your test by clicking through each action or hovering using the timeline and see the state of the page before and after the action. Inspect the log, source and network, errors and console during each step of the test. The trace viewer creates a DOM snapshot so you can fully interact with it and open the browser DevTools to inspect the HTML, CSS, etc.
+View traces of your test by clicking through each action or hovering using the timeline and see the state of the page before and after the action. Inspect the log, source and network, errors, and console during each step of the test. The trace viewer creates a DOM snapshot so you can fully interact with it and open the browser DevTools to inspect the HTML, CSS, etc.
-![playwright trace viewer](https://github.com/microsoft/playwright/assets/13063165/10fe3585-8401-4051-b1c2-b2e92ac4c274)
+![playwright trace viewer](./images/getting-started/trace-viewer-failed-test.webp)
-To learn more about traces check out our detailed guide on [Trace Viewer](/trace-viewer.md).
+To learn more about traces, check out our detailed guide on [Trace Viewer](/trace-viewer.md).
## What's next
diff --git a/docs/src/writing-tests-js.md b/docs/src/writing-tests-js.md
index 2cabde1564..f86d223439 100644
--- a/docs/src/writing-tests-js.md
+++ b/docs/src/writing-tests-js.md
@@ -4,21 +4,9 @@ title: "Writing tests"
---
## Introduction
-Playwright tests are simple, they
+Playwright tests are simple: they **perform actions** and **assert the state** against expectations.
-- **perform actions**, and
-- **assert the state** against expectations.
-
-There is no need to wait for anything prior to performing an action: Playwright
-automatically waits for the wide range of [actionability](./actionability.md)
-checks to pass prior to performing each action.
-
-There is also no need to deal with the race conditions when performing the checks -
-Playwright assertions are designed in a way that they describe the expectations
-that need to be eventually met.
-
-That's it! These design choices allow Playwright users to forget about flaky
-timeouts and racy checks in their tests altogether.
+Playwright automatically waits for [actionability](./actionability.md) checks to pass before performing each action. You don't need to add manual waits or deal with race conditions. Playwright assertions are designed to describe expectations that will eventually be met, eliminating flaky timeouts and racy checks.
**You will learn**
@@ -52,7 +40,7 @@ test('get started link', async ({ page }) => {
await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});
```
-
+
:::note
Add `// @ts-check` at the start of each test file when using JavaScript in VS Code to get automatic type checking.
:::
@@ -62,8 +50,7 @@ Add `// @ts-check` at the start of each test file when using JavaScript in VS Co
### Navigation
-Most of the tests will start with navigating page to the URL. After that, test
-will be able to interact with the page elements.
+Most tests start by navigating to a URL. After that, the test interacts with page elements.
```js
await page.goto('https://playwright.dev/');
@@ -73,12 +60,13 @@ await page.goto('https://playwright.dev/');
page.goto("https://playwright.dev/")
```
-Playwright will wait for page to reach the load state prior to moving forward.
-Learn more about the [`method: Page.goto`] options.
+Playwright waits for the page to reach the load state before continuing. Learn more about [`method: Page.goto`] options.
### Interactions
-Performing actions starts with locating the elements. Playwright uses [Locators API](./locators.md) for that. Locators represent a way to find element(s) on the page at any moment, learn more about the [different types](./locators.md) of locators available. Playwright will wait for the element to be [actionable](./actionability.md) prior to performing the action, so there is no need to wait for it to become available.
+Performing actions starts with locating elements. Playwright uses [Locators API](./locators.md) for that. Locators represent a way to find element(s) on the page at any moment. Learn more about the [different types](./locators.md) of locators available.
+
+Playwright waits for the element to be [actionable](./actionability.md) before performing the action, so you don't need to wait for it to become available.
```js
@@ -97,8 +85,7 @@ await page.getByRole('link', { name: 'Get started' }).click();
### Basic actions
-This is the list of the most popular Playwright actions. Note that there are many more, so make sure to check the [Locator API](./api/class-locator.md) section to
-learn more about them.
+Here are the most popular Playwright actions. For the complete list, check the [Locator API](./api/class-locator.md) section.
| Action | Description |
| :- | :- |
@@ -113,22 +100,16 @@ learn more about them.
| [`method: Locator.selectOption`] | Select option in the drop down |
## Assertions
-
-Playwright includes [test assertions](./test-assertions.md) in the form of `expect` function. To make an assertion, call `expect(value)` and choose a matcher that reflects the expectation.
-
-There are many generic matchers like `toEqual`, `toContain`, `toBeTruthy` that can be used to assert any conditions.
-```js
-expect(success).toBeTruthy();
-```
+Playwright includes [test assertions](./test-assertions.md) in the form of `expect` function. To make an assertion, call `expect(value)` and choose a matcher that reflects the expectation.
-Playwright also includes async matchers that will wait until the expected condition is met. Using these matchers allows making the tests non-flaky and resilient. For example, this code will wait until the page gets the title containing "Playwright":
+Playwright includes async matchers that wait until the expected condition is met. Using these matchers makes tests non-flaky and resilient. For example, this code waits until the page gets the title containing "Playwright":
```js
await expect(page).toHaveTitle(/Playwright/);
```
-
-Here is the list of the most popular async assertions. Note that there are [many more](./test-assertions.md) to get familiar with:
+
+Here are the most popular async assertions. For the complete list, see [assertions guide](./test-assertions.md):
| Assertion | Description |
| :- | :- |
@@ -143,9 +124,16 @@ Here is the list of the most popular async assertions. Note that there are [many
| [`method: PageAssertions.toHaveTitle`] | Page has title |
| [`method: PageAssertions.toHaveURL`] | Page has URL |
+Playwright also includes generic matchers like `toEqual`, `toContain`, `toBeTruthy` that can be used to assert any conditions. These assertions do not use the `await` keyword as they perform immediate synchronous checks on already available values.
+
+```js
+expect(success).toBeTruthy();
+```
+
+
### Test Isolation
-
-Playwright Test is based on the concept of [test fixtures](./test-fixtures.md) such as the [built in page fixture](./test-fixtures#built-in-fixtures), which is passed into your test. Pages are [isolated between tests due to the Browser Context](./browser-contexts), which is equivalent to a brand new browser profile, where every test gets a fresh environment, even when multiple tests run in a single Browser.
+
+Playwright Test is based on the concept of [test fixtures](./test-fixtures.md) such as the [built in page fixture](./test-fixtures#built-in-fixtures), which is passed into your test. Pages are [isolated between tests due to the Browser Context](./browser-contexts), which is equivalent to a brand new browser profile. Every test gets a fresh environment, even when multiple tests run in a single browser.
```js title="tests/example.spec.ts"
import { test } from '@playwright/test';