puppeteer/assets/js/fd0dde2d.1ef48a72.js

"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[91877],{3905:(e,t,r)=>{r.d(t,{Zo:()=>u,kt:()=>c});var n=r(67294);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function a(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,n)}return r}function i(e){for(var t=1;t<arguments.length;t++){var r=null!=arguments[t]?arguments[t]:{};t%2?a(Object(r),!0).forEach((function(t){o(e,t,r[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(r)):a(Object(r)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(r,t))}))}return e}function p(e,t){if(null==e)return{};var r,n,o=function(e,t){if(null==e)return{};var r,n,o={},a=Object.keys(e);for(n=0;n<a.length;n++)r=a[n],t.indexOf(r)>=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(n=0;n<a.length;n++)r=a[n],t.indexOf(r)>=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var s=n.createContext({}),l=function(e){var t=n.useContext(s),r=t;return e&&(r="function"==typeof e?e(t):i(i({},t),e)),r},u=function(e){var t=l(e.components);return n.createElement(s.Provider,{value:t},e.children)},h={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},m=n.forwardRef((function(e,t){var r=e.components,o=e.mdxType,a=e.originalType,s=e.parentName,u=p(e,["components","mdxType","originalType","parentName"]),m=l(r),c=o,d=m["".concat(s,".").concat(c)]||m[c]||h[c]||a;return r?n.createElement(d,i(i({ref:t},u),{},{components:r})):n.createElement(d,i({ref:t},u))}));function c(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=r.length,i=new Array(a);i[0]=m;var p={};for(var s in t)hasOwnProperty.call(t,s)&&(p[s]=t[s]);p.originalType=e,p.mdxType="string"==typeof e?e:o,i[1]=p;for(var l=2;l<a;l++)i[l]=r[l];return n.createElement.apply(null,i)}return n.createElement.apply(null,r)}m.displayName="MDXCreateElement"},39922:(e,t,r)=>{r.r(t),r.d(t,{assets:()=>l,contentTitle:()=>p,default:()=>m,frontMatter:()=>i,metadata:()=>s,toc:()=>u});r(67294);var n=r(3905);function o(){return o=Object.assign||function(e){for(var t=1;t<arguments.length;t++){var r=arguments[t];for(var n in r)Object.prototype.hasOwnProperty.call(r,n)&&(e[n]=r[n])}return e},o.apply(this,arguments)}function a(e,t){if(null==e)return{};var r,n,o=function(e,t){if(null==e)return{};var r,n,o={},a=Object.keys(e);for(n=0;n<a.length;n++)r=a[n],t.indexOf(r)>=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(n=0;n<a.length;n++)r=a[n],t.indexOf(r)>=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}const i={},p="FAQ",s={unversionedId:"faq",id:"version-21.3.0/faq",title:"FAQ",description:"Q: Who maintains Puppeteer?",source:"@site/versioned_docs/version-21.3.0/faq.md",sourceDirName:".",slug:"/faq",permalink:"/faq",draft:!1,tags:[],version:"21.3.0",frontMatter:{},sidebar:"docs",previous:{title:"Contributing",permalink:"/contributing"}},l={},u=[{value:"Q: Who maintains Puppeteer?",id:"q-who-maintains-puppeteer",level:2},{value:"Q: What is the status of cross-browser support?",id:"q-what-is-the-status-of-cross-browser-support",level:2},{value:"Q: What are Puppeteer\u2019s goals and principles?",id:"q-what-are-puppeteers-goals-and-principles",level:2},{value:"Q: Is Puppeteer replacing Selenium/WebDriver?",id:"q-is-puppeteer-replacing-seleniumwebdriver",level:2},{value:"Q: Why doesn\u2019t Puppeteer v.XXX work with Chromium v.YYY?",id:"q-why-doesnt-puppeteer-vxxx-work-with-chromium-vyyy",level:2},{value:"Q: Which Chrome version does Puppeteer use?",id:"q-which-chrome-version-does-puppeteer-use",level:2},{value:"Q: Which Firefox version does Puppeteer use?",id:"q-which-firefox-version-does-puppeteer-use",level:2},{value:"Q: What\u2019s considered a \u201cNavigation\u201d?",id:"q-whats-considered-a-navigation",level:4},{value:"Q: What\u2019s the difference between a \u201ctrusted&quot; and &quot;untrusted&quot; input event?",id:"q-whats-the-difference-between-a-trusted-and-untrusted-input-event",level:4},{value:"Q: What features does Puppeteer not support?",id:"q-what-features-does-puppeteer-not-support",level:4},{value:"Q: I am having trouble installing / running Puppeteer in my test environment. Where should I look for help?",id:"q-i-am-having-trouble-installing--running-puppeteer-in-my-test-environment-where-should-i-look-for-help",level:4},{value:"Q: I have more questions! Where do I ask?",id:"q-i-have-more-questions-where-do-i-ask",level:4}],h={toc:u};function m(e){var{components:t}=e,r=a(e,["components"]);return(0,n.kt)("wrapper",o({},h,r,{components:t,mdxType:"MDXLayout"}),(0,n.kt)("h1",o({},{id:"faq"}),"FAQ"),(0,n.kt)("h2",o({},{id:"q-who-maintains-puppeteer"}),"Q: Who maintains Puppeteer?"),(0,n.kt)("p",null,"The Chrome DevTools team maintains the library, but we'd love your help and\nexpertise on the project! See our\n",(0,n.kt)("a",o({parentName:"p"},{href:"https://pptr.dev/contributing"}),"contributing guide"),"."),(0,n.kt)("h2",o({},{id:"q-what-is-the-status-of-cross-browser-support"}),"Q: What is the status of cross-browser support?"),(0,n.kt)("p",null,"Official Firefox support is currently experimental. The ongoing collaboration\nwith Mozilla aims to support common end-to-end testing use cases, for which\ndevelopers expect cross-browser coverage. The Puppeteer team needs input from\nusers to stabilize Firefox support and to bring missing APIs to our attention."),(0,n.kt)("p",null,"From Puppeteer v2.1.0 onwards you can specify\n",(0,n.kt)("a",o({parentName:"p"},{href:"./api/puppeteer.puppeteernode.launch"}),(0,n.kt)("inlineCode",{parentName:"a"},"puppeteer.launch({product: 'firefox'})")),"\nto run your Puppeteer scripts in Firefox Nightly, without any additional custom\npatches. While\n",(0,n.kt)("a",o({parentName:"p"},{href:"https://www.npmjs.com/package/puppeteer-firefox"}),"an older experiment")," required\na patched version of Firefox,\n",(0,n.kt)("a",o({parentName:"p"},{href:"https://wiki.mozilla.org/Remote"}),"the current approach")," works with \u201cstock\u201d\nFirefox."),(0,n.kt)("p",null,"We will continue to collaborate with other browser vendors to bring Puppeteer\nsupport to browsers such as Safari. This effort includes exploration of a\nstandard for executing cross-browser commands (instead of relying on the\nnon-standard DevTools Protocol used by Chrome)."),(0,n.kt)("h2",o({},{id:"q-what-are-puppeteers-goals-and-principles"}),"Q: What are Puppeteer\u2019s goals and principles?"),(0,n.kt)("p",null,"The goals of the project are:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"Provide a slim, canonical library that highlights the capabilities of the\n",(0,n.kt)("a",o({parentName:"li"},{href:"https://chromedevtools.github.io/devtools-protocol/"}),"DevTools Protocol"),"."),(0,n.kt)("li",{parentName:"ul"},"Provide a reference implementation for similar testing libraries. Eventually,\nthese other frameworks could adopt Puppeteer as their foundational layer."),(0,n.kt)("li",{parentName:"ul"},"Grow the adoption of headless/automated browser testing."),(0,n.kt)("li",{parentName:"ul"},"Help dogfood new DevTools Protocol features...and catch bugs!"),(0,n.kt)("li",{parentName:"ul"},"Learn more about the pain points of automated browser testing and help fill\nthose gaps.")),(0,n.kt)("p",null,"We adapt\n",(0,n.kt)("a",o({parentName:"p"},{href:"https://www.chromium.org/developers/core-principles"}),"Chromium principles")," to\nhelp us drive product decisions:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("strong",{parentName:"li"},"Speed"),": Puppeteer has almost zero performance overhead over an automated\npage."),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("strong",{parentName:"li"},"Security"),": Puppeteer operates off-process with respect to Chromium, making\nit safe to automate potentially malicious pages."),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("strong",{parentName:"li"},"Stability"),": Puppeteer should not be flaky and should not leak memory."),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("strong",{parentName:"li"},"Simplicity"),": Puppeteer provides a high-level API that\u2019s easy to use,\nunderstand, and debug.")),(0,n.kt)("h2",o({},{id:"q-is-puppeteer-replacing-seleniumwebdriver"}),"Q: Is Puppeteer replacing Selenium/WebDriver?"),(0,n.kt)("p",null,(0,n.kt)("strong",{parentName:"p"},"No"),". Both projects are valuable for very different reasons:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"Selenium/WebDriver focuses on cross-browser automation; its value proposition\nis a single standard API that works across all major browsers."),(0,n.kt)("li",{parentName:"ul"},"Puppeteer focuses on Chromium; its value proposition is richer functionality\nand higher reliability.")),(0,n.kt)("p",null,"That said, you ",(0,n.kt)("strong",{parentName:"p"},"can")," use Puppeteer to run tests against Chromium, e.g. using\nthe community-driven\n",(0,n.kt)("a",o({parentName:"p"},{href:"https://github.com/smooth-code/jest-puppeteer"}),"jest-puppeteer"),". While this\nprobably shouldn\u2019t be your only testing solution, it does have a few good points\ncompared to WebDriver:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"Puppeteer requires zero setup and comes bundled with the Chromium version it\nworks best with, making it\n",(0,n.kt)("a",o({parentName:"li"},{href:"https://github.com/puppeteer/puppeteer/#getting-started"}),"very easy to start with"),".\nAt the end of the day, it\u2019s better to have a few tests running chromium-only,\nthan no tests at all."),(0,n.kt)("li",{parentName:"ul"},"Puppeteer has event-driven architecture, which removes a lot of potential\nflakiness. There\u2019s no need for evil \u201csleep(1000)\u201d calls in puppeteer scripts."),(0,n.kt)("li",{parentName:"ul"},"Puppeteer runs headless by default, which makes it fast to run. Puppeteer\nv1.5.0 also exposes browser contexts, making it possible to efficiently\nparallelize test execution."),(0,n.kt)("li",{parentName:"ul"},"Puppeteer shines when it comes to debugging: flip the \u201cheadless\u201d bit to false,\nadd \u201cslowMo\u201d, and you\u2019ll see what the browser is doing. You can even open\nChrome DevTools to inspect the test environment.")),(0,n.kt)("h2",o({},{id:"q-why-doesnt-puppeteer-vxxx-work-with-chromium-vyyy"}),"Q: Why doesn\u2019t Puppeteer v.XXX work with Chromium v.YYY?"),(0,n.kt)("p",null,"We see Puppeteer as an ",(0,n.kt)("strong",{parentName:"p"},"indivisible entity")," with Chromium. Each version of\nPuppeteer bundles a specific version of Chromium \u2013 ",(0,n.kt)("strong",{parentName:"p"},"the only")," version it is\nguaranteed to work with."),(0,n.kt)("p",null,"This is not an artificial constraint: A lot of work on Puppeteer is actually\ntaking place in the Chromium repository. Here\u2019s a typical story:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"A Puppeteer bug is reported:\n",(0,n.kt)("a",o({parentName:"li"},{href:"https://github.com/puppeteer/puppeteer/issues/2709"}),"https://github.com/puppeteer/puppeteer/issues/2709")),(0,n.kt)("li",{parentName:"ul"},"It turned out this is an issue with the DevTools protocol, so we\u2019re fixing it\nin Chromium: ",(0,n.kt)("a",o({parentName:"li"},{href:"https://chromium-review.googlesource.com/c/chromium/src/+/1102154"}),"https://chromium-review.googlesource.com/c/chromium/src/+/1102154")),(0,n.kt)("li",{parentName:"ul"},"Once the upstream fix is landed, we roll updated Chromium into Puppeteer:\n",(0,n.kt)("a",o({parentName:"li"},{href:"https://github.com/puppeteer/puppeteer/pull/2769"}),"https://github.com/puppeteer/puppeteer/pull/2769"))),(0,n.kt)("h2",o({},{id:"q-which-chrome-version-does-puppeteer-use"}),"Q: Which Chrome version does Puppeteer use?"),(0,n.kt)("p",null,"Look for the ",(0,n.kt)("inlineCode",{parentName:"p"},"chrome")," entry in\n",(0,n.kt)("a",o({parentName:"p"},{href:"https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/revisions.ts"}),"revisions.ts"),"."),(0,n.kt)("h2",o({},{id:"q-which-firefox-version-does-puppeteer-use"}),"Q: Which Firefox version does Puppeteer use?"),(0,n.kt)("p",null,"Since Firefox support is experimental, Puppeteer downloads the latest\n",(0,n.kt)("a",o({parentName:"p"},{href:"https://wiki.mozilla.org/Nightly"}),"Firefox Nightly")," when the ",(0,n.kt)("inlineCode",{parentName:"p"},"PUPPETEER_PRODUCT"),"\nenvironment variable is set to ",(0,n.kt)("inlineCode",{parentName:"p"},"firefox"),". That's also why the value of ",(0,n.kt)("inlineCode",{parentName:"p"},"firefox"),"\nin\n",(0,n.kt)("a",o({parentName:"p"},{href:"https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/revisions.ts"}),"revisions.ts"),"\nis ",(0,n.kt)("inlineCode",{parentName:"p"},"latest")," -- Puppeteer isn't tied to a particular Firefox version."),(0,n.kt)("p",null,"To fetch Firefox Nightly as part of Puppeteer installation:"),(0,n.kt)("pre",null,(0,n.kt)("code",o({parentName:"pre"},{className:"language-bash"}),"PUPPETEER_PRODUCT=firefox npm i puppeteer\n")),(0,n.kt)("h4",o({},{id:"q-whats-considered-a-navigation"}),"Q: What\u2019s considered a \u201cNavigation\u201d?"),(0,n.kt)("p",null,"From Puppeteer\u2019s standpoint, ",(0,n.kt)("strong",{parentName:"p"},"\u201cnavigation\u201d is anything that changes a page\u2019s\nURL"),". Aside from regular navigation where the browser hits the network to fetch\na new document from the web server, this includes\n",(0,n.kt)("a",o({parentName:"p"},{href:"https://www.w3.org/TR/html5/single-page.html#scroll-to-fragid"}),"anchor navigations"),"\nand ",(0,n.kt)("a",o({parentName:"p"},{href:"https://developer.mozilla.org/en-US/docs/Web/API/History_API"}),"History API"),"\nusage."),(0,n.kt)("p",null,"With this definition of \u201cnavigation,\u201d ",(0,n.kt)("strong",{parentName:"p"},"Puppeteer works seamlessly with\nsingle-page applications.")),(0,n.kt)("h4",o({},{id:"q-whats-the-difference-between-a-trusted-and-untrusted-input-event"}),'Q: What\u2019s the difference between a \u201ctrusted" and "untrusted" input event?'),(0,n.kt)("p",null,"In browsers, input events could be divided into two big groups: trusted vs.\nuntrusted."),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("strong",{parentName:"li"},"Trusted events"),": events generated by users interacting with the page, e.g.\nusing a mouse or keyboard."),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("strong",{parentName:"li"},"Untrusted event"),": events generated by Web APIs, e.g. ",(0,n.kt)("inlineCode",{parentName:"li"},"document.createEvent"),"\nor ",(0,n.kt)("inlineCode",{parentName:"li"},"element.click()")," methods.")),(0,n.kt)("p",null,"Websites can distinguish between these two groups:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"using an\n",(0,n.kt)("a",o({parentName:"li"},{href:"https://developer.mozilla.org/en-US/docs/Web/API/Event/isTrusted"}),(0,n.kt)("inlineCode",{parentName:"a"},"Event.isTrusted")),"\nevent flag"),(0,n.kt)("li",{parentName:"ul"},"sniffing for accompanying events. For example, every trusted ",(0,n.kt)("inlineCode",{parentName:"li"},"'click'")," event\nis preceded by ",(0,n.kt)("inlineCode",{parentName:"li"},"'mousedown'")," and ",(0,n.kt)("inlineCode",{parentName:"li"},"'mouseup'")," events.")),(0,n.kt)("p",null,"For automation purposes it\u2019s important to generate trusted events. ",(0,n.kt)("strong",{parentName:"p"},"All input\nevents generated with Puppeteer are trusted and fire proper accompanying\nevents.")," If, for some reason, one needs an untrusted event, it\u2019s always\npossible to hop into a page context with ",(0,n.kt)("inlineCode",{parentName:"p"},"page.evaluate")," and generate a fake\nevent:"),(0,n.kt)("pre",null,(0,n.kt)("code",o({parentName:"pre"},{className:"language-ts"}),"await page.evaluate(() => {\n  document.querySelector('button[type=submit]').click();\n});\n")),(0,n.kt)("h4",o({},{id:"q-what-features-does-puppeteer-not-support"}),"Q: What features does Puppeteer not support?"),(0,n.kt)("p",null,"You may find that Puppeteer does not behave as expected when controlling pages\nthat incorporate audio and video. (For example,\n",(0,n.kt)("a",o({parentName:"p"},{href:"https://github.com/puppeteer/puppeteer/issues/291"}),"video playback/screenshots is likely to fail"),".)\nThere are two reasons for this:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"Puppeteer is bundled with ",(0,n.kt)("a",o({parentName:"li"},{href:"https://goo.gle/chrome-for-testing"}),"Chrome for Testing")," \u2014 not the regular Chrome \u2014 and so by default, it\ninherits all of\n",(0,n.kt)("a",o({parentName:"li"},{href:"https://www.chromium.org/audio-video"}),"Chromium's media-related limitations"),".\nThis means that Puppeteer does not support licensed formats such as AAC or\nH.264. (However, it is possible to force Puppeteer to use a\nseparately-installed version Chrome instead of Chromium via the\n",(0,n.kt)("a",o({parentName:"li"},{href:"./api/puppeteer.launchoptions"}),(0,n.kt)("inlineCode",{parentName:"a"},"executablePath")," option to ",(0,n.kt)("inlineCode",{parentName:"a"},"puppeteer.launch")),".\nYou should only use this configuration if you need an official release of\nChrome that supports these media formats.)"),(0,n.kt)("li",{parentName:"ul"},"Since Puppeteer (in all configurations) controls a desktop version of\nChromium/Chrome, features that are only supported by the mobile version of\nChrome are not supported. This means that Puppeteer\n",(0,n.kt)("a",o({parentName:"li"},{href:"https://caniuse.com/#feat=http-live-streaming"}),"does not support HTTP Live Streaming (HLS)"),".")),(0,n.kt)("h4",o({},{id:"q-i-am-having-trouble-installing--running-puppeteer-in-my-test-environment-where-should-i-look-for-help"}),"Q: I am having trouble installing / running Puppeteer in my test environment. Where should I look for help?"),(0,n.kt)("p",null,"We have a\n",(0,n.kt)("a",o({parentName:"p"},{href:"https://pptr.dev/troubleshooting"}),"troubleshooting"),"\nguide for various operating systems that lists the required dependencies."),(0,n.kt)("h4",o({},{id:"q-i-have-more-questions-where-do-i-ask"}),"Q: I have more questions! Where do I ask?"),(0,n.kt)("p",null,"There are many ways to get help on Puppeteer:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("a",o({parentName:"li"},{href:"https://github.com/puppeteer/puppeteer/issues"}),"bugtracker")),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("a",o({parentName:"li"},{href:"https://stackoverflow.com/questions/tagged/puppeteer"}),"Stack Overflow"))),(0,n.kt)("p",null,"Make sure to search these channels before posting your question."))}m.isMDXComponent=!0}}]);