-
Notifications
You must be signed in to change notification settings - Fork 9k
/
debugging.md
169 lines (123 loc) · 5.49 KB
/
debugging.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
# Debugging
Debugging with Puppeteer can be an arduous task. There is no _single_ method for
debugging all possible issues since Puppeteer touches many distinct components
of a browser such as network requests and Web APIs. On a high note, Puppeteer
provides _several_ methods for debugging which hopefully does cover all possible
issues.
## Background
In general, there are two possible sources of an issue: Code running on Node.js
(which we call _server code_), and
[code running in the browser](../api/puppeteer.page.evaluate)
(which we call _client code_). There is also a third possible source being the
browser itself (which we call _internal code_ or _browser code_), but if you suspect this is the
source **after attempting the methods below**, we suggest
[searching existing issues](https://github.com/puppeteer/puppeteer/issues)
before
[filing an issue](https://github.com/puppeteer/puppeteer/issues/new/choose).
## Debugging methods for all situations
These methods can be used to debug any situation. These should be used as a
quick sanity check before diving into more complex methods.
### Turn off [`headless`](../api/puppeteer.browserlaunchargumentoptions)
Sometimes it's useful to see what the browser is displaying. Instead of
launching in
[`headless`](../api/puppeteer.browserlaunchargumentoptions) mode,
launch a full version of the browser with
[`headless`](../api/puppeteer.browserlaunchargumentoptions) set to
`false`:
```ts
const browser = await puppeteer.launch({headless: false});
```
### Puppeteer "slow-mo"
The [`slowMo`](../api/puppeteer.browserconnectoptions) option slows down
Puppeteer operations by a specified amount of milliseconds. It's another way to
help see what's going on.
```ts
const browser = await puppeteer.launch({
headless: false,
slowMo: 250, // slow down by 250ms
});
```
## Debugging methods for client code
### Capture `console.*` output
Since client code runs in the browser, doing `console.*` in client code will not
directly log to Node.js. However, you can [listen (page.on)](../api/puppeteer.page) for
the [`console`](../api/puppeteer.pageevents) event which returns a
payload with the logged text.
```ts
page.on('console', msg => console.log('PAGE LOG:', msg.text()));
await page.evaluate(() => console.log(`url is ${location.href}`));
```
### Use the debugger in the browser
1. Set [`devtools`](../api/puppeteer.browserlaunchargumentoptions) to
`true` when launching Puppeteer:
```ts
const browser = await puppeteer.launch({devtools: true});
```
2. Add `debugger` inside any client code you want debugged. For example,
```ts
await page.evaluate(() => {
debugger;
});
```
The Browser will now stop in the location the `debugger` word is found in
debug mode.
## Debugging methods for server code
### Use the debugger in Node.js (Chrome/Chromium-only)
Since server code intermingles with client code, this method of debugging is
closely tied with the browser. For example, you can step over
`await page.click()` in the server script and see the click happen in the
browser.
Note that you won't be able to run `await page.click()` in DevTools console due
to this
[Chromium bug](https://bugs.chromium.org/p/chromium/issues/detail?id=833928), so
if you want to try something out, you have to add it to your test file.
1. Set [`headless`](../api/puppeteer.browserlaunchargumentoptions) to
`false`.
2. Add `debugger` to any server code you want debugged. For example,
```ts
debugger;
await page.click('a[target=_blank]');
```
3. Run your server code with `--inspect-brk`. For example,
```bash
node --inspect-brk path/to/script.js
```
4. In the opened Chrome/Chromium browser, open `chrome://inspect/#devices` and
click `inspect`.
5. In the newly opened test browser, press `F8` to resume test execution.
6. Now your `debugger` statement will be hit and you can debug in the test
browser.
### Log DevTools protocol traffic
If all else fails, it's possible there may be an issue between Puppeteer and the
DevTools protocol. You can debug this by setting the `DEBUG` environment
variable before running your script. This will log internal traffic via
[`debug`](https://github.com/visionmedia/debug) under the `puppeteer` namespace.
```bash
# Basic verbose logging
env DEBUG="puppeteer:*" node script.js
# Prevent truncating of long messages
env DEBUG="puppeteer:*" env DEBUG_MAX_STRING_LENGTH=null node script.js
# Protocol traffic can be rather noisy. This example filters out all Network domain messages
env DEBUG="puppeteer:*" env DEBUG_COLORS=true node script.js 2>&1 | grep -v '"Network'
# Filter out all protocol messages but keep all other logging
env DEBUG="puppeteer:*,-puppeteer:protocol:*" node script.js
```
### Log pending protocol calls
If you encounter issues with async Puppeteer calls not getting resolved, try logging
pending callbacks by using the [`debugInfo`](https://pptr.dev/api/puppeteer.browser/#properties) interface
to see what call is the cause:
```ts
console.log(browser.debugInfo.pendingProtocolErrors);
```
The getter returns a list of `Error` objects and the stacktraces of the error objects
indicate which code triggered a protocol call.
## Debugging methods for the browser code
### Print browser logs
If the browser unexpectedly crashes or does not launch properly, it could be useful
to inspect logs from the browser process by setting the launch attribute `dumpio` to `true`.
```ts
const browser = await puppeteer.launch({
dumpio: true,
});
```
In this case, Puppeteer forwards browser logs to the Node process' stdio.