|
1 | 1 | --- |
2 | | -id: inspector |
3 | | -title: "Inspector" |
| 2 | +id: debug-selectors |
| 3 | +title: "Debugging Selectors" |
4 | 4 | --- |
5 | 5 | import Tabs from '@theme/Tabs'; |
6 | 6 | import TabItem from '@theme/TabItem'; |
7 | 7 |
|
8 | | -Playwright Inspector is a GUI tool that helps authoring and debugging Playwright scripts. |
| 8 | +Playwright will throw a timeout exception like `locator.click: Timeout 30000ms exceeded` when an element does not exist on the page. There are multiple ways of debugging selectors: |
| 9 | +- [Playwright Inspector](#using-playwright-inspector) to step over each Playwright API call to inspect the page. |
| 10 | +- [Browser DevTools](#using-devtools) to inspect selectors with the DevTools element panel. |
| 11 | +- [Trace Viewer](./trace-viewer.mdx) to see what the page looked like during the test run. |
| 12 | +- [Verbose API logs](#verbose-api-logs) shows [actionability checks](./actionability.mdx) when locating the element. |
9 | 13 |
|
10 | | -<img width="712" alt="Playwright Inspector" src="https://user-images.githubusercontent.com/883973/108614092-8c478a80-73ac-11eb-9597-67dfce110e00.png"></img> |
| 14 | +## Using Playwright Inspector |
11 | 15 |
|
12 | | -- [Open Playwright Inspector](#open-playwright-inspector) |
13 | | -- [Stepping through the Playwright script](#stepping-through-the-playwright-script) |
14 | | -- [Using Browser Developer Tools](#using-browser-developer-tools) |
15 | | -- [Debugging Selectors](#debugging-selectors) |
16 | | -- [Recording scripts](#recording-scripts) |
| 16 | +Open the [Playwright Inspector](./debug.mdx) and 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: |
17 | 17 |
|
18 | | -## Open Playwright Inspector |
| 18 | +<img width="602" alt="Selectors toolbar" src="https://user-images.githubusercontent.com/883973/108614696-ad5eaa00-73b1-11eb-81f5-9eebe62543a2.png"></img> |
19 | 19 |
|
20 | | -There are several ways of opening Playwright Inspector: |
21 | | -- Set the `PWDEBUG` environment variable to run your scripts in debug mode. This configures Playwright for debugging and opens the inspector. |
| 20 | +## Using DevTools |
22 | 21 |
|
23 | | - <Tabs |
24 | | - groupId="bash-flavor" |
25 | | - defaultValue="bash" |
26 | | - values={[ |
27 | | - {label: 'Bash', value: 'bash'}, |
28 | | - {label: 'PowerShell', value: 'powershell'}, |
29 | | - {label: 'Batch', value: 'batch'} |
30 | | - ] |
31 | | - }> |
32 | | - <TabItem value="bash"> |
33 | | - |
34 | | - ```bash |
35 | | - PWDEBUG=1 dotnet test |
36 | | - ``` |
37 | | - |
38 | | - </TabItem> |
39 | | - <TabItem value="powershell"> |
40 | | - |
41 | | - ```powershell |
42 | | - $env:PWDEBUG=1 |
43 | | - dotnet test |
44 | | - ``` |
45 | | - |
46 | | - </TabItem> |
47 | | - <TabItem value="batch"> |
48 | | - |
49 | | - ```batch |
50 | | - set PWDEBUG=1 |
51 | | - dotnet test |
52 | | - ``` |
53 | | - |
54 | | - </TabItem> |
55 | | - </Tabs> |
| 22 | +You can also use the following API inside the Developer Tools Console of any browser. |
56 | 23 |
|
57 | | - Additional useful defaults are configured when `PWDEBUG=1` is set: |
58 | | - - Browsers launch in the headed mode |
59 | | - - Default timeout is set to 0 (= no timeout) |
60 | | -- Call [Page.PauseAsync()](/api/class-page.mdx#page-pause) method from your script when running in headed browser. |
| 24 | +When running in Debug Mode with `PWDEBUG=console`, a `playwright` object is available in Developer tools console. |
| 25 | +1. Run with `PWDEBUG=console` |
| 26 | +1. Setup a breakpoint to pause the execution |
| 27 | +1. Open the console panel in browser developer tools |
61 | 28 |
|
62 | | - ```csharp |
63 | | - // Pause on the following line. |
64 | | - await page.PauseAsync(); |
65 | | - ``` |
| 29 | +<img src="https://user-images.githubusercontent.com/284612/92536317-37dd9380-f1ee-11ea-875d-daf1b206dd56.png"></img> |
66 | 30 |
|
67 | | -- Use `open` or `codegen` commands in the Playwright [CLI](./cli.mdx): |
| 31 | +### playwright.$(selector) |
68 | 32 |
|
69 | | - ```bash |
70 | | - pwsh bin\Debug\netX\playwright.ps1 codegen wikipedia.org |
71 | | - ``` |
| 33 | +Query Playwright selector, using the actual Playwright query engine, for example: |
72 | 34 |
|
73 | | -## Stepping through the Playwright script |
| 35 | +```txt |
| 36 | +> playwright.$('.auth-form >> text=Log in'); |
74 | 37 |
|
75 | | -When `PWDEBUG=1` is set, Playwright Inspector window will be opened and the script will be paused on the first Playwright statement: |
| 38 | +<button>Log in</button> |
| 39 | +``` |
76 | 40 |
|
77 | | -<img width="557" alt="Paused on line" src="https://user-images.githubusercontent.com/883973/108614337-71761580-73ae-11eb-9f61-3d29c52c9520.png"></img> |
| 41 | +### playwright.$$(selector) |
78 | 42 |
|
79 | | -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: |
| 43 | +Same as `playwright.$`, but returns all matching elements. |
80 | 44 |
|
81 | | -<img width="344" alt="Red dot on inspected page" src="https://user-images.githubusercontent.com/883973/108614363-b69a4780-73ae-11eb-8f5e-51f9c91ec9b4.png"></img> |
| 45 | +```txt |
| 46 | +> playwright.$$('li >> text=John') |
82 | 47 |
|
83 | | -By the time Playwright has paused on that click action, it has already performed actionability checks that can be found in the log: |
| 48 | +> [<li>, <li>, <li>, <li>] |
| 49 | +``` |
84 | 50 |
|
85 | | -<img width="712" alt="Action log" src="https://user-images.githubusercontent.com/883973/108614564-72a84200-73b0-11eb-9de2-828b28d78b36.png"></img> |
| 51 | +### playwright.inspect(selector) |
86 | 52 |
|
87 | | -If actionability can't be reached, it'll show action as pending: |
| 53 | +Reveal element in the Elements panel (if DevTools of the respective browser supports it). |
88 | 54 |
|
89 | | -<img width="712" alt="Pending action" src="https://user-images.githubusercontent.com/883973/108614840-e6e3e500-73b2-11eb-998f-0cf31b2aa9a2.png"></img> |
| 55 | +```txt |
| 56 | +> playwright.inspect('text=Log in') |
| 57 | +``` |
90 | 58 |
|
91 | | -You can step over each action using the "Step over" action (keyboard shortcut: `F10`) or resume script without further pauses (`F8`): |
| 59 | +### playwright.locator(selector) |
92 | 60 |
|
93 | | -<center><img width="98" alt="Stepping toolbar" src="https://user-images.githubusercontent.com/883973/108614389-f9f4b600-73ae-11eb-8df2-8d9ce9da5d5c.png"></img></center> |
| 61 | +Query Playwright element using the actual Playwright query engine, for example: |
94 | 62 |
|
95 | | -## Using Browser Developer Tools |
| 63 | +```txt |
| 64 | +> playwright.locator('.auth-form', { hasText: 'Log in' }); |
96 | 65 |
|
97 | | -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: |
98 | | -* Inspect the DOM tree |
99 | | -* **See console logs** during execution (or learn how to [read logs via API](./api/class-page.mdx#page-event-console)) |
100 | | -* Check **network activity** and other developer tools features |
| 66 | +> Locator () |
| 67 | +> - element: button |
| 68 | +> - elements: [button] |
| 69 | +``` |
101 | 70 |
|
102 | | -:::note |
103 | | -**For WebKit**: launching WebKit Inspector during the execution will prevent the Playwright script from executing any further. |
104 | | -::: |
| 71 | +### playwright.highlight(selector) |
105 | 72 |
|
106 | | -## Debugging Selectors |
107 | | -- Click the Explore button to hover over elements in the screen and click them to automatically generate selectors for those elements. |
108 | | -- To verify where selector points, paste it into the inspector input field: |
| 73 | +Highlight the first occurrence of the locator: |
109 | 74 |
|
110 | | -<img width="602" alt="Selectors toolbar" src="https://user-images.githubusercontent.com/883973/108614696-ad5eaa00-73b1-11eb-81f5-9eebe62543a2.png"></img> |
| 75 | +```txt |
| 76 | +> playwright.hightlight('.auth-form'); |
| 77 | +``` |
111 | 78 |
|
112 | | -You can also use the following API inside the Developer Tools Console of any browser. |
| 79 | +### playwright.clear() |
113 | 80 |
|
114 | | -<img src="https://user-images.githubusercontent.com/284612/92536317-37dd9380-f1ee-11ea-875d-daf1b206dd56.png"></img> |
| 81 | +```txt |
| 82 | +> playwright.clear() |
| 83 | +``` |
115 | 84 |
|
116 | | -#### playwright.$(selector) |
| 85 | +Clear existing highlights. |
117 | 86 |
|
118 | | -Query Playwright selector, using the actual Playwright query engine, for example: |
| 87 | +### playwright.selector(element) |
119 | 88 |
|
120 | | -#### playwright.$$(selector) |
| 89 | +Generates selector for the given element. |
121 | 90 |
|
122 | | -Same as `playwright.$`, but returns all matching elements. |
| 91 | +```txt |
| 92 | +> playwright.selector($0) |
123 | 93 |
|
124 | | -#### playwright.inspect(selector) |
| 94 | +"div[id="glow-ingress-block"] >> text=/.*Hello.*/" |
| 95 | +``` |
125 | 96 |
|
126 | | -Reveal element in the Elements panel (if DevTools of the respective browser supports it). |
| 97 | +## Verbose API logs |
127 | 98 |
|
128 | | -#### playwright.locator(selector) |
| 99 | +Playwright supports verbose logging with the `DEBUG` environment variable. |
129 | 100 |
|
130 | | -Query Playwright element using the actual Playwright query engine, for example: |
| 101 | +<Tabs |
| 102 | + groupId="bash-flavor" |
| 103 | + defaultValue="bash" |
| 104 | + values={[ |
| 105 | + {label: 'Bash', value: 'bash'}, |
| 106 | + {label: 'PowerShell', value: 'powershell'}, |
| 107 | + {label: 'Batch', value: 'batch'} |
| 108 | + ] |
| 109 | +}> |
| 110 | +<TabItem value="bash"> |
131 | 111 |
|
132 | | -#### playwright.selector(element) |
| 112 | +```bash |
| 113 | +DEBUG=pw:api dotnet run |
| 114 | +``` |
133 | 115 |
|
134 | | -Generates selector for the given element. |
| 116 | +</TabItem> |
| 117 | +<TabItem value="powershell"> |
135 | 118 |
|
136 | | -## Recording scripts |
| 119 | +```powershell |
| 120 | +$env:DEBUG="pw:api" |
| 121 | +dotnet run |
| 122 | +``` |
137 | 123 |
|
138 | | -At any moment, clicking Record action enables [codegen mode](./codegen.mdx). Every action on the target page is turned into the generated script: |
| 124 | +</TabItem> |
| 125 | +<TabItem value="batch"> |
139 | 126 |
|
140 | | -<img width="712" alt="Recorded script" src="https://user-images.githubusercontent.com/883973/108614897-85704600-73b3-11eb-8bcd-f2e129786c49.png"></img> |
| 127 | +```batch |
| 128 | +set DEBUG=pw:api |
| 129 | +dotnet run |
| 130 | +``` |
141 | 131 |
|
142 | | -You can copy entire generated script or clear it using toolbar actions. |
| 132 | +</TabItem> |
| 133 | +</Tabs> |
143 | 134 |
|
144 | 135 | [Accessibility]: /api/class-accessibility.mdx "Accessibility" |
145 | 136 | [APIRequest]: /api/class-apirequest.mdx "APIRequest" |
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments