<titledata-rh="true">Debugging | Puppeteer</title><metadata-rh="true"name="twitter:card"content="summary_large_image"><metadata-rh="true"property="og:url"content="https://pptr.dev/next/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="current"><metadata-rh="true"name="docusaurus_tag"content="docs-default-current"><metadata-rh="true"name="docsearch:version"content="current"><metadata-rh="true"name="docsearch:docusaurus_tag"content="docs-default-current"><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/next/guides/debugging"><linkdata-rh="true"rel="alternate"href="https://pptr.dev/next/guides/debugging"hreflang="en"><linkdata-rh="true"rel="alternate"href="https://pptr.dev/next/guides/debugging"hreflang="x-default"><linkrel="stylesheet"href="/assets/css/styles.121c39a6.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
(which we call <em>server code</em>), and
<ahref="/next/guides/[`Page.evaluate()`](https://pptr.dev/api/puppeteer.page.evaluate)">code running in the browser</a>
(which we call <em>client code</em>). There is also a third possible source being the
browser itself (which we call <em>internal code</em>), but if you suspect this is the
source <strong>after attempting the methods below</strong>, we suggest
<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="https://pptr.dev/api/puppeteer.browserlaunchargumentoptions.headless"target="_blank"rel="noopener noreferrer"><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
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
<ahref="https://github.com/visionmedia/debug"target="_blank"rel="noopener noreferrer"><code>debug</code></a> under the <code>puppeteer</code> namespace.</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"># Basic verbose logging</span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain">env DEBUG="puppeteer:*" node script.js</span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"style="display:inline-block"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"># Protocol traffic can be rather noisy. This example filters out all Network domain messages</span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain">env DEBUG="puppeteer:*" env DEBUG_COLORS=true node script.js 2>&1 | grep -v '"Network'</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></div></article><navclass="pagination-nav docusaurus-mt-lg"aria-label="Docs pages navigation"><aclass="pagination-nav__link pagination-nav__link--prev"href="/next/guides/chrome-extensions"><divclass="pagination-nav__sublabel">Previous</div><divclass="pagination-nav__label">Chrome Extensions</div></a><aclass="pagination-nav__link pagination-nav__link--next"href="/next/guides/docker"><divclass="pagination-nav__sublabel">Next</div><divclass="pagination-nav__label">Docker</div></a></nav></div></div><divclass="col col--3"><divclass="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ulclass="table-of-contents table-of-contents__left-border"><li><ahref="#background"class="table-of-contents__link toc-highlight">Background</a></li><li><ahref="#debugging-methods-for-all-situations"class="table-of-contents__link toc-highlight">Debugging methods for all situations</a><ul><li><ahref="#turn-off-headless"class="table-of-contents__link toc-highlight">Turn off <code>headless</code></a></li><li><ahref="#puppeteer-slow-mo"class="table-of-contents__link toc-highlight">Puppeteer "slow-mo"</a></li></ul></li><li><ahref="#debugging-methods-for-client-code"class="table-of-contents__link toc-highlight">Debugging methods for client code</a><ul><li><ahref="#capture-console-output"class="table-of-contents__link toc-highlight">Capture <code>console.*</code> output</a></li><li><ahref="#use-the-debugger-in-the-browser"class="table-of-contents__link toc-highlight">Use the debugger in the browser</a></li></ul></li><li><ahref="#debugging-methods-for-server-code"class="table-of-contents__link toc-highlight">Debugging methods for server code</a><ul><li><ahref="#use-the-debugger-in-nodejs-chromechromium-only"class="table-of-contents__link toc-highlight">Use the debugger in Node.js (Chrome/Chromium-only)</a></li><li><ahref="#use-ndb"class="table-of-contents__link toc-highlight">Use ndb</a></li><li><ahref="#log-devtools-protocol-traffic"class="table-of-contents__link toc-highlight">Log DevTools protocol traffic</a></li></ul></li></ul></div></div></div></div></main></div></div><footerclass="footer footer--dark"><divclass="container container-fluid"><divclass="row footer__links"><divclass="col footer__col"><divclass="footer__title">Community</div><ulclass="footer__itemsclean-
