diff --git a/docs/README.md b/docs/README.md index 978a76fc94..4036e8b4f7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,7 +7,6 @@ - [Usage](./intro.md#usage) - [First script](./intro.md#first-script) - [System requirements](./intro.md#system-requirements) - - [Debugging scripts](./intro.md#debugging-scripts) - [Installation parameters](./installation.md) 1. [Core Concepts](./core-concepts.md) - [Overview](./core-concepts.md#) @@ -47,6 +46,10 @@ - [Common patterns](./assertions.md#common-patterns) - [Element Handles](./assertions.md#element-handles) - [Custom assertions](./assertions.md#custom-assertions) +1. [Debugging tools](./debug.md) + - [VS Code debugger](./debug.md#visual-studio-code-debugger) + - [Browser developer tools](./debug.md#browser-developer-tools) + - [Debug mode](./debug.md#run-in-debug-mode) 1. [Verification](./verification.md) - [Screenshots](./verification.md#screenshots) - [Console logs](./verification.md#console-logs) diff --git a/docs/debug.md b/docs/debug.md new file mode 100644 index 0000000000..a7793423a0 --- /dev/null +++ b/docs/debug.md @@ -0,0 +1,137 @@ +# Debugging tools + +Playwright scripts work with existing debugging tools, like Node.js debuggers +and browser developer tools. Playwright also introduces new debugging features +for browser automation. + + +- [Run in headful mode](#run-in-headful-mode) +- [Visual Studio Code debugger](#visual-studio-code-debugger) + * [Use launch config](#use-launch-config) + * [Use the new JavaScript debugger](#use-the-new-javascript-debugger) +- [Browser Developer Tools](#browser-developer-tools) + * [API for Chromium](#api-for-chromium) +- [Run in Debug Mode](#run-in-debug-mode) + * [Defaults](#defaults) + * [Debugging Selectors](#debugging-selectors) + * [Evaluate Source Maps](#evaluate-source-maps) +- [Verbose API logs](#verbose-api-logs) + + +## Run in headful mode + +Playwright runs browsers in headless mode by default. To change this behavior, +use `headless: false` as a launch option. You can also use the `slowMo` option +to slow down execution and follow along while debugging. + +```js +await chromium.launch({ headless: false, slowMo: 100 }); // or firefox, webkit +``` + +## Visual Studio Code debugger + +The VS Code debugger can be used to pause and resume execution of Playwright +scripts with breakpoints. The debugger can be configured in two ways. + +### Use launch config + +Setup [`launch.json` configuration](https://code.visualstudio.com/docs/nodejs/nodejs-debugging) +for your Node.js project. Once configured launch the scripts with F5 and use +breakpoints. + +### Use the new JavaScript debugger + +VS Code 1.46+ introduces the new JavaScript debugger behind a feature flag. The +new debugger does not require a `launch.json` configuration. To use this: + +1. Enable the preview debugger + * Open JSON settings and add `"debug.javascript.usePreview": true` + * Open settings UI and enable the `Debug › JavaScript: Use Preview` setting + +1. Set a breakpoint in VS Code + * Use the `debugger` keyword or set a breakpoint in the VS Code UI + +1. Run your Node.js script from the terminal + +## Browser Developer Tools + +You can use browser developer tools in Chromium, Firefox and WebKit while running +a Playwright script. Developer tools help to: + +* Inspect the DOM tree and **find element selectors** +* **See console logs** during execution (or learn how to [read logs via API](verification.md#console-logs)) +* Check **network activity** and other developer tools features + +Chromium Developer Tools + +> **For WebKit**: Note that launching WebKit Inspector during the execution will + prevent the Playwright script from executing any further. + +### API for Chromium + +In Chromium, you can also open developer tools through a launch option. + +```js +await chromium.launch({ devtools: true }); +``` + +## Run in Debug Mode + +Set the `PWDEBUG` environment variable to run your scripts in debug mode. This +configures the browser for debugging. + +```sh +# Linux/macOS +$ PWDEBUG=1 npm run test + +# Windows +$ set PWDEBUG=1 +$ npm run test +``` + +### Defaults + +With PWDEBUG, the following defaults are configured for you: + +* **Run in headful**: With PWDEBUG, browsers always launch in headful mode +* **Disables timeout**: PWDEBUG sets timeout to 0 (= no timeout) +* **Preserve DevTools preferences**: When used with `devtools: true`, PWDEBUG + preserves the docked/undocked state of Chrome DevTools + +### Debugging Selectors + +PWDEBUG configures a `playwright` object in the browser to highlight +[Playwright selectors](selectors.md). This can be used to verify text or +composite selectors. To use this: + +1. Setup a breakpoint to pause the execution +1. Open the console panel in browser developer tools +1. Use the `playwright` API + * `playwright.$(selector)`: Highlight the first occurrence of the selector. This reflects + how `page.$` would see the page. + * `playwright.$$(selector)`: Highlight all occurrences of the selector. This reflects + how `page.$$` would see the page. + * `playwright.inspect(selector)`: Inspect the selector in the Elements panel. + * `playwright.clear()`: Clear existing highlights. + +Highlight selectors + +### Evaluate Source Maps + +PWDEBUG also enables source maps for [`page.evaluate` executions](core-concepts.md#evaluation). +This improves the debugging experience for JavaScript executions in the page context. + +Highlight selectors + +## Verbose API logs + +Playwright supports verbose logging with the `DEBUG` environment variable. + +```sh +# Linux/macOS +$ DEBUG=pw:api npm run test + +# Windows +$ set DEBUG=pw:api +$ npm run test +``` diff --git a/docs/docker/README.md b/docs/docker/README.md index c93fda46f2..9a0caf12cd 100644 --- a/docs/docker/README.md +++ b/docs/docker/README.md @@ -53,7 +53,7 @@ $ docker build -t mcr.microsoft.com/playwright:bionic -f Dockerfile.bionic . ### Push -Playwright on Docker Hub relies on +Playwright on Docker Hub is published via the [Microsoft Container Registry](https://github.com/microsoft/containerregistry). ``` $ docker push playwright.azurecr.io/public/playwright:bionic diff --git a/docs/intro.md b/docs/intro.md index 527455febe..d949b0f078 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -6,9 +6,6 @@ - [First script](#first-script) - [System requirements](#system-requirements) - [TypeScript IDE support](#typescript-ide-support) -- [Debugging scripts](#debugging-scripts) - * [Using editor debugger](#using-editor-debugger) - * [Verbose logging](#verbose-logging)
@@ -112,28 +109,3 @@ You can also use JSDoc to set types for variables. /** @type {import('playwright').Page} */ let page; ``` - -
- -## Debugging scripts - -### Using editor debugger - -Playwright scripts can be developed just like any other Node.js script. For example, you can use the [Node.js debugger](https://nodejs.org/api/debugger.html) or [VS Code debugging](https://code.visualstudio.com/docs/nodejs/nodejs-debugging) to set breakpoints and get fine grained control over execution. - - Chromium Developer Tools - -It is also possible to open **browser developer tools** during execution, to inspect the DOM tree or network activity. - -### Verbose logging - -Playwright supports verbose logging with the `DEBUG` environment variable. - -```sh -# Linux/macOS -$ DEBUG=pw:api npm run test - -# Windows -$ set DEBUG=pw:api -$ npm run test -```