puppeteer/assets/js/03a88bad.88308cd7.js

"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[26568],{3905:(e,t,r)=>{r.d(t,{Zo:()=>u,kt:()=>m});var n=r(67294);function a(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function p(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 o(e){for(var t=1;t<arguments.length;t++){var r=null!=arguments[t]?arguments[t]:{};t%2?p(Object(r),!0).forEach((function(t){a(e,t,r[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(r)):p(Object(r)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(r,t))}))}return e}function i(e,t){if(null==e)return{};var r,n,a=function(e,t){if(null==e)return{};var r,n,a={},p=Object.keys(e);for(n=0;n<p.length;n++)r=p[n],t.indexOf(r)>=0||(a[r]=e[r]);return a}(e,t);if(Object.getOwnPropertySymbols){var p=Object.getOwnPropertySymbols(e);for(n=0;n<p.length;n++)r=p[n],t.indexOf(r)>=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var l=n.createContext({}),s=function(e){var t=n.useContext(l),r=t;return e&&(r="function"==typeof e?e(t):o(o({},t),e)),r},u=function(e){var t=s(e.components);return n.createElement(l.Provider,{value:t},e.children)},c={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},h=n.forwardRef((function(e,t){var r=e.components,a=e.mdxType,p=e.originalType,l=e.parentName,u=i(e,["components","mdxType","originalType","parentName"]),h=s(r),m=a,d=h["".concat(l,".").concat(m)]||h[m]||c[m]||p;return r?n.createElement(d,o(o({ref:t},u),{},{components:r})):n.createElement(d,o({ref:t},u))}));function m(e,t){var r=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var p=r.length,o=new Array(p);o[0]=h;var i={};for(var l in t)hasOwnProperty.call(t,l)&&(i[l]=t[l]);i.originalType=e,i.mdxType="string"==typeof e?e:a,o[1]=i;for(var s=2;s<p;s++)o[s]=r[s];return n.createElement.apply(null,o)}return n.createElement.apply(null,r)}h.displayName="MDXCreateElement"},39942:(e,t,r)=>{r.r(t),r.d(t,{assets:()=>s,contentTitle:()=>i,default:()=>h,frontMatter:()=>o,metadata:()=>l,toc:()=>u});r(67294);var n=r(3905);function a(){return a=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},a.apply(this,arguments)}function p(e,t){if(null==e)return{};var r,n,a=function(e,t){if(null==e)return{};var r,n,a={},p=Object.keys(e);for(n=0;n<p.length;n++)r=p[n],t.indexOf(r)>=0||(a[r]=e[r]);return a}(e,t);if(Object.getOwnPropertySymbols){var p=Object.getOwnPropertySymbols(e);for(n=0;n<p.length;n++)r=p[n],t.indexOf(r)>=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}const o={},i="Puppeteer",l={unversionedId:"index",id:"index",title:"Puppeteer",description:"Build status",source:"@site/../docs/index.md",sourceDirName:".",slug:"/",permalink:"/next/",draft:!1,tags:[],version:"current",frontMatter:{},sidebar:"docs",next:{title:"Guides",permalink:"/next/category/guides"}},s={},u=[{value:"Guides | API | FAQ | Contributing | Troubleshooting",id:"guides--api--faq--contributing--troubleshooting",level:4},{value:"What can I do?",id:"what-can-i-do",level:4},{value:"Getting Started",id:"getting-started",level:2},{value:"Installation",id:"installation",level:3},{value:"Configuration",id:"configuration",level:4},{value:"<code>puppeteer-core</code>",id:"puppeteer-core",level:4},{value:"Usage",id:"usage",level:3},{value:"Example",id:"example",level:4},{value:"Default runtime settings",id:"default-runtime-settings",level:3},{value:"Using Docker",id:"using-docker",level:4},{value:"Using Chrome Extensions",id:"using-chrome-extensions",level:4},{value:"Resources",id:"resources",level:2},{value:"Contributing",id:"contributing",level:2},{value:"FAQ",id:"faq",level:2}],c={toc:u};function h(e){var{components:t}=e,r=p(e,["components"]);return(0,n.kt)("wrapper",a({},c,r,{components:t,mdxType:"MDXLayout"}),(0,n.kt)("h1",a({},{id:"puppeteer"}),"Puppeteer"),(0,n.kt)("p",null,(0,n.kt)("a",a({parentName:"p"},{href:"https://github.com/puppeteer/puppeteer/actions?query=workflow%3ACI"}),(0,n.kt)("img",a({parentName:"a"},{src:"https://github.com/puppeteer/puppeteer/workflows/CI/badge.svg",alt:"Build status"}))),"\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://npmjs.org/package/puppeteer"}),(0,n.kt)("img",a({parentName:"a"},{src:"https://img.shields.io/npm/v/puppeteer.svg",alt:"npm puppeteer package"})))),(0,n.kt)("img",{src:"https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png",height:"200",align:"right"}),(0,n.kt)("h4",a({},{id:"guides--api--faq--contributing--troubleshooting"}),(0,n.kt)("a",a({parentName:"h4"},{href:"https://pptr.dev/category/guides"}),"Guides")," | ",(0,n.kt)("a",a({parentName:"h4"},{href:"https://pptr.dev/api"}),"API")," | ",(0,n.kt)("a",a({parentName:"h4"},{href:"https://pptr.dev/faq"}),"FAQ")," | ",(0,n.kt)("a",a({parentName:"h4"},{href:"https://pptr.dev/contributing"}),"Contributing")," | ",(0,n.kt)("a",a({parentName:"h4"},{href:"https://pptr.dev/troubleshooting"}),"Troubleshooting")),(0,n.kt)("blockquote",null,(0,n.kt)("p",{parentName:"blockquote"},"Puppeteer is a Node.js library which provides a high-level API to control\nChrome/Chromium over the\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://chromedevtools.github.io/devtools-protocol/"}),"DevTools Protocol"),".\nPuppeteer runs in\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://developers.google.com/web/updates/2017/04/headless-chrome"}),"headless"),"\nmode by default, but can be configured to run in full (non-headless)\nChrome/Chromium.")),(0,n.kt)("h4",a({},{id:"what-can-i-do"}),"What can I do?"),(0,n.kt)("p",null,"Most things that you can do manually in the browser can be done using Puppeteer!\nHere are a few examples to get you started:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"Generate screenshots and PDFs of pages."),(0,n.kt)("li",{parentName:"ul"},'Crawl a SPA (Single-Page Application) and generate pre-rendered content (i.e.\n"SSR" (Server-Side Rendering)).'),(0,n.kt)("li",{parentName:"ul"},"Automate form submission, UI testing, keyboard input, etc."),(0,n.kt)("li",{parentName:"ul"},"Create an automated testing environment using the latest JavaScript and\nbrowser features."),(0,n.kt)("li",{parentName:"ul"},"Capture a\n",(0,n.kt)("a",a({parentName:"li"},{href:"https://developers.google.com/web/tools/chrome-devtools/evaluate-performance/reference"}),"timeline trace"),"\nof your site to help diagnose performance issues."),(0,n.kt)("li",{parentName:"ul"},"Test Chrome Extensions.")),(0,n.kt)("h2",a({},{id:"getting-started"}),"Getting Started"),(0,n.kt)("h3",a({},{id:"installation"}),"Installation"),(0,n.kt)("p",null,"To use Puppeteer in your project, run:"),(0,n.kt)("pre",null,(0,n.kt)("code",a({parentName:"pre"},{className:"language-bash"}),"npm i puppeteer\n# or `yarn add puppeteer`\n# or `pnpm i puppeteer`\n")),(0,n.kt)("p",null,"When you install Puppeteer, it automatically downloads a recent version of\nChromium (~170MB macOS, ~282MB Linux, ~280MB Windows) that is\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/faq#q-why-doesnt-puppeteer-vxxx-work-with-chromium-vyyy"}),"guaranteed to work"),"\nwith Puppeteer. For a version of Puppeteer without installation, see\n",(0,n.kt)("a",a({parentName:"p"},{href:"#puppeteer-core"}),(0,n.kt)("inlineCode",{parentName:"a"},"puppeteer-core")),"."),(0,n.kt)("h4",a({},{id:"configuration"}),"Configuration"),(0,n.kt)("p",null,"Puppeteer uses several defaults that can be customized through configuration\nfiles."),(0,n.kt)("p",null,"For example, to change the default cache directory Puppeteer uses to install\nbrowsers, you can add a ",(0,n.kt)("inlineCode",{parentName:"p"},".puppeteerrc.cjs")," (or ",(0,n.kt)("inlineCode",{parentName:"p"},"puppeteer.config.cjs"),") at the\nroot of your application with the contents"),(0,n.kt)("pre",null,(0,n.kt)("code",a({parentName:"pre"},{className:"language-js"}),"const {join} = require('path');\n\n/**\n * @type {import(\"puppeteer\").Configuration}\n */\nmodule.exports = {\n  // Changes the cache location for Puppeteer.\n  cacheDirectory: join(__dirname, '.cache', 'puppeteer'),\n};\n")),(0,n.kt)("p",null,"After adding the configuration file, you will need to remove and reinstall\n",(0,n.kt)("inlineCode",{parentName:"p"},"puppeteer")," for it to take effect."),(0,n.kt)("p",null,"See the ",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/guides/configuration"}),"configuration guide")," for more\ninformation."),(0,n.kt)("h4",a({},{id:"puppeteer-core"}),(0,n.kt)("inlineCode",{parentName:"h4"},"puppeteer-core")),(0,n.kt)("p",null,"Every release since v1.7.0 we publish two packages:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("a",a({parentName:"li"},{href:"https://www.npmjs.com/package/puppeteer"}),(0,n.kt)("inlineCode",{parentName:"a"},"puppeteer"))),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("a",a({parentName:"li"},{href:"https://www.npmjs.com/package/puppeteer-core"}),(0,n.kt)("inlineCode",{parentName:"a"},"puppeteer-core")))),(0,n.kt)("p",null,(0,n.kt)("inlineCode",{parentName:"p"},"puppeteer")," is a ",(0,n.kt)("em",{parentName:"p"},"product")," for browser automation. When installed, it downloads\na version of Chromium, which it then drives using ",(0,n.kt)("inlineCode",{parentName:"p"},"puppeteer-core"),". Being an\nend-user product, ",(0,n.kt)("inlineCode",{parentName:"p"},"puppeteer")," automates several workflows using reasonable\ndefaults ",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/guides/configuration"}),"that can be customized"),"."),(0,n.kt)("p",null,(0,n.kt)("inlineCode",{parentName:"p"},"puppeteer-core")," is a ",(0,n.kt)("em",{parentName:"p"},"library")," to help drive anything that supports DevTools\nprotocol. Being a library, ",(0,n.kt)("inlineCode",{parentName:"p"},"puppeteer-core")," is fully driven through its\nprogrammatic interface implying no defaults are assumed and ",(0,n.kt)("inlineCode",{parentName:"p"},"puppeteer-core"),"\nwill not download Chromium when installed."),(0,n.kt)("p",null,"You should use ",(0,n.kt)("inlineCode",{parentName:"p"},"puppeteer-core")," if you are\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/api/puppeteer.puppeteer.connect"}),"connecting to a remote browser"),"\nor ",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/api/puppeteer.browserfetcher"}),"managing browsers yourself"),".\nIf you are managing browsers yourself, you will need to call\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/api/puppeteer.puppeteernode.launch"}),(0,n.kt)("inlineCode",{parentName:"a"},"puppeteer.launch"))," with\nan an explicit\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/api/puppeteer.launchoptions.executablepath"}),(0,n.kt)("inlineCode",{parentName:"a"},"executablePath")),"\n(or ",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/api/puppeteer.launchoptions.channel"}),(0,n.kt)("inlineCode",{parentName:"a"},"channel"))," if it's\ninstalled in a standard location)."),(0,n.kt)("p",null,"When using ",(0,n.kt)("inlineCode",{parentName:"p"},"puppeteer-core"),", remember to change the import:"),(0,n.kt)("pre",null,(0,n.kt)("code",a({parentName:"pre"},{className:"language-ts"}),"import puppeteer from 'puppeteer-core';\n")),(0,n.kt)("h3",a({},{id:"usage"}),"Usage"),(0,n.kt)("p",null,"Puppeteer follows the latest\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://github.com/nodejs/Release#release-schedule"}),"maintenance LTS")," version of\nNode."),(0,n.kt)("p",null,"Puppeteer will be familiar to people using other browser testing frameworks. You\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/api/puppeteer.puppeteernode.launch"}),"launch"),"/",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/api/puppeteer.puppeteernode.connect"}),"connect"),"\na ",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/api/puppeteer.browser"}),"browser"),",\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/api/puppeteer.browser.newpage"}),"create")," some\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/api/puppeteer.page"}),"pages"),", and then manipulate them with\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/api"}),"Puppeteer's API"),"."),(0,n.kt)("p",null,"For more in-depth usage, check our ",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/category/guides"}),"guides"),"\nand ",(0,n.kt)("a",a({parentName:"p"},{href:"https://github.com/puppeteer/puppeteer/tree/main/examples"}),"examples"),"."),(0,n.kt)("h4",a({},{id:"example"}),"Example"),(0,n.kt)("p",null,"The following example searches ",(0,n.kt)("a",a({parentName:"p"},{href:"https://developer.chrome.com/"}),"developer.chrome.com"),' for blog posts with text "automate beyond recorder", click on the first result and print the full title of the blog post.'),(0,n.kt)("pre",null,(0,n.kt)("code",a({parentName:"pre"},{className:"language-ts"}),"import puppeteer from 'puppeteer';\n\n(async () => {\n  const browser = await puppeteer.launch();\n  const page = await browser.newPage();\n\n  await page.goto('https://developer.chrome.com/');\n\n  // Set screen size\n  await page.setViewport({width: 1080, height: 1024});\n\n  // Type into search box\n  await page.type('.search-box__input', 'automate beyond recorder');\n\n  // Wait and click on first result\n  const searchResultSelector = '.search-box__link';\n  await page.waitForSelector(searchResultSelector);\n  await page.click(searchResultSelector);\n\n  // Localte the full title with a unique string\n  const textSelector = await page.waitForSelector(\n    'text/Customize and automate'\n  );\n  const fullTitle = await textSelector.evaluate(el => el.textContent);\n\n  // Print the full title\n  console.log('The title of this blog post is \"%s\".', fullTitle);\n\n  await browser.close();\n})();\n")),(0,n.kt)("h3",a({},{id:"default-runtime-settings"}),"Default runtime settings"),(0,n.kt)("p",null,(0,n.kt)("strong",{parentName:"p"},"1. Uses Headless mode")),(0,n.kt)("p",null,"Puppeteer launches Chromium in\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://developers.google.com/web/updates/2017/04/headless-chrome"}),"headless mode"),".\nTo launch a full version of Chromium, set the\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/api/puppeteer.browserlaunchargumentoptions.headless"}),(0,n.kt)("inlineCode",{parentName:"a"},"headless")),"\noption when launching a browser:"),(0,n.kt)("pre",null,(0,n.kt)("code",a({parentName:"pre"},{className:"language-ts"}),"const browser = await puppeteer.launch({headless: false}); // default is true\n")),(0,n.kt)("p",null,(0,n.kt)("strong",{parentName:"p"},"2. Runs a bundled version of Chromium")),(0,n.kt)("p",null,"By default, Puppeteer downloads and uses a specific version of Chromium so its\nAPI is guaranteed to work out of the box. To use Puppeteer with a different\nversion of Chrome or Chromium, pass in the executable's path when creating a\n",(0,n.kt)("inlineCode",{parentName:"p"},"Browser")," instance:"),(0,n.kt)("pre",null,(0,n.kt)("code",a({parentName:"pre"},{className:"language-ts"}),"const browser = await puppeteer.launch({executablePath: '/path/to/Chrome'});\n")),(0,n.kt)("p",null,"You can also use Puppeteer with Firefox Nightly (experimental support). See\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/api/puppeteer.puppeteernode.launch"}),(0,n.kt)("inlineCode",{parentName:"a"},"Puppeteer.launch"))," for\nmore information."),(0,n.kt)("p",null,"See\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/"}),(0,n.kt)("inlineCode",{parentName:"a"},"this article")),"\nfor a description of the differences between Chromium and Chrome.\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/chromium_browser_vs_google_chrome.md"}),(0,n.kt)("inlineCode",{parentName:"a"},"This article")),"\ndescribes some differences for Linux users."),(0,n.kt)("p",null,(0,n.kt)("strong",{parentName:"p"},"3. Creates a fresh user profile")),(0,n.kt)("p",null,"Puppeteer creates its own browser user profile which it ",(0,n.kt)("strong",{parentName:"p"},"cleans up on every\nrun"),"."),(0,n.kt)("h4",a({},{id:"using-docker"}),"Using Docker"),(0,n.kt)("p",null,"See our ",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/guides/docker"}),"Docker guide"),"."),(0,n.kt)("h4",a({},{id:"using-chrome-extensions"}),"Using Chrome Extensions"),(0,n.kt)("p",null,"See our ",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/guides/chrome-extensions"}),"Chrome extensions guide"),"."),(0,n.kt)("h2",a({},{id:"resources"}),"Resources"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("a",a({parentName:"li"},{href:"https://pptr.dev/api"}),"API Documentation")),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("a",a({parentName:"li"},{href:"https://pptr.dev/category/guides"}),"Guides")),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("a",a({parentName:"li"},{href:"https://github.com/puppeteer/puppeteer/tree/main/examples"}),"Examples")),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("a",a({parentName:"li"},{href:"https://github.com/transitive-bullshit/awesome-puppeteer"}),"Community list of Puppeteer resources"))),(0,n.kt)("h2",a({},{id:"contributing"}),"Contributing"),(0,n.kt)("p",null,"Check out our ",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/contributing"}),"contributing guide")," to get an\noverview of Puppeteer development."),(0,n.kt)("h2",a({},{id:"faq"}),"FAQ"),(0,n.kt)("p",null,"Our ",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/faq"}),"FAQ")," has migrated to\n",(0,n.kt)("a",a({parentName:"p"},{href:"https://pptr.dev/faq"}),"our site"),"."))}h.isMDXComponent=!0}}]);