docs: add debugging docs page (#2865)
This commit is contained in:
Arjun Attam
GitHub
parent
8611ee8df7
commit
6a1bd3ae6e
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
<!-- GEN:toc -->
|
||||
- [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)
|
||||
<!-- GEN:stop -->
|
||||
|
||||
## 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
|
||||
|
||||
<a href="https://user-images.githubusercontent.com/284612/77234134-5f21a500-6b69-11ea-92ec-1c146e1333ec.png"><img src="https://user-images.githubusercontent.com/284612/77234134-5f21a500-6b69-11ea-92ec-1c146e1333ec.png" width="500" alt="Chromium Developer Tools"></a>
|
||||
|
||||
> **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.
|
||||
|
||||
<a href="https://user-images.githubusercontent.com/284612/86857345-299abc00-c073-11ea-9e31-02923a9f0d4b.png"><img src="https://user-images.githubusercontent.com/284612/86857345-299abc00-c073-11ea-9e31-02923a9f0d4b.png" width="500" alt="Highlight selectors"></a>
|
||||
|
||||
### 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.
|
||||
|
||||
<a href="https://user-images.githubusercontent.com/284612/86857568-a6c63100-c073-11ea-82a4-bfd531a4ec87.png"><img src="https://user-images.githubusercontent.com/284612/86857568-a6c63100-c073-11ea-82a4-bfd531a4ec87.png" width="500" alt="Highlight selectors"></a>
|
||||
|
||||
## 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
|
||||
```
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
<!-- GEN:stop -->
|
||||
|
||||
<br>
|
||||
|
|
@ -112,28 +109,3 @@ You can also use JSDoc to set types for variables.
|
|||
/** @type {import('playwright').Page} */
|
||||
let page;
|
||||
```
|
||||
|
||||
<br>
|
||||
|
||||
## 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.
|
||||
|
||||
<a href="https://user-images.githubusercontent.com/284612/77234134-5f21a500-6b69-11ea-92ec-1c146e1333ec.png"><img src="https://user-images.githubusercontent.com/284612/77234134-5f21a500-6b69-11ea-92ec-1c146e1333ec.png" width="300" alt="Chromium Developer Tools"></a>
|
||||
|
||||
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
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue