Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
docs: update VS Code getting started guide with new images and content enhancements (#36799)
Debbie O'Brien454a02ab5a38
diff --git a/docs/src/getting-started-vscode-js.md b/docs/src/getting-started-vscode-js.mdindex 03e29ff2e9..7cdbeda3be 100644--- a/docs/src/getting-started-vscode-js.md+++ b/docs/src/getting-started-vscode-js.md@@ -7,229 +7,166 @@ import LiteYouTube from '@site/src/components/LiteYouTube';## 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.--Get started by installing Playwright and generating a test to see it in action. Alternatively you can also get started and run your tests using the [CLI](./intro.md).+The Playwright VS Code extension brings the power of Playwright Test directly into your editor, allowing you to run, debug, and generate tests with a seamless UI-driven experience. This guide will walk you through setting up the extension and using its core features to supercharge your end-to-end testing workflow.<LiteYouTubeid="Xz6lhEzgI5I"title="Getting Started with Playwright in VS Code"/>-## Installation--Playwright has a VS Code extension which is available when testing with Node.js. Install [it from the VS Code marketplace](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright) or from the extensions tab in VS Code.----Once installed, open the command panel and type:--```bash-Install Playwright-```--+## Prerequisites+Before you begin, make sure you have the following installed:+- [Node.js](https://nodejs.org/) (LTS version recommended)+- [Visual Studio Code](https://code.visualstudio.com/)-Select **Test: Install Playwright** and Choose the browsers you would like to run your tests on. These can be later configured in the [playwright.config](./test-configuration.md) file. You can also choose if you would like to have a GitHub Actions setup to [run your tests on CI](./ci-intro.md).+## Getting Started-+### Installation & Setup-### Opening the testing sidebar+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).-The testing sidebar can be opened by clicking on the testing icon in the activity bar. This will give you access to the test explorer, which will show you all the tests in your project as well as the Playwright sidebar which includes projects, settings, tools and setup.-+-## Running tests--You can run a single test by clicking the green triangle next to your test block to run your test. Playwright will run through each line of the test and when it finishes you will see a green tick next to your test block as well as the time it took to run the test.--<LiteYouTube- id="mQmcIBMsc38"- title="Getting Started with Playwright in VS Code"-/>-+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.+-### Run tests and show browsers+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.-You can also run your tests and show the browsers by selecting the option **Show Browsers** in the testing sidebar. Then when you click the green triangle to run your test the browser will open and you will visually see it run through your test. Leave this selected if you want browsers open for all your tests or uncheck it if you prefer your tests to run in headless mode with no browser open.+-+### Opening the Testing Sidebar-Use the **Close all browsers** button to close all browsers.+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.-### View and run all tests+-View all tests in the testing sidebar and extend the tests by clicking on each test. Tests that have not been run will not have the green check next to them. Run all tests by clicking on the white triangle as you hover over the tests in the testing sidebar.+## Core Features-+### Running Your Tests-### Running tests on multiple browsers--The first section in the Playwright sidebar is the projects section. Here you can see all your projects as defined in your Playwright config file. The default config when installing Playwright gives you 3 projects, Chromium, Firefox and WebKit. The first project is selected by default.----To run tests on multiple projects, select each project by checking the checkboxes next to the project name. Then when you run your tests from the sidebar or by pressing the play button next to the test name, the tests will run on all the selected projects.----You can also individually run a test on a specific project by clicking the grey play button next to the project name of the test.----### Run tests with trace viewer+<LiteYouTube+ id="mQmcIBMsc38"+ title="Running Playwright Tests in VS Code"+/>-For a better developer experience you can run your tests with the **Show Trace Viewer** option.+- **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.-+-This will open up a full trace of your test where you can step through each action of your tests, explore the timeline, source code and more.+- **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.-+-To learn more about the trace viewer see our [Trace Viewer guide](./trace-viewer.md).+- **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.++- **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).-## Debugging tests+-With the VS Code extension you can debug your tests right in VS Code see error messages, create breakpoints and live debug your tests.+### Debugging Your Tests<LiteYouTubeid="tJF7UhA59Gc"title="Debugging Playwright tests in VS Code"/>-### Error messages--If your test fails VS Code will show you error messages right in the editor showing what was expected, what was received as well as a complete call log.+The VS Code extension provides powerful debugging tools to help you identify and fix issues in your tests. You can set breakpoints, inspect variables, view detailed error messages, get AI-powered suggestions to resolve test failures, and use the comprehensive trace viewer to analyze test execution step-by-step.-+- **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.-### Live debugging+ -You can debug your test live in VS Code. After running a test with the `Show Browser` option checked, click on any of the locators in VS Code and it will be highlighted in the Browser window. Playwright will highlight it if it exists and show you if there is more than one result+- **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.-+ -You can also edit the locators in VS Code and Playwright will show you the changes live in the browser window.+- **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.-### Run in debug mode+-To set a breakpoint click next to the line number where you want the breakpoint to be until a red dot appears. Run the tests in debug mode by right clicking on the line next to the test you want to run.+- **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.-+-A browser window will open and the test will run and pause at where the breakpoint is set. You can step through the tests, pause the test and rerun the tests from the menu in VS Code.+- **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+ - **DOM inspection**: View DOM snapshots at any point during test execution to see exactly what the page looked like+ - **Network monitoring**: Examine all network requests and responses that occurred during the test+ - **Console logs**: Access all console messages and errors from the browser+ - **Source mapping**: Jump directly to the source code that executed each action+ - **Visual debugging**: See screenshots and understand what the user would have seen at each step-+ The trace viewer is especially valuable when debugging flaky tests or understanding complex user interactions.-+-To learn more about debugging, see [Debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging).+To learn more, see our [Trace Viewer guide](./trace-viewer.md).-### Debug with trace viewer+### Generating Tests with CodeGen-For a better developer experience you can debug your tests with the **Show Trace Viewer** option.----This will open up a full trace of your test where you can step through each action and see what happened before and after the action. You can also inspect the DOM snapshot, see console logs, network requests, the source code and more.----To learn more about the trace viewer see our [Trace Viewer guide](./trace-viewer.md).--## Generating tests--CodeGen will auto generate your tests for you as you perform actions in the browser and is a great way to quickly get started. The viewport for the browser window is set to a specific width and height. See the [configuration guide](./test-configuration.md) to change the viewport or emulate different environments.+CodeGen is Playwright's powerful test generation tool that automatically creates test code by recording your interactions with a web page. Instead of writing tests from scratch, you can simply navigate through your application while CodeGen captures your actions and converts them into reliable test code with proper locators and assertions.<LiteYouTubeid="5XIZPqKkdBA"title="Generating Playwright tests in VS Code"/>-### Record a new test--To record a test click on the **Record new** button from the Testing sidebar. This will create a `test-1.spec.ts` file as well as open up a browser window. In the browser go to the URL you wish to test and start clicking around. Playwright will record your actions and generate the test code directly in VS Code. You can also generate assertions by choosing one of the icons in the toolbar and then clicking on an element on the page to assert against. The following assertions can be generated:- * `'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--Once you are done recording click the **cancel** button or close the browser window. You can then inspect your `test-1.spec.ts` file and see your generated test.-----### Record at cursor--To record from a specific point in your test file click the **Record at cursor** button from the Testing sidebar. This generates actions into the existing test at the current cursor position. You can run the test, position the cursor at the end of the test and continue generating the test.----### Picking a locator--Pick a [locator](./locators.md) and copy it into your test file by clicking the **Pick locator** button form the testing sidebar. Then in the browser click the element you require and it will now show up in the **Pick locator** box in VS Code. Press 'enter' on your keyboard to copy the locator into the clipboard and then paste anywhere in your code. Or press 'escape' if you want to cancel.-----Playwright will look at your page and figure out the best locator, prioritizing [role, text and test id locators](./locators.md). If the generator finds multiple elements matching the locator, it will improve the locator to make it resilient and uniquely identify the target element, so you don't have to worry about failing tests due to locators.--## Project Dependencies--You can use [project dependencies](./test-projects.md) to run tests that depend on other tests. This is useful for **setup** tests such as logging in to a website.--### Running setup tests--To run your setup tests select the **setup** project, as defined in your configuration file, from the project section in the Playwright sidebar. This will give you access to the **setup** tests in the test explorer.--+- **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.-When you run a test that depends on the **setup** tests, the **setup** test will run first. Each time you run the test, the **setup** test will run again.+-+- **Record at Cursor**: Place your cursor inside an existing test and click **Record at cursor** to add new actions at that specific point.+-### Running setup tests only once+- **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.-To run the **setup** test only once, deselect it from the projects section in the Playwright sidebar. The **setup** test is now removed from the test explorer. When you run a test that depends on the **setup** test, it will no longer run the **setup** test, making it much faster and therefore a much better developer experience.+-+To learn more, see our [CodeGen guide](./codegen.md).-## Global Setup-**Global setup** runs when you execute your first test. It runs only once and is useful for setting up a database or starting a server. You can manually run **global setup** by clicking the `Run global setup` option from the **Setup** section in the Playwright sidebar. **Global teardown** does not run by default; you need to manually initiate it by clicking the `Run global teardown` option.+## Advanced Features-Global setup will re-run when you debug tests as this ensures an isolated environment and dedicated setup for the test.+### Project Dependencies-+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.-## Multiple configurations+-If your project contains more than one playwright configuration file, you can switch between them by first clicking on the gear icon in the top right corner of the Playwright sidebar. This will show you all the configuration files in your project. Select the configuration files you want to use by checking the checkbox next to each one and clicking on the 'ok' button.+To learn more, see our [Project Dependencies guide](./test-projects.md).-+### Global Setup-You will now have access to all your tests in the test explorer. To run a test click on the grey triangle next to the file or project name.+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.-+-To run all tests from all configurations click on the grey triangle at the top of the test explorer.+### 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.-To choose a configuration file to work with simply toggle between them by clicking on the configuration file name in the Playwright sidebar. Now when you use the tools, such as Record a test, it will record a test for the selected configuration file.+-+## Quick Reference-You can easily toggle back and forth between configurations by clicking on the configuration file name in the Playwright sidebar.+| Action | How to do it in VS Code |+| ----------------------- | ----------------------------------------------------------- |+| **Install Playwright** | Command Palette → `Test: Install Playwright` |+| **Run a Test** | Click the "play" icon next to the test |+| **Debug a Test** | Set a breakpoint, right-click the test → `Debug Test` |+| **Show Live Browser** | Enable `Show Browsers` in the Playwright sidebar |+| **Record a New Test** | Click `Record new` in the Playwright sidebar |+| **Pick a Locator** | Click `Pick locator` in the Playwright sidebar |+| **View Test Trace** | Enable `Show Trace Viewer` in the Playwright sidebar |-## What's next+## What's Next-- [Write tests using web first assertions, page fixtures and locators](./writing-tests.md)-- [Run your tests on CI](./ci-intro.md)-- [Learn more about the Trace Viewer](./trace-viewer.md)+- [Write tests using web-first assertions, page fixtures, and locators](./writing-tests.md)+- [Run your tests on CI](./ci-intro.md)+- [Learn more about the Trace Viewer](./trace-viewer.md)diff --git a/docs/src/images/getting-started/debug-mode.png b/docs/src/images/getting-started/debug-mode.pngnew file mode 100644index 0000000000..73c48a568dBinary files /dev/null and b/docs/src/images/getting-started/debug-mode.png differdiff --git a/docs/src/images/getting-started/error-messaging.png b/docs/src/images/getting-started/error-messaging.pngnew file mode 100644index 0000000000..ced1f2f8c8Binary files /dev/null and b/docs/src/images/getting-started/error-messaging.png differdiff --git a/docs/src/images/getting-started/fix-with-ai.png b/docs/src/images/getting-started/fix-with-ai.pngnew file mode 100644index 0000000000..d1adcdbe38Binary files /dev/null and b/docs/src/images/getting-started/fix-with-ai.png differdiff --git a/docs/src/images/getting-started/global-setup.png b/docs/src/images/getting-started/global-setup.pngnew file mode 100644index 0000000000..35d6aa8857Binary files /dev/null and b/docs/src/images/getting-started/global-setup.png differdiff --git a/docs/src/images/getting-started/install-browsers.png b/docs/src/images/getting-started/install-browsers.pngnew file mode 100644index 0000000000..715e620229Binary files /dev/null and b/docs/src/images/getting-started/install-browsers.png differdiff --git a/docs/src/images/getting-started/install-playwright.png b/docs/src/images/getting-started/install-playwright.pngnew file mode 100644index 0000000000..38c2363909Binary files /dev/null and b/docs/src/images/getting-started/install-playwright.png differdiff --git a/docs/src/images/getting-started/live-debugging.png b/docs/src/images/getting-started/live-debugging.pngnew file mode 100644index 0000000000..41f6d8e7e4Binary files /dev/null and b/docs/src/images/getting-started/live-debugging.png differdiff --git a/docs/src/images/getting-started/pick-locator.png b/docs/src/images/getting-started/pick-locator.pngnew file mode 100644index 0000000000..26408dd356Binary files /dev/null and b/docs/src/images/getting-started/pick-locator.png differdiff --git a/docs/src/images/getting-started/record-at-cursor.png b/docs/src/images/getting-started/record-at-cursor.pngnew file mode 100644index 0000000000..0ab2fc0939Binary files /dev/null and b/docs/src/images/getting-started/record-at-cursor.png differdiff --git a/docs/src/images/getting-started/record-new-test.png b/docs/src/images/getting-started/record-new-test.pngnew file mode 100644index 0000000000..085ff97aa5Binary files /dev/null and b/docs/src/images/getting-started/record-new-test.png differdiff --git a/docs/src/images/getting-started/run-all-tests.png b/docs/src/images/getting-started/run-all-tests.pngnew file mode 100644index 0000000000..d339bf77b5Binary files /dev/null and b/docs/src/images/getting-started/run-all-tests.png differdiff --git a/docs/src/images/getting-started/run-single-test.png b/docs/src/images/getting-started/run-single-test.pngnew file mode 100644index 0000000000..32c226c960Binary files /dev/null and b/docs/src/images/getting-started/run-single-test.png differdiff --git a/docs/src/images/getting-started/select-projects.png b/docs/src/images/getting-started/select-projects.pngnew file mode 100644index 0000000000..813b8553f0Binary files /dev/null and b/docs/src/images/getting-started/select-projects.png differdiff --git a/docs/src/images/getting-started/selecting-configuration.png b/docs/src/images/getting-started/selecting-configuration.pngnew file mode 100644index 0000000000..6fa106d57dBinary files /dev/null and b/docs/src/images/getting-started/selecting-configuration.png differdiff --git a/docs/src/images/getting-started/setup-tests.png b/docs/src/images/getting-started/setup-tests.pngnew file mode 100644index 0000000000..f90faa7190Binary files /dev/null and b/docs/src/images/getting-started/setup-tests.png differdiff --git a/docs/src/images/getting-started/show-browser.png b/docs/src/images/getting-started/show-browser.pngnew file mode 100644index 0000000000..c5389d371eBinary files /dev/null and b/docs/src/images/getting-started/show-browser.png differdiff --git a/docs/src/images/getting-started/testing-sidebar.png b/docs/src/images/getting-started/testing-sidebar.pngnew file mode 100644index 0000000000..3dcc449ccaBinary files /dev/null and b/docs/src/images/getting-started/testing-sidebar.png differdiff --git a/docs/src/images/getting-started/trace-viewer-debug.png b/docs/src/images/getting-started/trace-viewer-debug.pngnew file mode 100644index 0000000000..9dbcbcaf1fBinary files /dev/null and b/docs/src/images/getting-started/trace-viewer-debug.png differdiff --git a/docs/src/images/getting-started/trace-viewer.png b/docs/src/images/getting-started/trace-viewer.pngnew file mode 100644index 0000000000..cb282aa18cBinary files /dev/null and b/docs/src/images/getting-started/trace-viewer.png differdiff --git a/docs/src/images/getting-started/vscode-extension.png b/docs/src/images/getting-started/vscode-extension.pngnew file mode 100644index 0000000000..9f360e5a0dBinary files /dev/null and b/docs/src/images/getting-started/vscode-extension.png differdiff --git a/docs/src/running-tests-js.md b/docs/src/running-tests-js.mdindex 4ad9ea9c67..5cdc008bdc 100644--- a/docs/src/running-tests-js.md+++ b/docs/src/running-tests-js.md@@ -94,9 +94,9 @@ npx playwright test --last-failed### Run tests in VS Code-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#running-tests) guide for more details.+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.-+## Debugging tests