diff --git a/docs/src/codegen-intro.md b/docs/src/codegen-intro.md index 84e0fe196cc15..f995d03bef2d5 100644 --- a/docs/src/codegen-intro.md +++ b/docs/src/codegen-intro.md @@ -7,11 +7,18 @@ Playwright comes with the ability to generate tests out of the box and is a grea **You will learn** -- [How to generate tests with Codegen](/codegen.md#running-codegen) +- [How to record a test](/codegen.md#recording-a-test) +- [How to generate locators](/codegen.md#generate-locators) + ## 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. + ```bash js npx playwright codegen demo.playwright.dev/todomvc ``` @@ -28,12 +35,29 @@ playwright codegen demo.playwright.dev/todomvc pwsh bin/Debug/netX/playwright.ps1 codegen demo.playwright.dev/todomvc ``` -Run `codegen` and perform actions in the browser. Playwright will generate the code for the user interactions. `Codegen` will attempt to generate resilient text-based selectors. +### 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. + +###### +* langs: js + +Recording a test + +###### +* langs: java + +Recording a test + +###### +* langs: python + +Recording a test + +###### +* langs: csharp + +Screenshot 2023-01-16 at 20 42 26 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. @@ -41,6 +65,39 @@ Use the **clear** button to clear the code to start recording again. Once finish To learn more about generating tests check out or detailed guide on [Codegen](./codegen.md). +### Generating locators + +You can generate [locators](/locators.md) with the test generator. + +* Press the `'Record'` button to stop the recording and the `'Pick Locator'` button will appear. +* Click on the `'Pick Locator'` button and then hover over elements in the browser window to see the locator highlighted underneath each element. +* To choose a locator click on the element you would like to locate and the code for that locator will appear in the field next to the Pick Locator button. +* You can then edit the locator in this field to fine tune it or use the copy button to copy it and paste it into your code. + +###### +* langs: js + +Picking a locator + +###### +* langs: java + +Picking a locator + +###### +* langs: python + +Picking a locator + +###### +* langs: csharp + +Picking a locator + +### Emulation + +You can also generate tests using emulation so as to generate a test for a specific viewport, device, color scheme, as well as emulate the geolocation, language or timezone. The test generator can also generate a test while preserving authenticated state. Check out the [Test Generator](./codegen.md#emulation) guide to learn more. + ## What's Next - [See a trace of your tests](./trace-viewer-intro.md) diff --git a/docs/src/codegen.md b/docs/src/codegen.md index 6eb35a0a5b717..996e69c36e112 100644 --- a/docs/src/codegen.md +++ b/docs/src/codegen.md @@ -5,9 +5,15 @@ title: "Test Generator" 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. + ## 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. + ```bash js npx playwright codegen demo.playwright.dev/todomvc ``` @@ -24,14 +30,69 @@ playwright codegen demo.playwright.dev/todomvc pwsh bin/Debug/netX/playwright.ps1 codegen demo.playwright.dev/todomvc ``` -Run `codegen` and perform actions in the browser. Playwright will generate the code for the user interactions. `Codegen` will attempt to generate resilient text-based selectors. +### 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. + +###### +* langs: js + +Recording a test + +###### +* langs: java + +Recording a test + +###### +* langs: python + +Recording a test + +###### +* langs: csharp + +Screenshot 2023-01-16 at 20 42 26 -## Emulate viewport size +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. + +Use the **clear** button to clear the code to start recording again. Once finished close the Playwright inspector window or stop the terminal command. + +To learn more about generating tests check out or detailed guide on [Codegen](./codegen.md). + +### Generating locators +You can generate [locators](/locators.md) with the test generator. + +* Press the `'Record'` button to stop the recording and the `'Pick Locator'` button will appear. +* Click on the `'Pick Locator'` button and then hover over elements in the browser window to see the locator highlighted underneath each element. +* To choose a locator click on the element you would like to locate and the code for that locator will appear in the field next to the Pick Locator button. +* You can then edit the locator in this field to fine tune it or use the copy button to copy it and paste it into your code. + +###### +* langs: js + +Picking a locator + +###### +* langs: java + +Picking a locator + +###### +* langs: python + +Picking a locator + +###### +* langs: csharp + +Picking a locator + +## Emulation + +You can use the test generator to 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. + +### Emulate viewport size Playwright opens a browser window with it's viewport set to a specific width and height and is not responsive as tests need to be run under the same conditions. Use the `--viewport` option to generate tests with a different viewport size. @@ -51,11 +112,9 @@ playwright codegen --viewport-size=800,600 playwright.dev pwsh bin/Debug/netX/playwright.ps1 codegen --viewport-size=800,600 playwright.dev ``` - - Codegen generating code for tests for playwright.dev website with a specific viewport -## Emulate devices +### Emulate devices Record scripts and tests while emulating a mobile device using the `--device` option which sets the viewport size and user agent among others. @@ -77,7 +136,7 @@ pwsh bin/Debug/netX/playwright.ps1 codegen --device="iPhone 11" playwright.dev Codegen generating code for tests for playwright.dev website emulated for iPhone 11 -## Emulate color scheme +### Emulate color scheme Record scripts and tests while emulating the color scheme with the `--color-scheme` option. @@ -99,7 +158,7 @@ pwsh bin/Debug/netX/playwright.ps1 codegen --color-scheme=dark playwright.dev Codegen generating code for tests for playwright.dev website in dark mode -## Emulate geolocation, language and timezone +### Emulate geolocation, language and timezone Record scripts and tests while emulating timezone, language & location using the `--timezone`, `--geolocation` and `--lang` options. Once page opens, click the "show your location" icon at them bottom right corner of the map to see geolocation in action. @@ -121,7 +180,7 @@ pwsh bin/Debug/netX/playwright.ps1 codegen --timezone="Europe/Rome" --geolocatio Codegen generating code for tests for google maps showing timezone, geolocation as Rome, Italy and in Italian language -## Preserve authenticated state +### Preserve authenticated state Run `codegen` with `--save-storage` to save [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) and [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) at the end of the session. This is useful to separately record an authentication step and reuse it later in the tests.