diff --git a/docs/src/debug.md b/docs/src/debug.md index 43c4a126a0..ccfbc90cf5 100644 --- a/docs/src/debug.md +++ b/docs/src/debug.md @@ -42,7 +42,98 @@ chromium.launch(headless=False, slow_mo=100) # or firefox, webkit ``` -## Visual Studio Code debugger (Node.JS) +## Browser Developer Tools + +You can use browser developer tools in Chromium, Firefox and WebKit while running +a Playwright script in headed mode. 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 + +Using a [`method: Page.pause`] method is an easy way to pause the Playwright script execution +and inspect the page in Developer tools. It will also open [Playwright Inspector](./inspector.md) to help with debugging. + +:::note +**For WebKit**: launching WebKit Inspector during the execution will + prevent the Playwright script from executing any further. +::: + +:::note +**For Chromium**: you can also open developer tools through a launch option. +```js +await chromium.launch({ devtools: true }); +``` +```java +chromium.launch(new BrowserType.LaunchOptions().setDevtools(true)); +``` +```python async +await chromium.launch(devtools=True) +``` +```python sync +chromium.launch(devtools=True) +``` +::: + +## Run in Debug Mode + +Set the `PWDEBUG` environment variable to run your scripts in debug mode. Using `PWDEBUG=1` will open [Playwright Inspector](./inspector.md). + +Using `PWDEBUG=console` will configure the browser for debugging in Developer tools console: +* **Runs headed**: Browsers always launch in headed mode +* **Disables timeout**: Sets default timeout to 0 (= no timeout) +* **Console helper**: Configures a `playwright` object in the browser to generate and highlight +[Playwright selectors](./selectors.md). This can be used to verify text or +composite selectors. + +```sh js +# Linux/macOS +$ PWDEBUG=console npm run test + +# Windows +$ set PWDEBUG=console +$ npm run test +``` + +```sh java +# Linux/macOS +$ PWDEBUG=console mvn test + +# Windows +$ set PWDEBUG=console +$ mvn test +``` + +```sh python +# Linux/macOS +$ PWDEBUG=console pytest -s + +# Windows +$ set PWDEBUG=console +$ pytest -s +``` + +## Selectors in Developer Tools Console + +When running in Debug Mode with `PWDEBUG=console`, a `playwright` object is available in Developer tools console. + +1. Run with `PWDEBUG=console` +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. + * `playwright.selector(element)`: Generate a selector that points to the element. + +Highlight selectors + +## Visual Studio Code debugger (Node.js) 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. @@ -53,111 +144,13 @@ Setup [`launch.json` configuration](https://code.visualstudio.com/docs/nodejs/no for your Node.js project. Once configured launch the scripts with F5 and use breakpoints. -### Use the new JavaScript debugging terminal +### Use the JavaScript Debug Terminal +1. Open [JavaScript Debug Terminal](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_javascript-debug-terminal) 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 }); -``` - -```java -chromium.launch(new BrowserType.LaunchOptions().setDevtools(true)); -``` - -```python async -await chromium.launch(devtools=True) - -``` - -```python sync -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 js -# Linux/macOS -$ PWDEBUG=1 npm run test - -# Windows -$ set PWDEBUG=1 -$ npm run test -``` - -```sh java -# Linux/macOS -$ PWDEBUG=1 mvn test - -# Windows -$ set PWDEBUG=1 -$ mvn test -``` - -```sh python -# Linux/macOS -$ PWDEBUG=1 pytest -s - -# Windows -$ set PWDEBUG=1 -$ pytest -s -``` - -### Defaults - -With PWDEBUG, the following defaults are configured for you: - -* **Run in headed**: With PWDEBUG, browsers always launch in headed mode -* **Disables timeout**: PWDEBUG sets timeout to 0 (= no timeout) - -### 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 [`method: 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. diff --git a/docs/src/inspector.md b/docs/src/inspector.md index a8d3252923..908868846e 100644 --- a/docs/src/inspector.md +++ b/docs/src/inspector.md @@ -43,7 +43,7 @@ configures Playwright for debugging and opens the inspector. $ pytest -s ``` - Additional useful defaults are configured when `PWDEBUG` is set: + Additional useful defaults are configured when `PWDEBUG=1` is set: - Browsers launch in the headed mode - Default timeout is set to 0 (= no timeout) @@ -84,7 +84,7 @@ configures Playwright for debugging and opens the inspector. ## Stepping through the Playwright script -When `PWDEBUG` is set, Playwright Inspector window will be opened and the script will be +When `PWDEBUG=1` is set, Playwright Inspector window will be opened and the script will be paused on the first Playwright statement: Paused on line @@ -100,12 +100,25 @@ By the time Playwright has paused on that click action, it has already performed If actionability can't be reached, it'll show action as pending: -Screen Shot 2021-02-20 at 7 36 06 PM +Pending action You can step over each action using the "Step over" action or resume script without further pauses:
Stepping toolbar
+## Using Browser Developer Tools + +You can use browser developer tools in Chromium, Firefox and WebKit while running +a Playwright script, with or without Playwright inspector. Developer tools help to: + +* Inspect the DOM tree +* **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 + +:::note +**For WebKit**: launching WebKit Inspector during the execution will + prevent the Playwright script from executing any further. +::: ## Debugging Selectors @@ -113,13 +126,13 @@ You can step over each action using the "Step over" action or resume script with 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 +Selectors toolbar ## 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 +Recorded script You can copy entire generated script or clear it using toolbar actions. diff --git a/src/server/browserContext.ts b/src/server/browserContext.ts index b9d426bb04..7482ea35f6 100644 --- a/src/server/browserContext.ts +++ b/src/server/browserContext.ts @@ -16,7 +16,7 @@ */ import { TimeoutSettings } from '../utils/timeoutSettings'; -import { isDebugMode, mkdirIfNeeded, createGuid } from '../utils/utils'; +import { debugMode, mkdirIfNeeded, createGuid } from '../utils/utils'; import { Browser, BrowserOptions } from './browser'; import { Download } from './download'; import * as frames from './frames'; @@ -377,7 +377,7 @@ export function validateBrowserContextOptions(options: types.BrowserContextOptio throw new Error(`Browser needs to be launched with the global proxy. If all contexts override the proxy, global proxy will be never used and can be any string, for example "launch({ proxy: { server: 'per-context' } })"`); options.proxy = normalizeProxySettings(options.proxy); } - if (isDebugMode()) + if (debugMode() === 'inspector') options.bypassCSP = true; verifyGeolocation(options.geolocation); if (!options._debugName) diff --git a/src/server/browserType.ts b/src/server/browserType.ts index 9b9173d2e4..75bb40dd6f 100644 --- a/src/server/browserType.ts +++ b/src/server/browserType.ts @@ -28,7 +28,7 @@ import { Progress, ProgressController } from './progress'; import * as types from './types'; import { DEFAULT_TIMEOUT, TimeoutSettings } from '../utils/timeoutSettings'; import { validateHostRequirements } from './validateDependencies'; -import { isDebugMode } from '../utils/utils'; +import { debugMode } from '../utils/utils'; import { helper } from './helper'; import { RecentLogsCollector } from '../utils/debugLogger'; import { CallMetadata, SdkObject } from './instrumentation'; @@ -271,7 +271,7 @@ function copyTestHooks(from: object, to: object) { function validateLaunchOptions(options: Options): Options { const { devtools = false } = options; let { headless = !devtools } = options; - if (isDebugMode()) + if (debugMode()) headless = false; return { ...options, devtools, headless }; } diff --git a/src/server/chromium/chromium.ts b/src/server/chromium/chromium.ts index d6287db219..5e4ba34b0d 100644 --- a/src/server/chromium/chromium.ts +++ b/src/server/chromium/chromium.ts @@ -25,7 +25,7 @@ import { ConnectionTransport, ProtocolRequest, WebSocketTransport } from '../tra import { CRDevTools } from './crDevTools'; import { BrowserOptions, BrowserProcess, PlaywrightOptions } from '../browser'; import * as types from '../types'; -import { isDebugMode } from '../../utils/utils'; +import { debugMode } from '../../utils/utils'; import { RecentLogsCollector } from '../../utils/debugLogger'; import { ProgressController } from '../progress'; import { TimeoutSettings } from '../../utils/timeoutSettings'; @@ -40,7 +40,7 @@ export class Chromium extends BrowserType { constructor(playwrightOptions: PlaywrightOptions) { super('chromium', playwrightOptions); - if (isDebugMode()) + if (debugMode()) this._devtools = this._createDevTools(); } diff --git a/src/server/supplements/inspectorController.ts b/src/server/supplements/inspectorController.ts index e62a84b2a3..49835c30c3 100644 --- a/src/server/supplements/inspectorController.ts +++ b/src/server/supplements/inspectorController.ts @@ -18,12 +18,15 @@ import { BrowserContext } from '../browserContext'; import { RecorderSupplement } from './recorderSupplement'; import { debugLogger } from '../../utils/debugLogger'; import { CallMetadata, InstrumentationListener, SdkObject } from '../instrumentation'; -import { isDebugMode, isUnderTest } from '../../utils/utils'; +import { debugMode, isUnderTest } from '../../utils/utils'; +import * as consoleApiSource from '../../generated/consoleApiSource'; export class InspectorController implements InstrumentationListener { async onContextCreated(context: BrowserContext): Promise { - if (isDebugMode()) + if (debugMode() === 'inspector') await RecorderSupplement.getOrCreate(context, { pauseOnNextStatement: true }); + else if (debugMode() === 'console') + await context.extendInjectedScript(consoleApiSource.source); } async onBeforeCall(sdkObject: SdkObject, metadata: CallMetadata): Promise { diff --git a/src/utils/timeoutSettings.ts b/src/utils/timeoutSettings.ts index 06280b5a26..46b8fd4cea 100644 --- a/src/utils/timeoutSettings.ts +++ b/src/utils/timeoutSettings.ts @@ -15,10 +15,10 @@ * limitations under the License. */ -import { isDebugMode } from './utils'; +import { debugMode } from './utils'; export const DEFAULT_TIMEOUT = 30000; -const TIMEOUT = isDebugMode() ? 0 : DEFAULT_TIMEOUT; +const TIMEOUT = debugMode() ? 0 : DEFAULT_TIMEOUT; export class TimeoutSettings { private _parent: TimeoutSettings | undefined; diff --git a/src/utils/utils.ts b/src/utils/utils.ts index 0d7728b499..ed98d10c74 100644 --- a/src/utils/utils.ts +++ b/src/utils/utils.ts @@ -88,9 +88,11 @@ export function isError(obj: any): obj is Error { return obj instanceof Error || (obj && obj.__proto__ && obj.__proto__.name === 'Error'); } -const isInDebugMode = !!getFromENV('PWDEBUG'); -export function isDebugMode(): boolean { - return isInDebugMode; +const debugEnv = getFromENV('PWDEBUG') || ''; +export function debugMode() { + if (debugEnv === 'console') + return 'console'; + return debugEnv ? 'inspector' : ''; } let _isUnderTest = false;