docs(inspector): add initial inspector docs (#5541)

Author: pavelfeldman

docs/src/cli.md

@@ -14,7 +14,7 @@ $ npx playwright --help
 ```
 
 ```sh python
-$ python -m playwright
+$ playwright
 ```
 
 ```json js
@@ -33,7 +33,7 @@ $ npx playwright codegen wikipedia.org
 ```
 
 ```sh python
-$ python -m playwright codegen wikipedia.org
+$ playwright codegen wikipedia.org
 ```
 
 Run `codegen` and perform actions in the browser. Playwright CLI will generate JavaScript code for the user interactions. `codegen` will attempt to generate resilient text-based selectors.
@@ -51,7 +51,7 @@ $ npx playwright --save-storage=auth.json codegen
 ```
 
 ```sh python
-$ python -m playwright --save-storage=auth.json codegen
+$ playwright --save-storage=auth.json codegen
 # Perform authentication and exit.
 # auth.json will contain the storage state.
 ```
@@ -65,8 +65,8 @@ $ npx playwright --load-storage=auth.json codegen my.web.app
 ```
 
 ```sh python
-$ python -m playwright --load-storage=auth.json open my.web.app
-$ python -m playwright --load-storage=auth.json codegen my.web.app
+$ playwright --load-storage=auth.json open my.web.app
+$ playwright --load-storage=auth.json codegen my.web.app
 # Perform actions in authenticated state.
 ```
 
@@ -138,7 +138,7 @@ $ npx playwright open example.com
 
 ```sh python
 # Open page in Chromium
-$ python -m playwright open example.com
+$ playwright open example.com
 ```
 
 ```sh js
@@ -148,7 +148,7 @@ $ npx playwright wk example.com
 
 ```sh python
 # Open page in WebKit
-$ python -m playwright wk example.com
+$ playwright wk example.com
 ```
 
 ### Emulate devices
@@ -161,7 +161,7 @@ $ npx playwright --device="iPhone 11" open wikipedia.org
 
 ```sh python
 # Emulate iPhone 11.
-$ python -m playwright --device="iPhone 11" open wikipedia.org
+$ playwright --device="iPhone 11" open wikipedia.org
 ```
 
 ### Emulate color scheme and viewport size
@@ -171,7 +171,7 @@ $ npx playwright --viewport-size=800,600 --color-scheme=dark open twitter.com
 ```
 ```sh python
 # Emulate screen size and color scheme.
-$ python -m playwright --viewport-size=800,600 --color-scheme=dark open twitter.com
+$ playwright --viewport-size=800,600 --color-scheme=dark open twitter.com
 ```
 
 ### Emulate geolocation, language and timezone
@@ -183,7 +183,7 @@ $ npx playwright --timezone="Europe/Rome" --geolocation="41.890221,12.492348" --
 ```sh python
 # Emulate timezone, language & location
 # Once page opens, click the "my location" button to see geolocation in action
-$ python -m playwright --timezone="Europe/Rome" --geolocation="41.890221,12.492348" --lang="it-IT" open maps.google.com
+$ playwright --timezone="Europe/Rome" --geolocation="41.890221,12.492348" --lang="it-IT" open maps.google.com
 ```
 
 ## Inspect selectors
@@ -238,7 +238,7 @@ $ npx playwright screenshot --help
 
 ```sh python
 # See command help
-$ python -m playwright screenshot --help
+$ playwright screenshot --help
 ```
 
 ```sh js
@@ -253,7 +253,7 @@ $ npx playwright \
 
 ```sh python
 # Wait 3 seconds before capturing a screenshot after page loads ('load' event fires)
-$ python -m playwright \
+$ playwright \
   --device="iPhone 11" \
   --color-scheme=dark \
   screenshot \
@@ -268,7 +268,7 @@ $ npx playwright screenshot --full-page en.wikipedia.org wiki-full.png
 
 ```sh python
 # Capture a full page screenshot
-$ python -m playwright screenshot --full-page en.wikipedia.org wiki-full.png
+$ playwright screenshot --full-page en.wikipedia.org wiki-full.png
 ```
 
 ## Generate PDF
@@ -282,7 +282,7 @@ $ npx playwright pdf https://en.wikipedia.org/wiki/PDF wiki.pdf
 
 ```sh python
 # See command help
-$ python -m playwright pdf https://en.wikipedia.org/wiki/PDF wiki.pdf
+$ playwright pdf https://en.wikipedia.org/wiki/PDF wiki.pdf
 ```
 
 ## Known limitations

docs/src/debug.md

@@ -9,6 +9,13 @@ for browser automation.
 
 <!-- TOC -->
 
+## Playwright Inspector
+
+[Playwright Inspector](./inspector.md) is a GUI tool that helps authoring and debugging Playwright scripts. That's our default recommended tool for scripts troubleshooting.
+
+<img width="712" alt="Playwright Inspector" src="https://user-images.githubusercontent.com/883973/108614092-8c478a80-73ac-11eb-9597-67dfce110e00.png">
+
+
 ## Run in headful mode
 
 Playwright runs browsers in headless mode by default. To change this behavior,
@@ -42,9 +49,6 @@ breakpoints.
 
 ### Use the new JavaScript debugging terminal
 
-VS Code 1.46+ introduced the new JavaScript debugger that does not require a `launch.json`
-configuration. To use it:
-
 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
@@ -109,8 +113,6 @@ 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
 

docs/src/inspector.md

@@ -0,0 +1,106 @@
+---
+id: inspector
+title: "Inspector"
+---
+
+Playwright Inspector is a GUI tool that helps authoring and debugging Playwright scripts.
+
+<img width="712" alt="Playwright Inspector" src="https://user-images.githubusercontent.com/883973/108614092-8c478a80-73ac-11eb-9597-67dfce110e00.png">
+
+<!-- TOC -->
+
+## Open Playwright Inspector
+
+There are several ways of opening Playwright Inspector:
+
+- Set the `PWDEBUG` environment variable to run your scripts in debug mode. This
+configures Playwright for debugging and opens the inspector.
+  ```sh js
+  # Linux/macOS
+  $ PWDEBUG=1 npm run test
+
+  # Windows
+  $ set PWDEBUG=1
+  $ npm run test
+  ```
+
+  ```sh python
+  # Linux/macOS
+  $ PWDEBUG=1 pytest -s
+
+  # Windows
+  $ set PWDEBUG=1
+  $ pytest -s
+  ```
+
+  Additional useful defaults are configured when `PWDEBUG` is set:
+  - Browsers launch in the headed mode
+  - Default timeout is set to 0 (= no timeout)
+
+- Call [`method: Page.pause`] method from your script when running in headed browser.
+
+  ```js
+  // Pause on the following line.
+  await page.pause();
+  ```
+
+  ```python async
+  # Pause on the following line.
+  await page.pause()
+  ```
+
+  ```python sync
+  # Pause on the following line.
+  page.pause()
+  ```
+
+- Use `open` or `codegen` commands in the Playwright [CLI](./cli.md):
+  ```sh js
+  $ npx playwright codegen wikipedia.org
+  ```
+
+  ```sh python
+  $ playwright codegen wikipedia.org
+  ```
+
+## Stepping through the Playwright script
+
+When `PWDEBUG` is set, Playwright Inspector window will be opened and the script will be
+paused on the first Playwright statement:
+
+<img width="557" alt="Paused on line" src="https://user-images.githubusercontent.com/883973/108614337-71761580-73ae-11eb-9f61-3d29c52c9520.png">
+
+Now we know what action is about to be performed and we can look into the details on that
+action. For example, when stopped on an input action such as `click`, the exact point Playwright is about to click is highlighted with the large red dot on the inspected page:
+
+<img width="344" alt="Red dot on inspected page" src="https://user-images.githubusercontent.com/883973/108614363-b69a4780-73ae-11eb-8f5e-51f9c91ec9b4.png">
+
+By the time Playwright has paused on that click action, it has already performed actionability checks that can be found in the log:
+
+<img width="712" alt="Action log" src="https://user-images.githubusercontent.com/883973/108614564-72a84200-73b0-11eb-9de2-828b28d78b36.png">
+
+If actionability can't be reached, it'll show action as pending:
+
+<img width="712" alt="Screen Shot 2021-02-20 at 7 36 06 PM" src="https://user-images.githubusercontent.com/883973/108614840-e6e3e500-73b2-11eb-998f-0cf31b2aa9a2.png">
+
+You can step over each action using the "Step over" action or resume script without further pauses:
+
+<center><img width="98" alt="Stepping toolbar" src="https://user-images.githubusercontent.com/883973/108614389-f9f4b600-73ae-11eb-8df2-8d9ce9da5d5c.png"></center>
+
+
+## Debugging Selectors
+
+- Click the Explore button to hover over elements in the screen and click them to
+automatically generate selectors for those elements.
+- To verify where selector points, paste it into the inspector input field:
+
+<img width="602" alt="Screen Shot 2021-02-20 at 7 27 20 PM" src="https://user-images.githubusercontent.com/883973/108614696-ad5eaa00-73b1-11eb-81f5-9eebe62543a2.png">
+
+## Recording scripts
+
+At any moment, clicking Record action enables recorder (codegen) mode.
+Every action on the target page is turned into the generated script:
+
+<img width="712" alt="Screen Shot 2021-02-20 at 7 40 02 PM" src="https://user-images.githubusercontent.com/883973/108614897-85704600-73b3-11eb-8bcd-f2e129786c49.png">
+
+You can copy entire generated script or clear it using toolbar actions.

docs/src/installation-python.md

@@ -15,7 +15,7 @@ Each version of Playwright needs specific versions of browser binaries to operat
 
 ```sh
 $ pip install playwright
-$ python -m playwright install
+$ playwright install
 ```
 
 These browsers will take few hundreds of megabytes of the disk space when installed:
@@ -37,7 +37,7 @@ $ PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers python -m playwright install
 # Windows
 $ set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
 $ pip install playwright
-$ python -m playwright install
+$ playwright install
 ```
 
 When running Playwright scripts, ask it to search for browsers in a shared location:
@@ -61,7 +61,7 @@ $ PLAYWRIGHT_BROWSERS_PATH=0 python -m playwright install
 # Windows
 $ set PLAYWRIGHT_BROWSERS_PATH=0
 $ pip install playwright
-$ python -m playwright install
+$ playwright install
 ```
 
 Playwright keeps track of packages that need those browsers and will garbage collect them as you update Playwright to the newer versions.
@@ -86,7 +86,7 @@ $ PLAYWRIGHT_DOWNLOAD_HOST=192.168.1.78 python -m playwright install
 # Windows
 $ set PLAYWRIGHT_DOWNLOAD_HOST=192.168.1.78
 $ pip install playwright
-$ python -m playwright install
+$ playwright install
 ```
 
 It is also possible to use a per-browser download hosts using `PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST`, `PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST` and `PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST` env variables that
@@ -113,7 +113,7 @@ $ PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 python -m playwright install
 # Windows
 $ set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
 $ pip install playwright
-$ python -m playwright install
+$ playwright install
 ```
 
 ## Download single browser binary
@@ -122,5 +122,5 @@ Playwright downloads Chromium, Firefox and WebKit browsers by default. To instal
 
 ```sh
 $ pip install playwright
-$ python -m playwright install firefox
+$ playwright install firefox
 ```

docs/src/intro-python.md

@@ -12,7 +12,7 @@ Use pip to install Playwright in your Python project. See [system requirements](
 
 ```sh
 $ pip install playwright
-$ python -m playwright install
+$ playwright install
 ```
 
 These commands download the Playwright package and install browser binaries for Chromium, Firefox and WebKit. To modify this behavior see [installation parameters](./installation.md).
@@ -75,7 +75,7 @@ firefox.launch(headless=False, slowMo=50)
 Command Line Interface [CLI](./cli.md) can be used to record user interactions and generate Python code.
 
 ```sh
-$ python -m playwright codegen wikipedia.org
+$ playwright codegen wikipedia.org
 ```
 
 ## System requirements

docs/src/release-notes.md

@@ -13,7 +13,7 @@ title: "Release notes"
   $ npx playwright --help
   ```
   ```sh python
-  $ python -m playwright --help
+  $ playwright --help
   ```
 - [`method: Page.selectOption`] now waits for the options to be present.
 - New methods to [assert element state](./actionability#assertions) like [`method: Page.isEditable`].

docs/src/why-playwright.md

@@ -42,7 +42,7 @@ Playwright enables fast, reliable and capable automation across all modern brows
   ```
   ```sh python
   $ pip install playwright
-  $ python -m playwright install
+  $ playwright install
   ```
 
 * **TypeScript support**. Playwright ships with built-in types for auto-completion and other benefits.

utils/markdown.js

@@ -125,13 +125,15 @@ function buildTree(lines) {
       };
       line = lines[++i];
       while (!line.trim().startsWith('```')) {
-        if (!line.startsWith(indent)) {
+        if (line && !line.startsWith(indent)) {
           const from = Math.max(0, i - 5)
           const to = Math.min(lines.length, from + 10);
           const snippet = lines.slice(from, to);
           throw new Error(`Bad code block: ${snippet.join('\n')}`);
         }
-        node.lines.push(line.substring(indent.length));
+        if (line)
+          line = line.substring(indent.length);
+        node.lines.push(line);
         line = lines[++i];
       }
       appendNode(indent, node);