diff --git a/dotnet/docs/ci-intro.mdx b/dotnet/docs/ci-intro.mdx index 98e1cd0023e..8bc37bbc5ce 100644 --- a/dotnet/docs/ci-intro.mdx +++ b/dotnet/docs/ci-intro.mdx @@ -9,7 +9,7 @@ import ProgressiveImage from '@theme/ProgressiveImage'; ## Introduction -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 - [How to set up GitHub Actions](/ci-intro.mdx#setting-up-github-actions) @@ -18,7 +18,7 @@ Playwright tests can be run on any CI provider. In this section we will cover ru ## Setting up GitHub Actions -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 title=".github/workflows/playwright.yml" name: Playwright Tests @@ -56,14 +56,14 @@ 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. ###### ![dotnet repo on github](https://github.com/microsoft/playwright/assets/13063165/4f1b4cc3-b850-4d60-a99e-24057eaf91ad) ## 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. ###### ![opening the workflow](https://github.com/microsoft/playwright/assets/13063165/71793c09-0815-4faa-866b-85684a1f87e5) @@ -74,7 +74,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. ###### ![viewing the test logs](https://github.com/microsoft/playwright/assets/13063165/ba2d8d7b-ffce-42de-95e0-bcb35c421975) @@ -84,11 +84,11 @@ Clicking on the workflow run will show you the all the actions that GitHub perfo You can upload Traces which get created on your CI like GitHub Actions as artifacts. This requires [starting and stopping the trace](./trace-viewer-intro#recording-a-trace). We recommend only recording traces for failing tests. Once your traces have been uploaded to CI, they can then be downloaded and opened using [trace.playwright.dev](https://trace.playwright.dev), which 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/84150084-5019-470a-8449-b61d206bfbb0) + ## Properly handling Secrets -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. 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. +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 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 - [Learn how to use Locators](./locators.mdx) diff --git a/dotnet/docs/codegen-intro.mdx b/dotnet/docs/codegen-intro.mdx index dc37e104fe0..2c90212ac51 100644 --- a/dotnet/docs/codegen-intro.mdx +++ b/dotnet/docs/codegen-intro.mdx @@ -9,7 +9,7 @@ import ProgressiveImage from '@theme/ProgressiveImage'; ## 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** - [How to record a test](/codegen.mdx#recording-a-test) @@ -17,7 +17,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 pwsh bin/Debug/net8.0/playwright.ps1 codegen demo.playwright.dev/todomvc @@ -25,40 +25,40 @@ 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 ###### -![recording a test](https://github.com/microsoft/playwright/assets/13063165/53bdfb6f-d462-4ce0-ab95-0619faaebf1e) + ###### -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.mdx). +To learn more about generating tests, check out our detailed guide on [Codegen](./codegen.mdx). ### Generating locators You can generate [locators](/locators.mdx) 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 ###### -![picking a locator](https://github.com/microsoft/playwright/assets/13063165/1478f56f-422f-4276-9696-0674041f11dc) + ### 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.mdx#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.mdx#emulation) guide to learn more. ## What's Next - [See a trace of your tests](./trace-viewer-intro.mdx) diff --git a/images/getting-started/codegen-csharp.png b/images/getting-started/codegen-csharp.png new file mode 100644 index 00000000000..96946f491ab Binary files /dev/null and b/images/getting-started/codegen-csharp.png differ diff --git a/images/getting-started/codegen-java.png b/images/getting-started/codegen-java.png new file mode 100644 index 00000000000..539ba06e30a Binary files /dev/null and b/images/getting-started/codegen-java.png differ diff --git a/images/getting-started/codgen-js.png b/images/getting-started/codgen-js.png new file mode 100644 index 00000000000..e6a3938de92 Binary files /dev/null and b/images/getting-started/codgen-js.png differ diff --git a/images/getting-started/codgen-python.png b/images/getting-started/codgen-python.png new file mode 100644 index 00000000000..5ecafe2b7ba Binary files /dev/null and b/images/getting-started/codgen-python.png differ diff --git a/images/getting-started/debug-mode.png b/images/getting-started/debug-mode.png index 73c48a568df..d2ec8a9c19c 100644 Binary files a/images/getting-started/debug-mode.png 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 index ced1f2f8c8a..7d87662142b 100644 Binary files a/images/getting-started/error-messaging.png 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 index d1adcdbe381..556a1ad04af 100644 Binary files a/images/getting-started/fix-with-ai.png 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 index 35d6aa88570..34119260ed0 100644 Binary files a/images/getting-started/global-setup.png and b/images/getting-started/global-setup.png differ diff --git a/images/getting-started/html-report-basic.png b/images/getting-started/html-report-basic.png new file mode 100644 index 00000000000..03d8c5e33a2 Binary files /dev/null and b/images/getting-started/html-report-basic.png differ diff --git a/images/getting-started/html-report-detail.png b/images/getting-started/html-report-detail.png new file mode 100644 index 00000000000..6e75f25eb2c Binary files /dev/null and b/images/getting-started/html-report-detail.png differ diff --git a/images/getting-started/html-report-failed-tests.png b/images/getting-started/html-report-failed-tests.png new file mode 100644 index 00000000000..572854db204 Binary files /dev/null and b/images/getting-started/html-report-failed-tests.png differ diff --git a/images/getting-started/html-report-open.png b/images/getting-started/html-report-open.png new file mode 100644 index 00000000000..6e75f25eb2c Binary files /dev/null and b/images/getting-started/html-report-open.png differ diff --git a/images/getting-started/html-report-trace.png b/images/getting-started/html-report-trace.png new file mode 100644 index 00000000000..d3a3273ac4a Binary files /dev/null and b/images/getting-started/html-report-trace.png differ diff --git a/images/getting-started/html-report.png b/images/getting-started/html-report.png new file mode 100644 index 00000000000..e7cac492d96 Binary files /dev/null and b/images/getting-started/html-report.png differ diff --git a/images/getting-started/install-browsers.png b/images/getting-started/install-browsers.png index 715e620229f..83395893d01 100644 Binary files a/images/getting-started/install-browsers.png 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 index 38c2363909d..68a7b794256 100644 Binary files a/images/getting-started/install-playwright.png 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 index 41f6d8e7e4e..89d8c0a9f9e 100644 Binary files a/images/getting-started/live-debugging.png and b/images/getting-started/live-debugging.png differ diff --git a/images/getting-started/pick-locator-csharp.png b/images/getting-started/pick-locator-csharp.png new file mode 100644 index 00000000000..800f3484f77 Binary files /dev/null and b/images/getting-started/pick-locator-csharp.png differ diff --git a/images/getting-started/pick-locator-java.png b/images/getting-started/pick-locator-java.png new file mode 100644 index 00000000000..13810f7a145 Binary files /dev/null and b/images/getting-started/pick-locator-java.png differ diff --git a/images/getting-started/pick-locator-js.png b/images/getting-started/pick-locator-js.png new file mode 100644 index 00000000000..fbdb652c3b8 Binary files /dev/null and b/images/getting-started/pick-locator-js.png differ diff --git a/images/getting-started/pick-locator-python.png b/images/getting-started/pick-locator-python.png new file mode 100644 index 00000000000..b99697f5a3b Binary files /dev/null and b/images/getting-started/pick-locator-python.png differ diff --git a/images/getting-started/pick-locator.png b/images/getting-started/pick-locator.png index 26408dd356b..8ac237d42a3 100644 Binary files a/images/getting-started/pick-locator.png 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 index 0ab2fc09394..ad9e4c83229 100644 Binary files a/images/getting-started/record-at-cursor.png 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 index 085ff97aa56..d612fde7659 100644 Binary files a/images/getting-started/record-new-test.png and b/images/getting-started/record-new-test.png differ diff --git a/images/getting-started/record-test-csharp.png b/images/getting-started/record-test-csharp.png new file mode 100644 index 00000000000..96946f491ab Binary files /dev/null and b/images/getting-started/record-test-csharp.png differ diff --git a/images/getting-started/record-test-java.png b/images/getting-started/record-test-java.png new file mode 100644 index 00000000000..539ba06e30a Binary files /dev/null and b/images/getting-started/record-test-java.png differ diff --git a/images/getting-started/record-test-js.png b/images/getting-started/record-test-js.png new file mode 100644 index 00000000000..e6a3938de92 Binary files /dev/null and b/images/getting-started/record-test-js.png differ diff --git a/images/getting-started/record-test-python.png b/images/getting-started/record-test-python.png new file mode 100644 index 00000000000..5ecafe2b7ba Binary files /dev/null and b/images/getting-started/record-test-python.png differ diff --git a/images/getting-started/run-all-tests.png b/images/getting-started/run-all-tests.png index d339bf77b56..86c2dd886ba 100644 Binary files a/images/getting-started/run-all-tests.png 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 index 32c226c9605..b5609c4358f 100644 Binary files a/images/getting-started/run-single-test.png and b/images/getting-started/run-single-test.png differ diff --git a/images/getting-started/run-tests-cli.png b/images/getting-started/run-tests-cli.png new file mode 100644 index 00000000000..d3dee686d97 Binary files /dev/null and b/images/getting-started/run-tests-cli.png differ diff --git a/images/getting-started/run-tests-debug.png b/images/getting-started/run-tests-debug.png new file mode 100644 index 00000000000..75d94bee956 Binary files /dev/null and b/images/getting-started/run-tests-debug.png differ diff --git a/images/getting-started/run-tests-pick-locator.png b/images/getting-started/run-tests-pick-locator.png new file mode 100644 index 00000000000..9c9a6dc9d4a Binary files /dev/null and b/images/getting-started/run-tests-pick-locator.png differ diff --git a/images/getting-started/select-projects.png b/images/getting-started/select-projects.png index 813b8553f04..4a6fd6f1683 100644 Binary files a/images/getting-started/select-projects.png 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 index 6fa106d57d4..472a6359644 100644 Binary files a/images/getting-started/selecting-configuration.png 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 index f90faa71908..675cc01e29c 100644 Binary files a/images/getting-started/setup-tests.png 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 index c5389d371e7..6dee4026800 100644 Binary files a/images/getting-started/show-browser.png 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 index 3dcc449cca9..f817824de30 100644 Binary files a/images/getting-started/testing-sidebar.png 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 index 9dbcbcaf1fa..5321f8aa880 100644 Binary files a/images/getting-started/trace-viewer-debug.png and b/images/getting-started/trace-viewer-debug.png differ diff --git a/images/getting-started/trace-viewer-failed-test.png b/images/getting-started/trace-viewer-failed-test.png new file mode 100644 index 00000000000..6c130b1f2b0 Binary files /dev/null and b/images/getting-started/trace-viewer-failed-test.png differ diff --git a/images/getting-started/trace-viewer.png b/images/getting-started/trace-viewer.png index cb282aa18c7..8781423c9cc 100644 Binary files a/images/getting-started/trace-viewer.png and b/images/getting-started/trace-viewer.png differ diff --git a/images/getting-started/ui-mode-error.png b/images/getting-started/ui-mode-error.png new file mode 100644 index 00000000000..fa293f87942 Binary files /dev/null and b/images/getting-started/ui-mode-error.png differ diff --git a/images/getting-started/ui-mode-pick-locator.png b/images/getting-started/ui-mode-pick-locator.png new file mode 100644 index 00000000000..2a4df09bcb7 Binary files /dev/null and b/images/getting-started/ui-mode-pick-locator.png differ diff --git a/images/getting-started/ui-mode.png b/images/getting-started/ui-mode.png new file mode 100644 index 00000000000..f9e83dbe72a Binary files /dev/null and b/images/getting-started/ui-mode.png differ diff --git a/images/getting-started/vscode-extension.png b/images/getting-started/vscode-extension.png index 9f360e5a0dd..106fb690e89 100644 Binary files a/images/getting-started/vscode-extension.png and b/images/getting-started/vscode-extension.png differ diff --git a/images/vscode-projects-section.png b/images/vscode-projects-section.png index d304dd04f9d..cffe4ec1811 100644 Binary files a/images/vscode-projects-section.png and b/images/vscode-projects-section.png differ diff --git a/java/docs/ci-intro.mdx b/java/docs/ci-intro.mdx index 60f5abee200..cfb2a0c6d60 100644 --- a/java/docs/ci-intro.mdx +++ b/java/docs/ci-intro.mdx @@ -9,7 +9,7 @@ import ProgressiveImage from '@theme/ProgressiveImage'; ## Introduction -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 - [How to set up GitHub Actions](/ci-intro.mdx#setting-up-github-actions) @@ -18,7 +18,7 @@ Playwright tests can be run on any CI provider. In this section we will cover ru ## Setting up GitHub Actions -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 title=".github/workflows/playwright.yml" name: Playwright Tests @@ -56,21 +56,21 @@ 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. ###### Create a Repo and Push to GitHub ## 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. ###### ![opening the workflow](https://user-images.githubusercontent.com/13063165/183423783-58bf2008-514e-4f96-9c12-c9a55703960c.png) ## 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. ###### ![Viewing Test Logs](https://user-images.githubusercontent.com/13063165/183423783-58bf2008-514e-4f96-9c12-c9a55703960c.png) @@ -79,11 +79,11 @@ Clicking on the workflow run will show you the all the actions that GitHub perfo [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) + ## Properly handling Secrets -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. 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. +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 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 - [Learn how to use Locators](./locators.mdx) diff --git a/java/docs/codegen-intro.mdx b/java/docs/codegen-intro.mdx index a30862e980e..98ae1195323 100644 --- a/java/docs/codegen-intro.mdx +++ b/java/docs/codegen-intro.mdx @@ -9,7 +9,7 @@ import ProgressiveImage from '@theme/ProgressiveImage'; ## 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** - [How to record a test](/codegen.mdx#recording-a-test) @@ -17,7 +17,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 mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="codegen demo.playwright.dev/todomvc" @@ -25,40 +25,40 @@ mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="co ### 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 ###### -![recording a test](https://github.com/microsoft/playwright/assets/13063165/ec9c4071-4af8-4ae7-8b36-aebcc29bdbbb) + ###### -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.mdx). +To learn more about generating tests, check out our detailed guide on [Codegen](./codegen.mdx). ### Generating locators You can generate [locators](/locators.mdx) 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 ###### -![picking a locator](https://github.com/microsoft/playwright/assets/13063165/733b48fd-5edf-4150-93f0-018adc52b6ff) + ### 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.mdx#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.mdx#emulation) guide to learn more. ## What's Next - [See a trace of your tests](./trace-viewer-intro.mdx) diff --git a/nodejs/docs/ci-intro.mdx b/nodejs/docs/ci-intro.mdx index abbeafdf1ba..2ddba34a231 100644 --- a/nodejs/docs/ci-intro.mdx +++ b/nodejs/docs/ci-intro.mdx @@ -9,7 +9,7 @@ import ProgressiveImage from '@theme/ProgressiveImage'; ## Introduction -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.mdx). +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.mdx). #### You will learn - [How to set up GitHub Actions](/ci-intro.mdx#setting-up-github-actions) @@ -20,7 +20,7 @@ Playwright tests can be run on any CI provider. This guide covers one way of run ## Setting up GitHub Actions -When [installing Playwright](./intro.mdx) using the [VS Code extension](./getting-started-vscode.mdx) 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.mdx) using the [VS Code extension](./getting-started-vscode.mdx) 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 title=".github/workflows/playwright.yml" name: Playwright Tests @@ -64,38 +64,38 @@ To learn more about this, see ["Understanding GitHub Actions"](https://docs.gith ## 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. ###### Create a Repo and Push to GitHub ## 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. ###### ![opening the workflow](https://user-images.githubusercontent.com/13063165/183423783-58bf2008-514e-4f96-9c12-c9a55703960c.png) ## 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. ###### ![Viewing Test Logs](https://user-images.githubusercontent.com/13063165/183423783-58bf2008-514e-4f96-9c12-c9a55703960c.png) ## HTML Report -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 -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. Downloading the HTML Report ### Viewing the HTML Report -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 npx playwright show-report name-of-my-extracted-playwright-report @@ -103,7 +103,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.mdx#html-reporter) +To learn more about reports, check out our detailed guide on [HTML Reporter](/test-reporters.mdx#html-reporter) ## Viewing the Trace @@ -154,7 +154,7 @@ This step will not work for pull requests created from a forked repository becau ## Properly handling Secrets -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. 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. +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 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 - [Learn how to use Locators](./locators.mdx) diff --git a/nodejs/docs/codegen-intro.mdx b/nodejs/docs/codegen-intro.mdx index 428ab453539..71e68194d1f 100644 --- a/nodejs/docs/codegen-intro.mdx +++ b/nodejs/docs/codegen-intro.mdx @@ -9,7 +9,7 @@ import ProgressiveImage from '@theme/ProgressiveImage'; ## 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** - [How to record a test](/codegen.mdx#recording-a-test) @@ -17,7 +17,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 npx playwright codegen demo.playwright.dev/todomvc @@ -25,40 +25,40 @@ npx playwright 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 ###### -![Recording a test](https://github.com/microsoft/playwright/assets/13063165/34a79ea1-639e-4cb3-8115-bfdc78e3d34d) + ###### -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.mdx). +To learn more about generating tests, check out our detailed guide on [Codegen](./codegen.mdx). ### Generating locators You can generate [locators](/locators.mdx) 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 ###### -![picking a locator](https://github.com/microsoft/playwright/assets/13063165/2c8a12e2-4e98-4fdd-af92-1d73ae696d86) + ### 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.mdx#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.mdx#emulation) guide to learn more. ## What's Next - [See a trace of your tests](./trace-viewer-intro.mdx) diff --git a/nodejs/docs/intro.mdx b/nodejs/docs/intro.mdx index f977b941770..838c79a776a 100644 --- a/nodejs/docs/intro.mdx +++ b/nodejs/docs/intro.mdx @@ -9,11 +9,11 @@ import ProgressiveImage from '@theme/ProgressiveImage'; ## 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.mdx#installing-playwright) -- [What's Installed](/intro.mdx#whats-installed) +- [What's installed](/intro.mdx#whats-installed) - [How to run the example test](/intro.mdx#running-the-example-test) - [How to open the HTML test report](/intro.mdx#html-test-reports) @@ -23,7 +23,7 @@ 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. @@ -53,37 +53,39 @@ pnpm create playwright -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.mdx). +You can also create and run tests with the [VS Code Extension](./getting-started-vscode.mdx). ## 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.mdx) 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.mdx) 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.mdx). 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.mdx)). Output and aggregated results display in the terminal. @@ -113,11 +115,19 @@ pnpm exec playwright test -![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.mdx) to learn more about running tests in headed mode, running multiple tests, running specific tests etc. + + +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.mdx) for details on filtering, headed mode, sharding and retries. ## HTML Test Reports -After your test completes, an [HTML Reporter](./test-reporters.mdx#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.mdx#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. @@ -147,11 +157,11 @@ pnpm exec playwright show-report -![HTML Report](https://github.com/microsoft/playwright/assets/13063165/38ec17a7-9e61-4002-b137-a93812765501) + ## Running the Example Test in UI Mode -Run your tests with [UI Mode](./test-ui-mode.mdx) for a better developer experience with time travel debugging, watch mode and more. +Run tests with [UI Mode](./test-ui-mode.mdx) for watch mode, live step view, time travel debugging and more. @@ -181,13 +191,13 @@ pnpm exec playwright test --ui -![UI Mode](https://github.com/microsoft/playwright/assets/13063165/c5b501cc-4f5d-485a-87cc-66044c651786) + -Check out or [detailed guide on UI Mode](./test-ui-mode.mdx) to learn more about its features. +See the [detailed guide on UI Mode](./test-ui-mode.mdx) 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: @@ -195,7 +205,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 ``` @@ -205,7 +214,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 ``` @@ -215,7 +223,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 ``` @@ -223,7 +230,7 @@ pnpm exec playwright install --with-deps -You can always check which version of Playwright you have by running the following command: +Check your installed version: @@ -254,16 +261,16 @@ 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.mdx) -- [Run single test, multiple tests, headed mode](./running-tests.mdx) +- [Write tests using web-first assertions, fixtures and locators](./writing-tests.mdx) +- [Run single or multiple tests; headed mode](./running-tests.mdx) - [Generate tests with Codegen](./codegen-intro.mdx) -- [See a trace of your tests](./trace-viewer-intro.mdx) +- [View a trace of your tests](./trace-viewer-intro.mdx) [Accessibility]: /api/class-accessibility.mdx "Accessibility" diff --git a/nodejs/docs/running-tests.mdx b/nodejs/docs/running-tests.mdx index 4259e5107d6..2d6a434b3d7 100644 --- a/nodejs/docs/running-tests.mdx +++ b/nodejs/docs/running-tests.mdx @@ -9,7 +9,7 @@ import ProgressiveImage from '@theme/ProgressiveImage'; ## 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.mdx) 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.mdx) using the `--ui` flag to see a full trace of your tests. **You will learn** - [How to run tests from the command line](/running-tests.mdx#command-line) @@ -20,13 +20,13 @@ With Playwright you can run a single test, a set of tests or all tests. Tests ca ### 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) + ### Run tests in UI mode @@ -36,13 +36,13 @@ We highly recommend running your tests with [UI Mode](./test-ui-mode.mdx) for a npx playwright test --ui ``` -![UI Mode](https://github.com/microsoft/playwright/assets/13063165/c5b501cc-4f5d-485a-87cc-66044c651786) + -Check out or [detailed guide on UI Mode](./test-ui-mode.mdx) to learn more about its features. +Check out our [detailed guide on UI Mode](./test-ui-mode.mdx) 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 @@ -50,13 +50,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 @@ -64,13 +64,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/ @@ -104,21 +104,21 @@ Tests can be run right from VS Code using the [VS Code extension](https://market ## 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.mdx). Playwright comes with [UI Mode](./test-ui-mode.mdx), 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.mdx#playwright-inspector), which allows you to step through Playwright API calls, see their debug logs and explore [locators](./locators.mdx). +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.mdx). Playwright comes with [UI Mode](./test-ui-mode.mdx), 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.mdx#playwright-inspector), which allows you to step through Playwright API calls, see their debug logs, and explore [locators](./locators.mdx). ### Debug tests in UI mode -We highly recommend debugging your tests with [UI Mode](./test-ui-mode.mdx) 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.mdx) 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) + -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) + Check out our [detailed guide on UI Mode](./test-ui-mode.mdx) to learn more about its features. @@ -130,11 +130,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) + -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 @@ -146,25 +146,25 @@ 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) + -Check out our [debugging guide](./debug.mdx) to learn more about debugging with the [VS Code debugger](./debug.mdx#vs-code-debugger), UI Mode and the [Playwright Inspector](./debug.mdx#playwright-inspector) as well as debugging with [Browser Developer tools](./debug.mdx#browser-developer-tools). +Check out our [debugging guide](./debug.mdx) to learn more about debugging with the [VS Code debugger](./debug.mdx#vs-code-debugger), UI Mode, and the [Playwright Inspector](./debug.mdx#playwright-inspector) as well as debugging with [Browser Developer tools](./debug.mdx#browser-developer-tools). ## Test reports -The [HTML Reporter](./test-reporters.mdx#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.mdx#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) + -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) + ## What's next - [Generate tests with Codegen](./codegen-intro.mdx) diff --git a/nodejs/docs/trace-viewer-intro.mdx b/nodejs/docs/trace-viewer-intro.mdx index d40c1866eb7..49c52a18c91 100644 --- a/nodejs/docs/trace-viewer-intro.mdx +++ b/nodejs/docs/trace-viewer-intro.mdx @@ -11,7 +11,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** - [How to record a trace](/trace-viewer-intro.mdx#recording-a-trace) @@ -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.mdx#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.mdx#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.mdx). -Traces are normally run in a Continuous Integration(CI) environment, because locally you can use [UI Mode](/test-ui-mode.mdx) for developing and debugging tests. However, if you want to run traces locally without using [UI Mode](/test-ui-mode.mdx), 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.mdx) for developing and debugging tests. However, if you want to run traces locally without using [UI Mode](/test-ui-mode.mdx), 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,23 +53,23 @@ 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) + -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) + -To learn more about reporters check out our detailed guide on reporters including the [HTML Reporter](/test-reporters.mdx#html-reporter). +To learn more about reporters, check out our detailed guide on reporters including the [HTML Reporter](/test-reporters.mdx#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) + -To learn more about traces check out our detailed guide on [Trace Viewer](/trace-viewer.mdx). +To learn more about traces, check out our detailed guide on [Trace Viewer](/trace-viewer.mdx). ## What's next - [Run tests on CI with GitHub Actions](/ci-intro.mdx) diff --git a/nodejs/docs/writing-tests.mdx b/nodejs/docs/writing-tests.mdx index 13ff0fa89e7..3b960f614e8 100644 --- a/nodejs/docs/writing-tests.mdx +++ b/nodejs/docs/writing-tests.mdx @@ -9,15 +9,9 @@ import ProgressiveImage from '@theme/ProgressiveImage'; ## Introduction -Playwright tests are simple, they -- **perform actions**, and -- **assert the state** against expectations. +Playwright tests are simple: they **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.mdx) 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.mdx) 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** - [How to write the first test](/writing-tests.mdx#first-test) @@ -59,17 +53,19 @@ 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/'); ``` -Playwright will wait for page to reach the load state prior to moving forward. Learn more about the [page.goto()](/api/class-page.mdx#page-goto) options. +Playwright waits for the page to reach the load state before continuing. Learn more about [page.goto()](/api/class-page.mdx#page-goto) options. ### Interactions -Performing actions starts with locating the elements. Playwright uses [Locators API](./locators.mdx) for that. Locators represent a way to find element(s) on the page at any moment, learn more about the [different types](./locators.mdx) of locators available. Playwright will wait for the element to be [actionable](./actionability.mdx) 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.mdx) for that. Locators represent a way to find element(s) on the page at any moment. Learn more about the [different types](./locators.mdx) of locators available. + +Playwright waits for the element to be [actionable](./actionability.mdx) before performing the action, so you don't need to wait for it to become available. ```js // Create a locator. @@ -87,7 +83,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.mdx) section to learn more about them. +Here are the most popular Playwright actions. For the complete list, check the [Locator API](./api/class-locator.mdx) section. | Action | Description | | :- | :- | @@ -105,19 +101,13 @@ This is the list of the most popular Playwright actions. Note that there are man Playwright includes [test assertions](./test-assertions.mdx) 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 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.mdx) to get familiar with: +Here are the most popular async assertions. For the complete list, see [assertions guide](./test-assertions.mdx): | Assertion | Description | | :- | :- | @@ -132,9 +122,15 @@ Here is the list of the most popular async assertions. Note that there are [many | [expect(page).toHaveTitle()](/api/class-pageassertions.mdx#page-assertions-to-have-title) | Page has title | | [expect(page).toHaveURL()](/api/class-pageassertions.mdx#page-assertions-to-have-url) | 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.mdx) 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.mdx) 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'; diff --git a/python/docs/ci-intro.mdx b/python/docs/ci-intro.mdx index 046b5560acb..5c2d47ea008 100644 --- a/python/docs/ci-intro.mdx +++ b/python/docs/ci-intro.mdx @@ -9,7 +9,7 @@ import ProgressiveImage from '@theme/ProgressiveImage'; ## Introduction -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 - [How to set up GitHub Actions](/ci-intro.mdx#setting-up-github-actions) @@ -18,7 +18,7 @@ Playwright tests can be run on any CI provider. In this section we will cover ru ## Setting up GitHub Actions -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 title=".github/workflows/playwright.yml" name: Playwright Tests @@ -63,21 +63,21 @@ 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. ###### Create a Repo and Push to GitHub ## 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. ###### ![opening the workflow](https://user-images.githubusercontent.com/13063165/183423783-58bf2008-514e-4f96-9c12-c9a55703960c.png) ## 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. ###### ![Viewing Test Logs](https://user-images.githubusercontent.com/13063165/183423783-58bf2008-514e-4f96-9c12-c9a55703960c.png) @@ -86,11 +86,11 @@ Clicking on the workflow run will show you the all the actions that GitHub perfo [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) + ## Properly handling Secrets -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. 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. +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 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 - [Learn how to use Locators](./locators.mdx) diff --git a/python/docs/codegen-intro.mdx b/python/docs/codegen-intro.mdx index fe51684102d..b06b8f81a30 100644 --- a/python/docs/codegen-intro.mdx +++ b/python/docs/codegen-intro.mdx @@ -9,7 +9,7 @@ import ProgressiveImage from '@theme/ProgressiveImage'; ## 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** - [How to record a test](/codegen.mdx#recording-a-test) @@ -17,7 +17,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 playwright codegen demo.playwright.dev/todomvc @@ -25,40 +25,40 @@ playwright 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 ###### -![recording a test](https://github.com/microsoft/playwright/assets/13063165/9751b609-6e4c-486b-a961-f86f177b1d58) + ###### -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.mdx). +To learn more about generating tests, check out our detailed guide on [Codegen](./codegen.mdx). ### Generating locators You can generate [locators](/locators.mdx) 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 ###### -![picking a locator](https://github.com/microsoft/playwright/assets/13063165/95d11f48-96a4-46b9-9c2a-63c3aa4fdce7) + ### 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.mdx#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.mdx#emulation) guide to learn more. ## What's Next - [See a trace of your tests](./trace-viewer-intro.mdx)