diff --git a/docs/src/cli.md b/docs/src/cli.md index 76728ca9af..2da5c5f529 100644 --- a/docs/src/cli.md +++ b/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 diff --git a/docs/src/debug.md b/docs/src/debug.md index 7db45b7b26..5a7a968234 100644 --- a/docs/src/debug.md +++ b/docs/src/debug.md @@ -9,6 +9,13 @@ for browser automation. +## 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. + +Playwright Inspector + + ## 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 diff --git a/docs/src/inspector.md b/docs/src/inspector.md new file mode 100644 index 0000000000..cfa8f845a1 --- /dev/null +++ b/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. + +Playwright Inspector + + + +## 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: + +Paused on line + +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: + +Red dot on inspected page + +By the time Playwright has paused on that click action, it has already performed actionability checks that can be found in the log: + +Action log + +If actionability can't be reached, it'll show action as pending: + +Screen Shot 2021-02-20 at 7 36 06 PM + +You can step over each action using the "Step over" action or resume script without further pauses: + +
Stepping toolbar
+ + +## 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: + +Screen Shot 2021-02-20 at 7 27 20 PM + +## Recording scripts + +At any moment, clicking Record action enables recorder (codegen) mode. +Every action on the target page is turned into the generated script: + +Screen Shot 2021-02-20 at 7 40 02 PM + +You can copy entire generated script or clear it using toolbar actions. diff --git a/docs/src/installation-python.md b/docs/src/installation-python.md index 1adc5cb06a..48378cbab1 100644 --- a/docs/src/installation-python.md +++ b/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 ``` diff --git a/docs/src/intro-python.md b/docs/src/intro-python.md index cb7bda3c86..a6d3bc4e66 100644 --- a/docs/src/intro-python.md +++ b/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 diff --git a/docs/src/release-notes.md b/docs/src/release-notes.md index 458c53e74f..69a285d5dc 100644 --- a/docs/src/release-notes.md +++ b/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`]. diff --git a/docs/src/why-playwright.md b/docs/src/why-playwright.md index 4d79c60953..c135e613eb 100644 --- a/docs/src/why-playwright.md +++ b/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. diff --git a/utils/markdown.js b/utils/markdown.js index 4b30e96687..5085c25cbb 100644 --- a/utils/markdown.js +++ b/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);