diff --git a/dotnet/docs/api/class-browsercontext.mdx b/dotnet/docs/api/class-browsercontext.mdx index c19df7a3476..da9fcb6629b 100644 --- a/dotnet/docs/api/class-browsercontext.mdx +++ b/dotnet/docs/api/class-browsercontext.mdx @@ -911,6 +911,50 @@ await BrowserContext.SetOfflineAsync(offline); --- +### SetStorageStateAsync {#browser-context-set-storage-state} + +Added in: v1.55browserContext.SetStorageStateAsync + +Resets storage state in the context by clearing cookies, cache and storage, and then applying the new storage state. + +**Usage** + +```csharp +await BrowserContext.SetStorageStateAsync(storageState); +``` + +**Arguments** +- `storageState` [string]# + + Populates context with given storage state. This option can be used to initialize context with logged-in information obtained via [BrowserContext.StorageStateAsync()](/api/class-browsercontext.mdx#browser-context-storage-state). + +**Returns** +- [void]# + +--- + +### SetStorageStatePathAsync {#browser-context-set-storage-state-path} + +Added in: v1.55browserContext.SetStorageStatePathAsync + +Resets storage state in the context by clearing cookies, cache and storage, and then applying the new storage state from a file. + +**Usage** + +```csharp +await BrowserContext.SetStorageStatePathAsync(storageStatePath); +``` + +**Arguments** +- `storageStatePath` [string]# + + Populates context with given storage state. This option can be used to initialize context with logged-in information obtained via [BrowserContext.StorageStateAsync()](/api/class-browsercontext.mdx#browser-context-storage-state). Path to the file with saved storage state. + +**Returns** +- [void]# + +--- + ### StorageStateAsync {#browser-context-storage-state} Added before v1.9browserContext.StorageStateAsync diff --git a/images/getting-started/debug-mode.png b/images/getting-started/debug-mode.png new file mode 100644 index 00000000000..73c48a568df Binary files /dev/null and b/images/getting-started/debug-mode.png differ diff --git a/images/getting-started/error-messaging.png b/images/getting-started/error-messaging.png new file mode 100644 index 00000000000..ced1f2f8c8a Binary files /dev/null and b/images/getting-started/error-messaging.png differ diff --git a/images/getting-started/fix-with-ai.png b/images/getting-started/fix-with-ai.png new file mode 100644 index 00000000000..d1adcdbe381 Binary files /dev/null and b/images/getting-started/fix-with-ai.png differ diff --git a/images/getting-started/global-setup.png b/images/getting-started/global-setup.png new file mode 100644 index 00000000000..35d6aa88570 Binary files /dev/null and b/images/getting-started/global-setup.png differ diff --git a/images/getting-started/install-browsers.png b/images/getting-started/install-browsers.png new file mode 100644 index 00000000000..715e620229f Binary files /dev/null and b/images/getting-started/install-browsers.png differ diff --git a/images/getting-started/install-playwright.png b/images/getting-started/install-playwright.png new file mode 100644 index 00000000000..38c2363909d Binary files /dev/null and b/images/getting-started/install-playwright.png differ diff --git a/images/getting-started/live-debugging.png b/images/getting-started/live-debugging.png new file mode 100644 index 00000000000..41f6d8e7e4e Binary files /dev/null and b/images/getting-started/live-debugging.png differ diff --git a/images/getting-started/pick-locator.png b/images/getting-started/pick-locator.png new file mode 100644 index 00000000000..26408dd356b Binary files /dev/null and b/images/getting-started/pick-locator.png differ diff --git a/images/getting-started/record-at-cursor.png b/images/getting-started/record-at-cursor.png new file mode 100644 index 00000000000..0ab2fc09394 Binary files /dev/null and b/images/getting-started/record-at-cursor.png differ diff --git a/images/getting-started/record-new-test.png b/images/getting-started/record-new-test.png new file mode 100644 index 00000000000..085ff97aa56 Binary files /dev/null and b/images/getting-started/record-new-test.png differ diff --git a/images/getting-started/run-all-tests.png b/images/getting-started/run-all-tests.png new file mode 100644 index 00000000000..d339bf77b56 Binary files /dev/null and b/images/getting-started/run-all-tests.png differ diff --git a/images/getting-started/run-single-test.png b/images/getting-started/run-single-test.png new file mode 100644 index 00000000000..32c226c9605 Binary files /dev/null and b/images/getting-started/run-single-test.png differ diff --git a/images/getting-started/select-projects.png b/images/getting-started/select-projects.png new file mode 100644 index 00000000000..813b8553f04 Binary files /dev/null and b/images/getting-started/select-projects.png differ diff --git a/images/getting-started/selecting-configuration.png b/images/getting-started/selecting-configuration.png new file mode 100644 index 00000000000..6fa106d57d4 Binary files /dev/null and b/images/getting-started/selecting-configuration.png differ diff --git a/images/getting-started/setup-tests.png b/images/getting-started/setup-tests.png new file mode 100644 index 00000000000..f90faa71908 Binary files /dev/null and b/images/getting-started/setup-tests.png differ diff --git a/images/getting-started/show-browser.png b/images/getting-started/show-browser.png new file mode 100644 index 00000000000..c5389d371e7 Binary files /dev/null and b/images/getting-started/show-browser.png differ diff --git a/images/getting-started/testing-sidebar.png b/images/getting-started/testing-sidebar.png new file mode 100644 index 00000000000..3dcc449cca9 Binary files /dev/null and b/images/getting-started/testing-sidebar.png differ diff --git a/images/getting-started/trace-viewer-debug.png b/images/getting-started/trace-viewer-debug.png new file mode 100644 index 00000000000..9dbcbcaf1fa Binary files /dev/null and b/images/getting-started/trace-viewer-debug.png differ diff --git a/images/getting-started/trace-viewer.png b/images/getting-started/trace-viewer.png new file mode 100644 index 00000000000..cb282aa18c7 Binary files /dev/null and b/images/getting-started/trace-viewer.png differ diff --git a/images/getting-started/vscode-extension.png b/images/getting-started/vscode-extension.png new file mode 100644 index 00000000000..9f360e5a0dd Binary files /dev/null and b/images/getting-started/vscode-extension.png differ diff --git a/java/docs/api/class-browsercontext.mdx b/java/docs/api/class-browsercontext.mdx index 71d675fb5cd..fff48de66c0 100644 --- a/java/docs/api/class-browsercontext.mdx +++ b/java/docs/api/class-browsercontext.mdx @@ -808,6 +808,50 @@ BrowserContext.setOffline(offline); --- +### setStorageState {#browser-context-set-storage-state} + +Added in: v1.55browserContext.setStorageState + +Resets storage state in the context by clearing cookies, cache and storage, and then applying the new storage state. + +**Usage** + +```java +BrowserContext.setStorageState(storageState); +``` + +**Arguments** +- `storageState` [String]# + + Populates context with given storage state. This option can be used to initialize context with logged-in information obtained via [BrowserContext.storageState()](/api/class-browsercontext.mdx#browser-context-storage-state). + +**Returns** +- [void]# + +--- + +### setStorageStatePath {#browser-context-set-storage-state-path} + +Added in: v1.55browserContext.setStorageStatePath + +Resets storage state in the context by clearing cookies, cache and storage, and then applying the new storage state from a file. + +**Usage** + +```java +BrowserContext.setStorageStatePath(storageStatePath); +``` + +**Arguments** +- `storageStatePath` [Path]# + + Populates context with given storage state. This option can be used to initialize context with logged-in information obtained via [BrowserContext.storageState()](/api/class-browsercontext.mdx#browser-context-storage-state). Path to the file with saved storage state. + +**Returns** +- [void]# + +--- + ### storageState {#browser-context-storage-state} Added before v1.9browserContext.storageState diff --git a/nodejs/docs/api/class-browsercontext.mdx b/nodejs/docs/api/class-browsercontext.mdx index 510e28809c3..1bf1b9400c8 100644 --- a/nodejs/docs/api/class-browsercontext.mdx +++ b/nodejs/docs/api/class-browsercontext.mdx @@ -850,6 +850,70 @@ await browserContext.setOffline(offline); --- +### setStorageState {#browser-context-set-storage-state} + +Added in: v1.55browserContext.setStorageState + +Resets storage state in the context by clearing cookies, cache and storage, and then applying the new storage state. + +**Usage** + +```js +await browserContext.setStorageState(storageState); +``` + +**Arguments** +- `storageState` [string] | [Object]# + - `cookies` [Array]<[Object]> + - `name` [string] + + + - `value` [string] + + + - `domain` [string] + + Domain and path are required. For the cookie to apply to all subdomains as well, prefix domain with a dot, like this: ".example.com" + - `path` [string] + + Domain and path are required + - `expires` [number] + + Unix time in seconds. + - `httpOnly` [boolean] + + + - `secure` [boolean] + + + - `sameSite` "Strict" | "Lax" | "None" + + sameSite flag + + Cookies to set for context + - `origins` [Array]<[Object]> + - `origin` [string] + + + - `localStorage` [Array]<[Object]> + - `name` [string] + + + - `value` [string] + + + localStorage to set for context + + + Learn more about [storage state and auth](../auth.mdx). + + Populates context with given storage state. This option can be used to initialize context with logged-in information obtained via [browserContext.storageState()](/api/class-browsercontext.mdx#browser-context-storage-state). + +**Returns** +- [Promise]<[void]># + +--- + ### storageState {#browser-context-storage-state} Added before v1.9browserContext.storageState diff --git a/nodejs/docs/ci.mdx b/nodejs/docs/ci.mdx index cbc1beb66fe..1c422e77923 100644 --- a/nodejs/docs/ci.mdx +++ b/nodejs/docs/ci.mdx @@ -101,7 +101,7 @@ jobs: name: 'Playwright Tests' runs-on: ubuntu-latest container: - image: mcr.microsoft.com/playwright:v1.54.1-noble + image: mcr.microsoft.com/playwright:v1.54.2-noble options: --user 1001 steps: - uses: actions/checkout@v4 @@ -335,7 +335,7 @@ trigger: pool: vmImage: ubuntu-latest -container: mcr.microsoft.com/playwright:v1.54.1-noble +container: mcr.microsoft.com/playwright:v1.54.2-noble steps: - task: NodeTool@0 @@ -359,7 +359,7 @@ Running Playwright on CircleCI is very similar to running on GitHub Actions. In executors: pw-noble-development: docker: - - image: mcr.microsoft.com/playwright:v1.54.1-noble + - image: mcr.microsoft.com/playwright:v1.54.2-noble ``` Note: When using the docker agent definition, you are specifying the resource class of where playwright runs to the 'medium' tier [here](https://circleci.com/docs/configuration-reference?#docker-execution-environment). The default behavior of Playwright is to set the number of workers to the detected core count (2 in the case of the medium tier). Overriding the number of workers to greater than this number will cause unnecessary timeouts and failures. @@ -382,7 +382,7 @@ Jenkins supports Docker agents for pipelines. Use the [Playwright Docker image]( ```groovy pipeline { - agent { docker { image 'mcr.microsoft.com/playwright:v1.54.1-noble' } } + agent { docker { image 'mcr.microsoft.com/playwright:v1.54.2-noble' } } stages { stage('e2e-tests') { steps { @@ -399,7 +399,7 @@ pipeline { Bitbucket Pipelines can use public [Docker images as build environments](https://confluence.atlassian.com/bitbucket/use-docker-images-as-build-environments-792298897.html). To run Playwright tests on Bitbucket, use our public Docker image ([see Dockerfile](./docker.mdx)). ```yml -image: mcr.microsoft.com/playwright:v1.54.1-noble +image: mcr.microsoft.com/playwright:v1.54.2-noble ``` ### GitLab CI @@ -412,7 +412,7 @@ stages: tests: stage: test - image: mcr.microsoft.com/playwright:v1.54.1-noble + image: mcr.microsoft.com/playwright:v1.54.2-noble script: ... ``` @@ -427,7 +427,7 @@ stages: tests: stage: test - image: mcr.microsoft.com/playwright:v1.54.1-noble + image: mcr.microsoft.com/playwright:v1.54.2-noble parallel: 7 script: - npm ci @@ -442,7 +442,7 @@ stages: tests: stage: test - image: mcr.microsoft.com/playwright:v1.54.1-noble + image: mcr.microsoft.com/playwright:v1.54.2-noble parallel: matrix: - PROJECT: ['chromium', 'webkit'] @@ -458,7 +458,7 @@ To run Playwright tests on Google Cloud Build, use our public Docker image ([see ```yml steps: -- name: mcr.microsoft.com/playwright:v1.54.1-noble +- name: mcr.microsoft.com/playwright:v1.54.2-noble script: ... env: @@ -476,7 +476,7 @@ type: docker steps: - name: test - image: mcr.microsoft.com/playwright:v1.54.1-noble + image: mcr.microsoft.com/playwright:v1.54.2-noble commands: - npx playwright test ``` diff --git a/nodejs/docs/docker.mdx b/nodejs/docs/docker.mdx index bf5e30764fc..ea8689c7329 100644 --- a/nodejs/docs/docker.mdx +++ b/nodejs/docs/docker.mdx @@ -22,7 +22,7 @@ This Docker image is intended to be used for testing and development purposes on ### Pull the image ```bash -docker pull mcr.microsoft.com/playwright:v1.54.1-noble +docker pull mcr.microsoft.com/playwright:v1.54.2-noble ``` ### Run the image @@ -34,7 +34,7 @@ By default, the Docker image will use the `root` user to run the browsers. This On trusted websites, you can avoid creating a separate user and use root for it since you trust the code which will run on the browsers. ```bash -docker run -it --rm --ipc=host mcr.microsoft.com/playwright:v1.54.1-noble /bin/bash +docker run -it --rm --ipc=host mcr.microsoft.com/playwright:v1.54.2-noble /bin/bash ``` #### Crawling and scraping @@ -42,7 +42,7 @@ docker run -it --rm --ipc=host mcr.microsoft.com/playwright:v1.54.1-noble /bin/b On untrusted websites, it's recommended to use a separate user for launching the browsers in combination with the seccomp profile. Inside the container or if you are using the Docker image as a base image you have to use `adduser` for it. ```bash -docker run -it --rm --ipc=host --user pwuser --security-opt seccomp=seccomp_profile.json mcr.microsoft.com/playwright:v1.54.1-noble /bin/bash +docker run -it --rm --ipc=host --user pwuser --security-opt seccomp=seccomp_profile.json mcr.microsoft.com/playwright:v1.54.2-noble /bin/bash ``` [`seccomp_profile.json`](https://github.com/microsoft/playwright/blob/main/utils/docker/seccomp_profile.json) is needed to run Chromium with sandbox. This is a [default Docker seccomp profile](https://github.com/docker/engine/blob/d0d99b04cf6e00ed3fc27e81fc3d94e7eda70af3/profiles/seccomp/default.json) with extra user namespace cloning permissions: @@ -82,7 +82,7 @@ You can run Playwright Server in Docker while keeping your tests running on the Start the Playwright Server in Docker: ```bash -docker run -p 3000:3000 --rm --init -it --workdir /home/pwuser --user pwuser mcr.microsoft.com/playwright:v1.54.1-noble /bin/sh -c "npx -y playwright@1.54.1 run-server --port 3000 --host 0.0.0.0" +docker run -p 3000:3000 --rm --init -it --workdir /home/pwuser --user pwuser mcr.microsoft.com/playwright:v1.54.2-noble /bin/sh -c "npx -y playwright@1.54.2 run-server --port 3000 --host 0.0.0.0" ``` #### Connecting to the Server @@ -105,7 +105,7 @@ const browser = await playwright['chromium'].connect('ws://127.0.0.1:3000/'); If you need to access local servers from within the Docker container: ```bash -docker run --add-host=hostmachine:host-gateway -p 3000:3000 --rm --init -it --workdir /home/pwuser --user pwuser mcr.microsoft.com/playwright:v1.54.1-noble /bin/sh -c "npx -y playwright@1.54.1 run-server --port 3000 --host 0.0.0.0" +docker run --add-host=hostmachine:host-gateway -p 3000:3000 --rm --init -it --workdir /home/pwuser --user pwuser mcr.microsoft.com/playwright:v1.54.2-noble /bin/sh -c "npx -y playwright@1.54.2 run-server --port 3000 --host 0.0.0.0" ``` This makes `hostmachine` point to the host's localhost. Your tests should use `hostmachine` instead of `localhost` when accessing local servers. @@ -120,9 +120,9 @@ When running tests remotely, ensure the Playwright version in your tests matches See [all available image tags]. We currently publish images with the following tags: -- `:v1.54.1` - Playwright v1.54.1 release docker image based on Ubuntu 24.04 LTS (Noble Numbat). -- `:v1.54.1-noble` - Playwright v1.54.1 release docker image based on Ubuntu 24.04 LTS (Noble Numbat). -- `:v1.54.1-jammy` - Playwright v1.54.1 release docker image based on Ubuntu 22.04 LTS (Jammy Jellyfish). +- `:v1.54.2` - Playwright v1.54.2 release docker image based on Ubuntu 24.04 LTS (Noble Numbat). +- `:v1.54.2-noble` - Playwright v1.54.2 release docker image based on Ubuntu 24.04 LTS (Noble Numbat). +- `:v1.54.2-jammy` - Playwright v1.54.2 release docker image based on Ubuntu 22.04 LTS (Jammy Jellyfish). :::note @@ -146,7 +146,7 @@ To run Playwright inside Docker, you need to have Node.js, [Playwright browsers] ```Dockerfile FROM node:20-bookworm -RUN npx -y playwright@1.54.1 install --with-deps +RUN npx -y playwright@1.54.2 install --with-deps ``` diff --git a/nodejs/docs/getting-started-vscode.mdx b/nodejs/docs/getting-started-vscode.mdx index 0ba718c14c4..2b531623c1e 100644 --- a/nodejs/docs/getting-started-vscode.mdx +++ b/nodejs/docs/getting-started-vscode.mdx @@ -10,213 +10,138 @@ 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.mdx). +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. -## 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. - -![VS Code extension for Playwright](https://github.com/microsoft/playwright/assets/13063165/cab54568-3168-4b3f-bf3d-854976594903) - -Once installed, open the command panel and type: - -```bash -Install Playwright -``` - -![install playwright](https://github.com/microsoft/playwright/assets/13063165/14e91050-24ab-4ff1-a37b-57d7c15e5c35) - -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.mdx) file. You can also choose if you would like to have a GitHub Actions setup to [run your tests on CI](./ci-intro.mdx). - -![choose browsers](https://github.com/microsoft/playwright/assets/13063165/c9e8a25a-e9e8-4419-aeb5-1b8ba58bd71d) - -### Opening the testing sidebar - -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. - -![Testing Sidebar](https://github.com/microsoft/playwright/assets/13063165/d203fe83-6015-4e7a-b816-35d373906b24) - -## 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. - - +## Prerequisites -![run a single test](https://github.com/microsoft/playwright/assets/13063165/69dbccfc-4e9f-40e7-bcdf-7d5c5a11f988) +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/) -### Run tests and show browsers +## Getting Started -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. +### Installation & Setup +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). -![show browsers while running tests](https://github.com/microsoft/playwright/assets/13063165/9f231530-0c43-466a-b944-8cf5102f714a) +![install playwright extension](../images/getting-started/vscode-extension.png) +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. -Use the **Close all browsers** button to close all browsers. +![install playwright](../images/getting-started/install-playwright.png) -### View and run all tests +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. -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. +![install browsers](../images/getting-started/install-browsers.png) -![run all tests](https://github.com/microsoft/playwright/assets/13063165/348e18ff-f819-4caa-8f7e-f16c20724f56) +### Opening the Testing Sidebar -### Running tests on multiple 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. -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. +![Testing Sidebar](../images/getting-started/testing-sidebar.png) -![Projects section in VS Code extension](https://github.com/microsoft/playwright/assets/13063165/58fedea6-a2b9-4942-b2c7-2f3d482210cf) +## Core Features -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. +### Running Your Tests -![Selecting projects to run tests on](https://github.com/microsoft/playwright/assets/13063165/6dc86ef4-6097-481c-9cab-b6e053ec7ea6) + +- **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. -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 a single test](../images/getting-started/run-single-test.png) +- **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. -![Running a test on a specific project](https://github.com/microsoft/playwright/assets/13063165/d29a27ab-07b5-4ca6-b4d7-1ad6d44bf222) +![run all tests](../images/getting-started/run-all-tests.png) +- **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. -### Run tests with trace viewer +![Selecting projects to run tests on](../images/getting-started/select-projects.png) +- **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). -For a better developer experience you can run your tests with the **Show Trace Viewer** option. +![show browsers while running tests](../images/getting-started/show-browser.png) -![run tests with trace viewer](https://github.com/microsoft/playwright/assets/13063165/fab8efa6-d5ef-496d-876d-c99e94e6a6b3) - -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. - -![trace viewer](https://github.com/microsoft/playwright/assets/13063165/ee31a4fe-c786-4d4b-887e-2dcecacfba2c) - -To learn more about the trace viewer see our [Trace Viewer guide](./trace-viewer.mdx). - -## 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 -### 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. - -![error messaging in vs code](https://github.com/microsoft/playwright/assets/13063165/3b8af12a-4805-4573-9d38-92055a0a7e75) - -### 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 in vs code](https://github.com/microsoft/playwright/assets/13063165/7d236ebb-3d2d-4384-b73d-32a2b4e33b9e) - -You can also edit the locators in VS Code and Playwright will show you the changes live in the browser window. - -### 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. +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. + + ![setting debug mode](../images/getting-started/debug-mode.png) +- **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) +- **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. -![setting debug mode](https://github.com/microsoft/playwright/assets/13063165/31640629-efac-4cc7-b8b0-80ae18a3af83) +![error messaging in vs code](../images/getting-started/error-messaging.png) +- **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. +![fix with ai in vs code](../images/getting-started/fix-with-ai.png) +- **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. -![running in debug mode](https://github.com/microsoft/playwright/assets/13063165/b96a9f50-0f4d-49f9-a3d8-f093980a5673) +![trace viewer debugging](../images/getting-started/trace-viewer-debug.png) -![choosing a profile for debugging](https://github.com/microsoft/playwright/assets/13063165/48c1b428-8dd2-4229-9eb5-24f7168db834) +To learn more, see our [Trace Viewer guide](./trace-viewer.mdx). -To learn more about debugging, see [Debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging). +### Generating Tests with CodeGen -### Debug with trace viewer - -For a better developer experience you can debug your tests with the **Show Trace Viewer** option. - -![run tests with trace viewer](https://github.com/microsoft/playwright/assets/13063165/fab8efa6-d5ef-496d-876d-c99e94e6a6b3) - -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. - -![trace viewer](https://github.com/microsoft/playwright/assets/13063165/ee31a4fe-c786-4d4b-887e-2dcecacfba2c) - -To learn more about the trace viewer see our [Trace Viewer guide](./trace-viewer.mdx). - -## 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.mdx) 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. +- **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 - -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 a new test](https://github.com/microsoft/playwright/assets/13063165/0407f112-e1cd-41e7-a05d-ae64e24d27ed) - -### 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. - -![record at cursor](https://github.com/microsoft/playwright/assets/13063165/96933ea1-4c84-453a-acd7-22b4d3bde185) - -### Picking a locator - -Pick a [locator](./locators.mdx) 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. - -![pick locators](https://github.com/microsoft/playwright/assets/13063165/9a1b2da9-9ac7-4def-a9e0-f94770364fc2) - -Playwright will look at your page and figure out the best locator, prioritizing [role, text and test id locators](./locators.mdx). 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.mdx) 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. - -![setup tests in vscode](https://github.com/microsoft/playwright/assets/13063165/7a9eccd5-a5b3-431f-9eff-9b2971501e07) - -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. - -![running setup tests in vscode](https://github.com/microsoft/playwright/assets/13063165/a54b3868-3f9f-4e74-8d42-a93443f099fc) - -### Running setup tests only once - -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. +![record a new test](../images/getting-started/record-new-test.png) +- **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) +- **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. -![deselecting setup tests in vscode](https://github.com/microsoft/playwright/assets/13063165/ebc50e38-c98d-4538-82fe-ec08491f8487) +![pick locators](../images/getting-started/pick-locator.png) -## Global Setup +To learn more, see our [CodeGen guide](./codegen.mdx). -**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 -![running global setup](https://github.com/microsoft/playwright/assets/13063165/bcf5fec7-2d7d-4cb9-a277-5f41e19b8d52) +Use [project dependencies](./test-projects.mdx) 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 +![setup tests in vscode](../images/getting-started/setup-tests.png) -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.mdx). -![Selecting a configuration file](https://github.com/microsoft/playwright/assets/13063165/ff9ff838-d27a-403d-b939-94e6c295e1d7) +### 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. -![Switching between configuration files](https://github.com/microsoft/playwright/assets/13063165/70930de5-0a0c-45e0-a6ee-b51f727f0e35) +![running global setup](../images/getting-started/global-setup.png) -To run all tests from all configurations click on the grey triangle at the top of the test explorer. +### Multiple Configurations -![Running all tests from all configurations](https://github.com/microsoft/playwright/assets/13063165/b3de4ce1-d311-4527-b2c7-b3e2f179a685) +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. +![Selecting a configuration file](../images/getting-started/selecting-configuration.png) -![Recording a test for a specific configuration file](https://github.com/microsoft/playwright/assets/13063165/a8ecbcd1-fab8-4012-bdaa-428951f233a2) +## 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 -- [Write tests using web first assertions, page fixtures and locators](./writing-tests.mdx) -- [Run your tests on CI](./ci-intro.mdx) -- [Learn more about the Trace Viewer](./trace-viewer.mdx) +## What's Next +- [Write tests using web-first assertions, page fixtures, and locators](./writing-tests.mdx) +- [Run your tests on CI](./ci-intro.mdx) +- [Learn more about the Trace Viewer](./trace-viewer.mdx) [Accessibility]: /api/class-accessibility.mdx "Accessibility" diff --git a/nodejs/docs/running-tests.mdx b/nodejs/docs/running-tests.mdx index 36c0f2cb417..7f3345744a0 100644 --- a/nodejs/docs/running-tests.mdx +++ b/nodejs/docs/running-tests.mdx @@ -97,9 +97,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.mdx#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.mdx) guide for more details. -![Playwright VS Code extension](https://github.com/microsoft/playwright/assets/13063165/47726e70-683b-4bd5-94de-7d03dd45c30f) +![install playwright extension](../images/getting-started/vscode-extension.png) ## Debugging tests diff --git a/python/docs/api/class-browsercontext.mdx b/python/docs/api/class-browsercontext.mdx index 6d3d5e37dcd..315b94e9313 100644 --- a/python/docs/api/class-browsercontext.mdx +++ b/python/docs/api/class-browsercontext.mdx @@ -1179,6 +1179,70 @@ browser_context.set_offline(offline) --- +### set_storage_state {#browser-context-set-storage-state} + +Added in: v1.55browserContext.set_storage_state + +Resets storage state in the context by clearing cookies, cache and storage, and then applying the new storage state. + +**Usage** + +```python +browser_context.set_storage_state(storage_state) +``` + +**Arguments** +- `storage_state` [Union]\[[str], [pathlib.Path]\] | [Dict]# + - `cookies` [List]\[[Dict]\] + - `name` [str] + + + - `value` [str] + + + - `domain` [str] + + Domain and path are required. For the cookie to apply to all subdomains as well, prefix domain with a dot, like this: ".example.com" + - `path` [str] + + Domain and path are required + - `expires` [float] + + Unix time in seconds. + - `httpOnly` [bool] + + + - `secure` [bool] + + + - `sameSite` "Strict" | "Lax" | "None" + + sameSite flag + + Cookies to set for context + - `origins` [List]\[[Dict]\] + - `origin` [str] + + + - `localStorage` [List]\[[Dict]\] + - `name` [str] + + + - `value` [str] + + + localStorage to set for context + + + Learn more about [storage state and auth](../auth.mdx). + + Populates context with given storage state. This option can be used to initialize context with logged-in information obtained via [browser_context.storage_state()](/api/class-browsercontext.mdx#browser-context-storage-state). + +**Returns** +- [NoneType]# + +--- + ### storage_state {#browser-context-storage-state} Added before v1.9browserContext.storage_state