<titledata-rh="true">Debugging | Puppeteer</title><metadata-rh="true"name="viewport"content="width=device-width,initial-scale=1"><metadata-rh="true"name="twitter:card"content="summary_large_image"><metadata-rh="true"property="og:url"content="https://pptr.dev/guides/debugging"><metadata-rh="true"name="docusaurus_locale"content="en"><metadata-rh="true"name="docsearch:language"content="en"><metadata-rh="true"name="docusaurus_version"content="19.2.0"><metadata-rh="true"name="docusaurus_tag"content="docs-default-19.2.0"><metadata-rh="true"name="docsearch:version"content="19.2.0"><metadata-rh="true"name="docsearch:docusaurus_tag"content="docs-default-19.2.0"><metadata-rh="true"property="og:title"content="Debugging | Puppeteer"><metadata-rh="true"name="description"content="Debugging with Puppeteer can be an arduous task. There is no single method for"><metadata-rh="true"property="og:description"content="Debugging with Puppeteer can be an arduous task. There is no single method for"><linkdata-rh="true"rel="icon"href="/img/favicon.ico"><linkdata-rh="true"rel="canonical"href="https://pptr.dev/guides/debugging"><linkdata-rh="true"rel="alternate"href="https://pptr.dev/guides/debugging"hreflang="en"><linkdata-rh="true"rel="alternate"href="https://pptr.dev/guides/debugging"hreflang="x-default"><linkrel="stylesheet"href="/assets/css/styles.acc20982.css">
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 <em>several</em> methods for debugging which hopefully does cover all possible
issues.</p><h2class="anchor anchorWithStickyNavbar_LWe7"id="background">Background<aclass="hash-link"href="#background"title="Direct link to heading"></a></h2><p>In general, there are two possible sources of an issue: Code running on Node.js
<ahref="https://github.com/puppeteer/puppeteer/issues/new/choose"target="_blank"rel="noopener noreferrer">filing an issue</a>.</p><h2class="anchor anchorWithStickyNavbar_LWe7"id="debugging-methods-for-all-situations">Debugging methods for all situations<aclass="hash-link"href="#debugging-methods-for-all-situations"title="Direct link to heading"></a></h2><p>These methods can be used to debug any situation. These should be used as a
quick sanity check before diving into more complex methods.</p><h3class="anchor anchorWithStickyNavbar_LWe7"id="turn-off-headless">Turn off <ahref="/api/puppeteer.browserlaunchargumentoptions.headless"><code>headless</code></a><aclass="hash-link"href="#turn-off-headless"title="Direct link to heading"></a></h3><p>Sometimes it's useful to see what the browser is displaying. Instead of
debug mode.</p></li></ol><h2class="anchor anchorWithStickyNavbar_LWe7"id="debugging-methods-for-server-code">Debugging methods for server code<aclass="hash-link"href="#debugging-methods-for-server-code"title="Direct link to heading"></a></h2><h3class="anchor anchorWithStickyNavbar_LWe7"id="use-the-debugger-in-nodejs-chromechromium-only">Use the debugger in Node.js (Chrome/Chromium-only)<aclass="hash-link"href="#use-the-debugger-in-nodejs-chromechromium-only"title="Direct link to heading"></a></h3><p>Since server code intermingles with client code, this method of debugging is
closely tied with the browser. For example, you can step over
<code>await page.click()</code> in the server script and see the click happen in the
browser.</p><p>Note that you won't be able to run <code>await page.click()</code> in DevTools console due
to this
<ahref="https://bugs.chromium.org/p/chromium/issues/detail?id=833928"target="_blank"rel="noopener noreferrer">Chromium bug</a>, so
if you want to try something out, you have to add it to your test file.</p><ol><li><p>Set <ahref="/api/puppeteer.browserlaunchargumentoptions.headless"><code>headless</code></a> to
<code>false</code>.</p></li><li><p>Add <code>debugger</code> to any server code you want debugged. For example,</p><divclass="language-ts codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-ts codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><spanclass="token keyword"style="color:#00009f">debugger</span><spanclass="token punctuation"style="color:#393A34">;</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">await</span><spanclass="token plain"> page</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">click</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e3116c">'a[target=_blank]'</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">;</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgclass="copyButtonIcon_y97N"viewBox="0 0 24 24"><pathd="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgclass="copyButtonSuccessIcon_LjdS"viewBox="0 0 24 24"><pathd="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></li><li><p>Run your server code with <code>--inspect-brk</code>. For example,</p><divclass="language-sh codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-sh codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><spanclass="token plain">node --inspect-brk path/to/script.js</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgclass="copyButtonIcon_y97N"viewBox="0 0 24 24"><pathd="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgclass="copyButtonSuccessIcon_LjdS"viewBox="0 0 24 24"><pathd="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></li><li><p>In the opened Chrome/Chromium browser, open <code>chrome://inspect/#devices</code> and
click <code>inspect</code>.</p></li><li><p>In the newly opened test browser, press <code>F8</code> to resume test execution.</p></li><li><p>Now your <code>debugger</code> statement will be hit and you can debug in the test
browser.</p></li></ol><h3class="anchor anchorWithStickyNavbar_LWe7"id="use-ndb">Use <ahref="https://github.com/GoogleChromeLabs/ndb"target="_blank"rel="noopener noreferrer">ndb</a><aclass="hash-link"href="#use-ndb"title="Direct link to heading"></a></h3><ol><li><p>Install <code>ndb</code>:</p><divclass="language-sh codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-sh codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><spanclass="token plain">npm install -g ndb</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgclass="copyButtonIcon_y97N"viewBox="0 0 24 24"><pathd="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgclass="copyButtonSuccessIcon_LjdS"viewBox="0 0 24 24"><pathd="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></li><li><p>Add <code>debugger</code> to any server code you want debugged. For example,</p><divclass="language-ts codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-ts codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><spanclass="token keyword"style="color:#00009f">debugger</span><spanclass="token punctuation"style="color:#393A34">;</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">await</span><spanclass="token plain"> page</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">click</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e3116c">'a[target=_blank]'</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">;</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgclass="copyButtonIcon_y97N"viewBox="0 0 24 24"><pathd="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgclass="copyButtonSuccessIcon_LjdS"viewBox="0 0 24 24"><pathd="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></li><li><p>Add <code>ndb</code> before your test command. For example,</p><divclass="language-sh codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-sh codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><spanclass="token plain">ndb node path/to/script.js</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgclass="copyButtonIcon_y97N"viewBox="0 0 24 24"><pathd="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgclass="copyButtonSuccessIcon_LjdS"viewBox="0 0 24 24"><pathd="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></li><li><p>Debug your test inside chromium like a boss!</p></li></ol><h3class="anchor
DevTools protocol. You can debug this by setting the <code>DEBUG</code> environment
variable before running your script. This will log internal traffic via
