├── README.md
├── LICENSE
└── docs
    └── api.md


/README.md:
--------------------------------------------------------------------------------
  1 | # Puppeteer [![Linux Build Status](https://img.shields.io/travis/GoogleChrome/puppeteer/master.svg)](https://travis-ci.org/GoogleChrome/puppeteer) [![Windows Build Status](https://img.shields.io/appveyor/ci/aslushnikov/puppeteer/master.svg?logo=appveyor)](https://ci.appveyor.com/project/aslushnikov/puppeteer/branch/master) [![NPM puppeteer package](https://img.shields.io/npm/v/puppeteer.svg)](https://npmjs.org/package/puppeteer)
  2 | 
  3 | <img src="https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png" height="200" align="right">
  4 | 
  5 | > 此项目同步自 [GoogleChrome](https://github.com/GoogleChrome) / [puppeteer](https://github.com/GoogleChrome/puppeteer) 项目中的  docs. 
  6 | 
  7 | ###### [API](#api-文档) | [FAQ](#faq) | [Contributing](#贡献-puppeteer)
  8 | 
  9 | > Puppeteer 是一个 Node 库，它提供了一系列高级 API 来通过 [DevTools 协议](https://chromedevtools.github.io/devtools-protocol/) 控制 [headless](https://developers.google.com/web/updates/2017/04/headless-chrome) Chrome 或 Chromium。 它也可以配置为使用完整的（non-headless）Chrome 或 Chromium。
 10 | 
 11 | 
 12 | ###### Puppeteer 能做什么?
 13 | 
 14 | 可以在浏览器中手动完成的大部分事情都可以使用 Puppeteer 完成！ 你可以通过这里的几个例子来起步：
 15 | 
 16 | * 生成页面的截图和PDF。
 17 | * 抓取 SPA 并生成预渲染的内容（即“SSR”）。
 18 | * 从网站抓取内容。
 19 | * 自动表单提交，UI测试，键盘输入等。
 20 | * 创建一个最新的自动化测试环境。 使用最新的 JavaScript 和浏览器功能，直接在最新版本的 Chrome 中运行测试。
 21 | * 捕获你网站的 [timeline trace](https://developers.google.com/web/tools/chrome-devtools/evaluate-performance/reference)，来帮助诊断性能问题。
 22 | 
 23 | 在线尝试: https://try-puppeteer.appspot.com/
 24 | 
 25 | ## 起步
 26 | 
 27 | ### 安装
 28 | 
 29 | > **注意**：Puppeteer 至少需要 Node v6.4.0，而下面的例子中使用的 async/await，只有 Node v7.6.0 或更高版本支持
 30 | 
 31 | 要在你的项目中使用 Puppeteer, 运行:
 32 | 
 33 | ```
 34 | yarn add puppeteer
 35 | # 或 "npm i puppeteer"
 36 | ```
 37 | 
 38 | > **注意**：当你安装 Puppeteer，它会下载最新版本的 Chromium  (~71Mb Mac, ~90Mb Linux, ~110Mb Win) 来保证与 API 协同工作。要跳过下载，参考 [Environment variables](docs/api.md#environment-variables)。
 39 | 
 40 | ### 使用
 41 | 
 42 | Puppeteer 对于使用过其他浏览器测试框架的人来说会很熟悉。 你创建一个 `Browser` 实例，打开页面，然后使用 [Puppeteer 的 API](docs/api.md#) 来操作它们。
 43 | 
 44 | **示例** - 导航到 https://example.com 然后保存屏幕截图为 *example.png*:
 45 | 
 46 | ```js
 47 | const puppeteer = require('puppeteer');
 48 | 
 49 | (async () => {
 50 |   const browser = await puppeteer.launch();
 51 |   const page = await browser.newPage();
 52 |   await page.goto('https://example.com');
 53 |   await page.screenshot({path: 'example.png'});
 54 | 
 55 |   await browser.close();
 56 | })();
 57 | ```
 58 | 
 59 | Puppeteer 设定一个初始页面大小为 800px x 600px, 这决定了截图的大小. 页面大小可以用 [`Page.setViewport()`](docs/api.md#pagesetviewportviewport) 来自定义。
 60 | 
 61 | **示例** - 创建一个 PDF.
 62 | 
 63 | ```js
 64 | const puppeteer = require('puppeteer');
 65 | 
 66 | (async () => {
 67 |   const browser = await puppeteer.launch();
 68 |   const page = await browser.newPage();
 69 |   await page.goto('https://news.ycombinator.com', {waitUntil: 'networkidle2'});
 70 |   await page.pdf({path: 'hn.pdf', format: 'A4'});
 71 | 
 72 |   await browser.close();
 73 | })();
 74 | ```
 75 | 
 76 | 参考 [`Page.pdf()`](docs/api.md#pagepdfoptions) 来获取关于 pdf 的更多内容。
 77 | 
 78 | **示例** - 评估页面上下文中的脚本
 79 | 
 80 | ```js
 81 | const puppeteer = require('puppeteer');
 82 | 
 83 | (async () => {
 84 |   const browser = await puppeteer.launch();
 85 |   const page = await browser.newPage();
 86 |   await page.goto('https://example.com');
 87 | 
 88 |   // Get the "viewport" of the page, as reported by the page.
 89 |   const dimensions = await page.evaluate(() => {
 90 |     return {
 91 |       width: document.documentElement.clientWidth,
 92 |       height: document.documentElement.clientHeight,
 93 |       deviceScaleFactor: window.devicePixelRatio
 94 |     };
 95 |   });
 96 | 
 97 |   console.log('Dimensions:', dimensions);
 98 | 
 99 |   await browser.close();
100 | })();
101 | ```
102 | 
103 | 请参阅 [`Page.evaluate()`](docs/api.md#pageevaluatepagefunction-args) 以获取更多关于 `evaluate` 和相关方法的信息，如`evaluateOnNewDocument` 和 `exposeFunction`。
104 | 
105 | ## 默认运行时设置
106 | 
107 | **1. 使用 Headless 模式**
108 | 
109 | Puppeteer 在 [headless 模式](https://developers.google.com/web/updates/2017/04/headless-chrome) 中运行 Chromium。要运行完整版本的 Chromium, 需在浏览器加载时设置 ['headless' 参数](docs/api.md#puppeteerlaunchoptions):
110 | 
111 | ```js
112 | const browser = await puppeteer.launch({headless: false}); // 默认是 true
113 | ```
114 | 
115 | **2. 运行 Chromium 的捆绑版本**
116 | 
117 | 默认情况下，Puppeteer 下载并使用特定版本的 Chromium，以便使它的 API 保证能开箱即用。 要让 Puppeteer 使用不同版本的 Chrome 或 Chromium，则当创建一个 `Browser` 实例时传入可执行文件的路径：
118 | 
119 | ```js
120 | const browser = await puppeteer.launch({executablePath: '/path/to/Chrome'});
121 | ```
122 | 
123 | 参考 [`Puppeteer.launch()`](docs/api.md#puppeteerlaunchoptions) 获取更多信息。
124 | 
125 | 参考 [`本文`](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) 来了解 Chromium 和 Chrome 之间的区别。 [`本文`](https://chromium.googlesource.com/chromium/src/+/lkcr/docs/chromium_browser_vs_google_chrome.md) 将介绍对于 Linux 用户的一些差异.
126 | 
127 | **3. 创建一个新的用户配置文件**
128 | 
129 | Puppeteer 创建它自己的 Chromium 用户配置文件，并在**每次运行时清理它**。
130 | 
131 | ## API 文档
132 | 
133 | 浏览 [API 文档](docs/api.md) 和 [示例](https://github.com/GoogleChrome/puppeteer/tree/master/examples/) 来学习更多内容。
134 | 
135 | ## 调试提示
136 | 
137 | 1. 关闭 headless 模式 - 有时查看浏览器显示的内容是非常有用的，而不是在 headless 模式下启动。使用 `headless:false` 启动完整版本的浏览器：
138 | 
139 |     ```js
140 |     const browser = await puppeteer.launch({headless: false});
141 |     ```
142 | 
143 | 2. 慢下来 - `slowMo` 参数可是使 Puppeteer 操作速度减少指定的毫秒数。 这是另一种帮助查看发生了什么的方法。
144 | 
145 |     ```js
146 |     const browser = await puppeteer.launch({
147 |       headless: false,
148 |       slowMo: 250 // 放慢了 250ms
149 |     });
150 |     ```
151 | 
152 | 3. 捕获控制台输出 - 您可以侦听 `console` 事件。在 `page.evaluate()` 中调试代码时，这也很方便：
153 | 
154 |     ```js
155 |     page.on('console', msg => console.log('PAGE LOG:', ...msg.args));
156 | 
157 |     await page.evaluate(() => console.log(`url is ${location.href}`));
158 |     ```
159 | 
160 | 4. 启用详细日志记录 - 所有公共 API 调用和内部协议流将通过 `puppeteer` 命名空间下的 [`debug`](https://github.com/visionmedia/debug) 模块进行记录。
161 | 
162 |    ```sh
163 |    # 基本的详细记录
164 |    env DEBUG="puppeteer:*" node script.js
165 | 
166 |    # DEBUG 输出可以通过命名空间来启用/禁用
167 |    env DEBUG="puppeteer:*,-puppeteer:protocol" node script.js # 所有协议消息
168 |    env DEBUG="puppeteer:session" node script.js # 协议会话消息（协议消息到目标）
169 |    env DEBUG="puppeteer:mouse,puppeteer:keyboard" node script.js # 只有鼠标和键盘的 API 调用
170 | 
171 |    # 协议流可能相当嘈杂。 这个例子过滤掉所有网络域的消息
172 |    env DEBUG="puppeteer:*" env DEBUG_COLORS=true node script.js 2>&1 | grep -v '"Network'
173 |    ```
174 | 
175 | ## 贡献 Puppeteer
176 | 
177 | 查看 [贡献指南](https://github.com/GoogleChrome/puppeteer/blob/master/CONTRIBUTING.md) 来获得有关 Puppeteer 开发的概述。
178 | 
179 | # FAQ
180 | 
181 | #### Q: Puppeteer 使用哪个 Chromium 版本？
182 | 
183 | 在 [package.json](https://github.com/GoogleChrome/puppeteer/blob/master/package.json) 中查看 `chromium_revision`.
184 | 
185 | Puppeteer 捆绑 Chromium 来确保它使用的最新功能可用。 随着 DevTools 协议和浏览器的不断改进，Puppeteer 将被更新为依赖于更新版本的 Chromium。
186 | 
187 | #### Q: Puppeteer，Selenium / WebDriver 和 PhantomJS 有什么区别？
188 | 
189 | Selenium / WebDriver是一个完善的跨浏览器API，可用于测试跨浏览器支持。
190 | 
191 | Puppeteer 仅适用于 Chromium 或 Chrome。 但是，许多团队只使用一个浏览器（例如PhantomJS）进行单元测试。 在非测试用例中，Puppeteer 提供了一个功能强大但简单的API，因为它只针对一个浏览器，使您能够快速开发自动化脚本。
192 | 
193 | Puppeteer 捆绑了最新版本的 Chromium。
194 | 
195 | #### Q: 谁维护 Puppeteer?
196 | 
197 | Chrome DevTools 团队负责维护该库，然而我们非常乐意在项目中提供帮助和专业知识！
198 | 参考 [Contributing](https://github.com/GoogleChrome/puppeteer/blob/master/CONTRIBUTING.md).
199 | 
200 | #### Q: Chrome 团队为什么要打造 Puppeteer?
201 | 
202 | 该项目的目标很简单：
203 | 
204 | - 提供一个精简的，规范的库，强调 [DevTools 协议](https://chromedevtools.github.io/devtools-protocol/) 的功能。
205 | - 为类似的测试库的实现提供参考。 最终，这些其他框架可以采用 Puppeteer 作为其基础层。
206 | - 越来越多的采用 headless/automated 浏览器测试。
207 | - 帮助养成新的 DevTools 协议功能...并捕捉错误！
208 | - 详细了解自动浏览器测试的难点，并帮助填补这些空白。
209 | 
210 | #### Q: Puppeteer 与其他 headless  Chrome 项目相比如何？
211 | 
212 | 过去几个月，[为自动化 headless Chrome 带来了一些新的库](https://medium.com/@kensoh/chromeless-chrominator-chromy-navalia-lambdium-ghostjs-autogcd-ef34bcd26907)。 作为开发 DevTools 协议的团队，我们很高兴看到和支持这个蓬勃发展的生态系统。
213 | 
214 | 我们已经联系了一些这样的项目，看看是否有合作的机会，我们很乐意尽我们所能帮助。
215 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
  1 |                     GNU GENERAL PUBLIC LICENSE
  2 |                        Version 2, June 1991
  3 | 
  4 |  Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
  5 |  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  6 |  Everyone is permitted to copy and distribute verbatim copies
  7 |  of this license document, but changing it is not allowed.
  8 | 
  9 |                             Preamble
 10 | 
 11 |   The licenses for most software are designed to take away your
 12 | freedom to share and change it.  By contrast, the GNU General Public
 13 | License is intended to guarantee your freedom to share and change free
 14 | software--to make sure the software is free for all its users.  This
 15 | General Public License applies to most of the Free Software
 16 | Foundation's software and to any other program whose authors commit to
 17 | using it.  (Some other Free Software Foundation software is covered by
 18 | the GNU Lesser General Public License instead.)  You can apply it to
 19 | your programs, too.
 20 | 
 21 |   When we speak of free software, we are referring to freedom, not
 22 | price.  Our General Public Licenses are designed to make sure that you
 23 | have the freedom to distribute copies of free software (and charge for
 24 | this service if you wish), that you receive source code or can get it
 25 | if you want it, that you can change the software or use pieces of it
 26 | in new free programs; and that you know you can do these things.
 27 | 
 28 |   To protect your rights, we need to make restrictions that forbid
 29 | anyone to deny you these rights or to ask you to surrender the rights.
 30 | These restrictions translate to certain responsibilities for you if you
 31 | distribute copies of the software, or if you modify it.
 32 | 
 33 |   For example, if you distribute copies of such a program, whether
 34 | gratis or for a fee, you must give the recipients all the rights that
 35 | you have.  You must make sure that they, too, receive or can get the
 36 | source code.  And you must show them these terms so they know their
 37 | rights.
 38 | 
 39 |   We protect your rights with two steps: (1) copyright the software, and
 40 | (2) offer you this license which gives you legal permission to copy,
 41 | distribute and/or modify the software.
 42 | 
 43 |   Also, for each author's protection and ours, we want to make certain
 44 | that everyone understands that there is no warranty for this free
 45 | software.  If the software is modified by someone else and passed on, we
 46 | want its recipients to know that what they have is not the original, so
 47 | that any problems introduced by others will not reflect on the original
 48 | authors' reputations.
 49 | 
 50 |   Finally, any free program is threatened constantly by software
 51 | patents.  We wish to avoid the danger that redistributors of a free
 52 | program will individually obtain patent licenses, in effect making the
 53 | program proprietary.  To prevent this, we have made it clear that any
 54 | patent must be licensed for everyone's free use or not licensed at all.
 55 | 
 56 |   The precise terms and conditions for copying, distribution and
 57 | modification follow.
 58 | 
 59 |                     GNU GENERAL PUBLIC LICENSE
 60 |    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
 61 | 
 62 |   0. This License applies to any program or other work which contains
 63 | a notice placed by the copyright holder saying it may be distributed
 64 | under the terms of this General Public License.  The "Program", below,
 65 | refers to any such program or work, and a "work based on the Program"
 66 | means either the Program or any derivative work under copyright law:
 67 | that is to say, a work containing the Program or a portion of it,
 68 | either verbatim or with modifications and/or translated into another
 69 | language.  (Hereinafter, translation is included without limitation in
 70 | the term "modification".)  Each licensee is addressed as "you".
 71 | 
 72 | Activities other than copying, distribution and modification are not
 73 | covered by this License; they are outside its scope.  The act of
 74 | running the Program is not restricted, and the output from the Program
 75 | is covered only if its contents constitute a work based on the
 76 | Program (independent of having been made by running the Program).
 77 | Whether that is true depends on what the Program does.
 78 | 
 79 |   1. You may copy and distribute verbatim copies of the Program's
 80 | source code as you receive it, in any medium, provided that you
 81 | conspicuously and appropriately publish on each copy an appropriate
 82 | copyright notice and disclaimer of warranty; keep intact all the
 83 | notices that refer to this License and to the absence of any warranty;
 84 | and give any other recipients of the Program a copy of this License
 85 | along with the Program.
 86 | 
 87 | You may charge a fee for the physical act of transferring a copy, and
 88 | you may at your option offer warranty protection in exchange for a fee.
 89 | 
 90 |   2. You may modify your copy or copies of the Program or any portion
 91 | of it, thus forming a work based on the Program, and copy and
 92 | distribute such modifications or work under the terms of Section 1
 93 | above, provided that you also meet all of these conditions:
 94 | 
 95 |     a) You must cause the modified files to carry prominent notices
 96 |     stating that you changed the files and the date of any change.
 97 | 
 98 |     b) You must cause any work that you distribute or publish, that in
 99 |     whole or in part contains or is derived from the Program or any
100 |     part thereof, to be licensed as a whole at no charge to all third
101 |     parties under the terms of this License.
102 | 
103 |     c) If the modified program normally reads commands interactively
104 |     when run, you must cause it, when started running for such
105 |     interactive use in the most ordinary way, to print or display an
106 |     announcement including an appropriate copyright notice and a
107 |     notice that there is no warranty (or else, saying that you provide
108 |     a warranty) and that users may redistribute the program under
109 |     these conditions, and telling the user how to view a copy of this
110 |     License.  (Exception: if the Program itself is interactive but
111 |     does not normally print such an announcement, your work based on
112 |     the Program is not required to print an announcement.)
113 | 
114 | These requirements apply to the modified work as a whole.  If
115 | identifiable sections of that work are not derived from the Program,
116 | and can be reasonably considered independent and separate works in
117 | themselves, then this License, and its terms, do not apply to those
118 | sections when you distribute them as separate works.  But when you
119 | distribute the same sections as part of a whole which is a work based
120 | on the Program, the distribution of the whole must be on the terms of
121 | this License, whose permissions for other licensees extend to the
122 | entire whole, and thus to each and every part regardless of who wrote it.
123 | 
124 | Thus, it is not the intent of this section to claim rights or contest
125 | your rights to work written entirely by you; rather, the intent is to
126 | exercise the right to control the distribution of derivative or
127 | collective works based on the Program.
128 | 
129 | In addition, mere aggregation of another work not based on the Program
130 | with the Program (or with a work based on the Program) on a volume of
131 | a storage or distribution medium does not bring the other work under
132 | the scope of this License.
133 | 
134 |   3. You may copy and distribute the Program (or a work based on it,
135 | under Section 2) in object code or executable form under the terms of
136 | Sections 1 and 2 above provided that you also do one of the following:
137 | 
138 |     a) Accompany it with the complete corresponding machine-readable
139 |     source code, which must be distributed under the terms of Sections
140 |     1 and 2 above on a medium customarily used for software interchange; or,
141 | 
142 |     b) Accompany it with a written offer, valid for at least three
143 |     years, to give any third party, for a charge no more than your
144 |     cost of physically performing source distribution, a complete
145 |     machine-readable copy of the corresponding source code, to be
146 |     distributed under the terms of Sections 1 and 2 above on a medium
147 |     customarily used for software interchange; or,
148 | 
149 |     c) Accompany it with the information you received as to the offer
150 |     to distribute corresponding source code.  (This alternative is
151 |     allowed only for noncommercial distribution and only if you
152 |     received the program in object code or executable form with such
153 |     an offer, in accord with Subsection b above.)
154 | 
155 | The source code for a work means the preferred form of the work for
156 | making modifications to it.  For an executable work, complete source
157 | code means all the source code for all modules it contains, plus any
158 | associated interface definition files, plus the scripts used to
159 | control compilation and installation of the executable.  However, as a
160 | special exception, the source code distributed need not include
161 | anything that is normally distributed (in either source or binary
162 | form) with the major components (compiler, kernel, and so on) of the
163 | operating system on which the executable runs, unless that component
164 | itself accompanies the executable.
165 | 
166 | If distribution of executable or object code is made by offering
167 | access to copy from a designated place, then offering equivalent
168 | access to copy the source code from the same place counts as
169 | distribution of the source code, even though third parties are not
170 | compelled to copy the source along with the object code.
171 | 
172 |   4. You may not copy, modify, sublicense, or distribute the Program
173 | except as expressly provided under this License.  Any attempt
174 | otherwise to copy, modify, sublicense or distribute the Program is
175 | void, and will automatically terminate your rights under this License.
176 | However, parties who have received copies, or rights, from you under
177 | this License will not have their licenses terminated so long as such
178 | parties remain in full compliance.
179 | 
180 |   5. You are not required to accept this License, since you have not
181 | signed it.  However, nothing else grants you permission to modify or
182 | distribute the Program or its derivative works.  These actions are
183 | prohibited by law if you do not accept this License.  Therefore, by
184 | modifying or distributing the Program (or any work based on the
185 | Program), you indicate your acceptance of this License to do so, and
186 | all its terms and conditions for copying, distributing or modifying
187 | the Program or works based on it.
188 | 
189 |   6. Each time you redistribute the Program (or any work based on the
190 | Program), the recipient automatically receives a license from the
191 | original licensor to copy, distribute or modify the Program subject to
192 | these terms and conditions.  You may not impose any further
193 | restrictions on the recipients' exercise of the rights granted herein.
194 | You are not responsible for enforcing compliance by third parties to
195 | this License.
196 | 
197 |   7. If, as a consequence of a court judgment or allegation of patent
198 | infringement or for any other reason (not limited to patent issues),
199 | conditions are imposed on you (whether by court order, agreement or
200 | otherwise) that contradict the conditions of this License, they do not
201 | excuse you from the conditions of this License.  If you cannot
202 | distribute so as to satisfy simultaneously your obligations under this
203 | License and any other pertinent obligations, then as a consequence you
204 | may not distribute the Program at all.  For example, if a patent
205 | license would not permit royalty-free redistribution of the Program by
206 | all those who receive copies directly or indirectly through you, then
207 | the only way you could satisfy both it and this License would be to
208 | refrain entirely from distribution of the Program.
209 | 
210 | If any portion of this section is held invalid or unenforceable under
211 | any particular circumstance, the balance of the section is intended to
212 | apply and the section as a whole is intended to apply in other
213 | circumstances.
214 | 
215 | It is not the purpose of this section to induce you to infringe any
216 | patents or other property right claims or to contest validity of any
217 | such claims; this section has the sole purpose of protecting the
218 | integrity of the free software distribution system, which is
219 | implemented by public license practices.  Many people have made
220 | generous contributions to the wide range of software distributed
221 | through that system in reliance on consistent application of that
222 | system; it is up to the author/donor to decide if he or she is willing
223 | to distribute software through any other system and a licensee cannot
224 | impose that choice.
225 | 
226 | This section is intended to make thoroughly clear what is believed to
227 | be a consequence of the rest of this License.
228 | 
229 |   8. If the distribution and/or use of the Program is restricted in
230 | certain countries either by patents or by copyrighted interfaces, the
231 | original copyright holder who places the Program under this License
232 | may add an explicit geographical distribution limitation excluding
233 | those countries, so that distribution is permitted only in or among
234 | countries not thus excluded.  In such case, this License incorporates
235 | the limitation as if written in the body of this License.
236 | 
237 |   9. The Free Software Foundation may publish revised and/or new versions
238 | of the General Public License from time to time.  Such new versions will
239 | be similar in spirit to the present version, but may differ in detail to
240 | address new problems or concerns.
241 | 
242 | Each version is given a distinguishing version number.  If the Program
243 | specifies a version number of this License which applies to it and "any
244 | later version", you have the option of following the terms and conditions
245 | either of that version or of any later version published by the Free
246 | Software Foundation.  If the Program does not specify a version number of
247 | this License, you may choose any version ever published by the Free Software
248 | Foundation.
249 | 
250 |   10. If you wish to incorporate parts of the Program into other free
251 | programs whose distribution conditions are different, write to the author
252 | to ask for permission.  For software which is copyrighted by the Free
253 | Software Foundation, write to the Free Software Foundation; we sometimes
254 | make exceptions for this.  Our decision will be guided by the two goals
255 | of preserving the free status of all derivatives of our free software and
256 | of promoting the sharing and reuse of software generally.
257 | 
258 |                             NO WARRANTY
259 | 
260 |   11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
261 | FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
262 | OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
263 | PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
264 | OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
265 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
266 | TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
267 | PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
268 | REPAIR OR CORRECTION.
269 | 
270 |   12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
271 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
272 | REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
273 | INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
274 | OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
275 | TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
276 | YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
277 | PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
278 | POSSIBILITY OF SUCH DAMAGES.
279 | 
280 |                      END OF TERMS AND CONDITIONS
281 | 
282 |             How to Apply These Terms to Your New Programs
283 | 
284 |   If you develop a new program, and you want it to be of the greatest
285 | possible use to the public, the best way to achieve this is to make it
286 | free software which everyone can redistribute and change under these terms.
287 | 
288 |   To do so, attach the following notices to the program.  It is safest
289 | to attach them to the start of each source file to most effectively
290 | convey the exclusion of warranty; and each file should have at least
291 | the "copyright" line and a pointer to where the full notice is found.
292 | 
293 |     <one line to give the program's name and a brief idea of what it does.>
294 |     Copyright (C) <year>  <name of author>
295 | 
296 |     This program is free software; you can redistribute it and/or modify
297 |     it under the terms of the GNU General Public License as published by
298 |     the Free Software Foundation; either version 2 of the License, or
299 |     (at your option) any later version.
300 | 
301 |     This program is distributed in the hope that it will be useful,
302 |     but WITHOUT ANY WARRANTY; without even the implied warranty of
303 |     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
304 |     GNU General Public License for more details.
305 | 
306 |     You should have received a copy of the GNU General Public License along
307 |     with this program; if not, write to the Free Software Foundation, Inc.,
308 |     51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
309 | 
310 | Also add information on how to contact you by electronic and paper mail.
311 | 
312 | If the program is interactive, make it output a short notice like this
313 | when it starts in an interactive mode:
314 | 
315 |     Gnomovision version 69, Copyright (C) year name of author
316 |     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
317 |     This is free software, and you are welcome to redistribute it
318 |     under certain conditions; type `show c' for details.
319 | 
320 | The hypothetical commands `show w' and `show c' should show the appropriate
321 | parts of the General Public License.  Of course, the commands you use may
322 | be called something other than `show w' and `show c'; they could even be
323 | mouse-clicks or menu items--whatever suits your program.
324 | 
325 | You should also get your employer (if you work as a programmer) or your
326 | school, if any, to sign a "copyright disclaimer" for the program, if
327 | necessary.  Here is a sample; alter the names:
328 | 
329 |   Yoyodyne, Inc., hereby disclaims all copyright interest in the program
330 |   `Gnomovision' (which makes passes at compilers) written by James Hacker.
331 | 
332 |   <signature of Ty Coon>, 1 April 1989
333 |   Ty Coon, President of Vice
334 | 
335 | This General Public License does not permit incorporating your program into
336 | proprietary programs.  If your program is a subroutine library, you may
337 | consider it more useful to permit linking proprietary applications with the
338 | library.  If this is what you want to do, use the GNU Lesser General
339 | Public License instead of this License.
340 | 


--------------------------------------------------------------------------------
/docs/api.md:
--------------------------------------------------------------------------------
   1 | # Puppeteer API v<!-- GEN:version -->1.0.0-rc<!-- GEN:stop-->
   2 | 
   3 | ##### 内容目录
   4 | 
   5 | <!-- toc -->
   6 | 
   7 | - [概览](#overview)
   8 | - [环境变量](#environment-variables)
   9 | - [class: Puppeteer](#class-puppeteer)
  10 |   * [puppeteer.connect(options)](#puppeteerconnectoptions)
  11 |   * [puppeteer.defaultArgs()](#puppeteerdefaultargs)
  12 |   * [puppeteer.executablePath()](#puppeteerexecutablepath)
  13 |   * [puppeteer.launch([options])](#puppeteerlaunchoptions)
  14 | - [class: Browser](#class-browser)
  15 |   * [event: 'disconnected'](#event-disconnected)
  16 |   * [event: 'targetchanged'](#event-targetchanged)
  17 |   * [event: 'targetcreated'](#event-targetcreated)
  18 |   * [event: 'targetdestroyed'](#event-targetdestroyed)
  19 |   * [browser.close()](#browserclose)
  20 |   * [browser.disconnect()](#browserdisconnect)
  21 |   * [browser.newPage()](#browsernewpage)
  22 |   * [browser.pages()](#browserpages)
  23 |   * [browser.process()](#browserprocess)
  24 |   * [browser.targets()](#browsertargets)
  25 |   * [browser.userAgent()](#browseruseragent)
  26 |   * [browser.version()](#browserversion)
  27 |   * [browser.wsEndpoint()](#browserwsendpoint)
  28 | - [class: Page](#class-page)
  29 |   * [event: 'console'](#event-console)
  30 |   * [event: 'dialog'](#event-dialog)
  31 |   * [event: 'error'](#event-error)
  32 |   * [event: 'frameattached'](#event-frameattached)
  33 |   * [event: 'framedetached'](#event-framedetached)
  34 |   * [event: 'framenavigated'](#event-framenavigated)
  35 |   * [event: 'load'](#event-load)
  36 |   * [event: 'metrics'](#event-metrics)
  37 |   * [event: 'pageerror'](#event-pageerror)
  38 |   * [event: 'request'](#event-request)
  39 |   * [event: 'requestfailed'](#event-requestfailed)
  40 |   * [event: 'requestfinished'](#event-requestfinished)
  41 |   * [event: 'response'](#event-response)
  42 |   * [page.$(selector)](#pageselector)
  43 |   * [page.$$(selector)](#pageselector)
  44 |   * [page.$$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args)
  45 |   * [page.$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args)
  46 |   * [page.$x(expression)](#pagexexpression)
  47 |   * [page.addScriptTag(options)](#pageaddscripttagoptions)
  48 |   * [page.addStyleTag(options)](#pageaddstyletagoptions)
  49 |   * [page.authenticate(credentials)](#pageauthenticatecredentials)
  50 |   * [page.bringToFront()](#pagebringtofront)
  51 |   * [page.click(selector[, options])](#pageclickselector-options)
  52 |   * [page.close()](#pageclose)
  53 |   * [page.content()](#pagecontent)
  54 |   * [page.cookies(...urls)](#pagecookiesurls)
  55 |   * [page.coverage](#pagecoverage)
  56 |   * [page.deleteCookie(...cookies)](#pagedeletecookiecookies)
  57 |   * [page.emulate(options)](#pageemulateoptions)
  58 |   * [page.emulateMedia(mediaType)](#pageemulatemediamediatype)
  59 |   * [page.evaluate(pageFunction, ...args)](#pageevaluatepagefunction-args)
  60 |   * [page.evaluateHandle(pageFunction, ...args)](#pageevaluatehandlepagefunction-args)
  61 |   * [page.evaluateOnNewDocument(pageFunction, ...args)](#pageevaluateonnewdocumentpagefunction-args)
  62 |   * [page.exposeFunction(name, puppeteerFunction)](#pageexposefunctionname-puppeteerfunction)
  63 |   * [page.focus(selector)](#pagefocusselector)
  64 |   * [page.frames()](#pageframes)
  65 |   * [page.goBack(options)](#pagegobackoptions)
  66 |   * [page.goForward(options)](#pagegoforwardoptions)
  67 |   * [page.goto(url, options)](#pagegotourl-options)
  68 |   * [page.hover(selector)](#pagehoverselector)
  69 |   * [page.keyboard](#pagekeyboard)
  70 |   * [page.mainFrame()](#pagemainframe)
  71 |   * [page.metrics()](#pagemetrics)
  72 |   * [page.mouse](#pagemouse)
  73 |   * [page.pdf(options)](#pagepdfoptions)
  74 |   * [page.queryObjects(prototypeHandle)](#pagequeryobjectsprototypehandle)
  75 |   * [page.reload(options)](#pagereloadoptions)
  76 |   * [page.screenshot([options])](#pagescreenshotoptions)
  77 |   * [page.select(selector, ...values)](#pageselectselector-values)
  78 |   * [page.setContent(html)](#pagesetcontenthtml)
  79 |   * [page.setCookie(...cookies)](#pagesetcookiecookies)
  80 |   * [page.setExtraHTTPHeaders(headers)](#pagesetextrahttpheadersheaders)
  81 |   * [page.setJavaScriptEnabled(enabled)](#pagesetjavascriptenabledenabled)
  82 |   * [page.setOfflineMode(enabled)](#pagesetofflinemodeenabled)
  83 |   * [page.setRequestInterception(value)](#pagesetrequestinterceptionvalue)
  84 |   * [page.setUserAgent(userAgent)](#pagesetuseragentuseragent)
  85 |   * [page.setViewport(viewport)](#pagesetviewportviewport)
  86 |   * [page.tap(selector)](#pagetapselector)
  87 |   * [page.title()](#pagetitle)
  88 |   * [page.touchscreen](#pagetouchscreen)
  89 |   * [page.tracing](#pagetracing)
  90 |   * [page.type(selector, text[, options])](#pagetypeselector-text-options)
  91 |   * [page.url()](#pageurl)
  92 |   * [page.viewport()](#pageviewport)
  93 |   * [page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#pagewaitforselectororfunctionortimeout-options-args)
  94 |   * [page.waitForFunction(pageFunction[, options[, ...args]])](#pagewaitforfunctionpagefunction-options-args)
  95 |   * [page.waitForNavigation(options)](#pagewaitfornavigationoptions)
  96 |   * [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options)
  97 | - [class: Keyboard](#class-keyboard)
  98 |   * [keyboard.down(key[, options])](#keyboarddownkey-options)
  99 |   * [keyboard.press(key[, options])](#keyboardpresskey-options)
 100 |   * [keyboard.sendCharacter(char)](#keyboardsendcharacterchar)
 101 |   * [keyboard.type(text, options)](#keyboardtypetext-options)
 102 |   * [keyboard.up(key)](#keyboardupkey)
 103 | - [class: Mouse](#class-mouse)
 104 |   * [mouse.click(x, y, [options])](#mouseclickx-y-options)
 105 |   * [mouse.down([options])](#mousedownoptions)
 106 |   * [mouse.move(x, y, [options])](#mousemovex-y-options)
 107 |   * [mouse.up([options])](#mouseupoptions)
 108 | - [class: Touchscreen](#class-touchscreen)
 109 |   * [touchscreen.tap(x, y)](#touchscreentapx-y)
 110 | - [class: Tracing](#class-tracing)
 111 |   * [tracing.start(options)](#tracingstartoptions)
 112 |   * [tracing.stop()](#tracingstop)
 113 | - [class: Dialog](#class-dialog)
 114 |   * [dialog.accept([promptText])](#dialogacceptprompttext)
 115 |   * [dialog.defaultValue()](#dialogdefaultvalue)
 116 |   * [dialog.dismiss()](#dialogdismiss)
 117 |   * [dialog.message()](#dialogmessage)
 118 |   * [dialog.type()](#dialogtype)
 119 | - [class: ConsoleMessage](#class-consolemessage)
 120 |   * [consoleMessage.args()](#consolemessageargs)
 121 |   * [consoleMessage.text()](#consolemessagetext)
 122 |   * [consoleMessage.type()](#consolemessagetype)
 123 | - [class: Frame](#class-frame)
 124 |   * [frame.$(selector)](#frameselector)
 125 |   * [frame.$$(selector)](#frameselector)
 126 |   * [frame.$$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args)
 127 |   * [frame.$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args)
 128 |   * [frame.$x(expression)](#framexexpression)
 129 |   * [frame.addScriptTag(options)](#frameaddscripttagoptions)
 130 |   * [frame.addStyleTag(options)](#frameaddstyletagoptions)
 131 |   * [frame.childFrames()](#framechildframes)
 132 |   * [frame.content()](#framecontent)
 133 |   * [frame.evaluate(pageFunction, ...args)](#frameevaluatepagefunction-args)
 134 |   * [frame.executionContext()](#frameexecutioncontext)
 135 |   * [frame.isDetached()](#frameisdetached)
 136 |   * [frame.name()](#framename)
 137 |   * [frame.parentFrame()](#frameparentframe)
 138 |   * [frame.select(selector, ...values)](#frameselectselector-values)
 139 |   * [frame.setContent(html)](#framesetcontenthtml)
 140 |   * [frame.title()](#frametitle)
 141 |   * [frame.url()](#frameurl)
 142 |   * [frame.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#framewaitforselectororfunctionortimeout-options-args)
 143 |   * [frame.waitForFunction(pageFunction[, options[, ...args]])](#framewaitforfunctionpagefunction-options-args)
 144 |   * [frame.waitForSelector(selector[, options])](#framewaitforselectorselector-options)
 145 | - [class: ExecutionContext](#class-executioncontext)
 146 |   * [executionContext.evaluate(pageFunction, ...args)](#executioncontextevaluatepagefunction-args)
 147 |   * [executionContext.evaluateHandle(pageFunction, ...args)](#executioncontextevaluatehandlepagefunction-args)
 148 |   * [executionContext.queryObjects(prototypeHandle)](#executioncontextqueryobjectsprototypehandle)
 149 | - [class: JSHandle](#class-jshandle)
 150 |   * [jsHandle.asElement()](#jshandleaselement)
 151 |   * [jsHandle.dispose()](#jshandledispose)
 152 |   * [jsHandle.executionContext()](#jshandleexecutioncontext)
 153 |   * [jsHandle.getProperties()](#jshandlegetproperties)
 154 |   * [jsHandle.getProperty(propertyName)](#jshandlegetpropertypropertyname)
 155 |   * [jsHandle.jsonValue()](#jshandlejsonvalue)
 156 | - [class: ElementHandle](#class-elementhandle)
 157 |   * [elementHandle.$(selector)](#elementhandleselector)
 158 |   * [elementHandle.$$(selector)](#elementhandleselector)
 159 |   * [elementHandle.$x(expression)](#elementhandlexexpression)
 160 |   * [elementHandle.asElement()](#elementhandleaselement)
 161 |   * [elementHandle.boundingBox()](#elementhandleboundingbox)
 162 |   * [elementHandle.click([options])](#elementhandleclickoptions)
 163 |   * [elementHandle.dispose()](#elementhandledispose)
 164 |   * [elementHandle.executionContext()](#elementhandleexecutioncontext)
 165 |   * [elementHandle.focus()](#elementhandlefocus)
 166 |   * [elementHandle.getProperties()](#elementhandlegetproperties)
 167 |   * [elementHandle.getProperty(propertyName)](#elementhandlegetpropertypropertyname)
 168 |   * [elementHandle.hover()](#elementhandlehover)
 169 |   * [elementHandle.jsonValue()](#elementhandlejsonvalue)
 170 |   * [elementHandle.press(key[, options])](#elementhandlepresskey-options)
 171 |   * [elementHandle.screenshot([options])](#elementhandlescreenshotoptions)
 172 |   * [elementHandle.tap()](#elementhandletap)
 173 |   * [elementHandle.toString()](#elementhandletostring)
 174 |   * [elementHandle.type(text[, options])](#elementhandletypetext-options)
 175 |   * [elementHandle.uploadFile(...filePaths)](#elementhandleuploadfilefilepaths)
 176 | - [class: Request](#class-request)
 177 |   * [request.abort([errorCode])](#requestaborterrorcode)
 178 |   * [request.continue([overrides])](#requestcontinueoverrides)
 179 |   * [request.failure()](#requestfailure)
 180 |   * [request.headers()](#requestheaders)
 181 |   * [request.method()](#requestmethod)
 182 |   * [request.postData()](#requestpostdata)
 183 |   * [request.resourceType()](#requestresourcetype)
 184 |   * [request.respond(response)](#requestrespondresponse)
 185 |   * [request.response()](#requestresponse)
 186 |   * [request.url()](#requesturl)
 187 | - [class: Response](#class-response)
 188 |   * [response.buffer()](#responsebuffer)
 189 |   * [response.headers()](#responseheaders)
 190 |   * [response.json()](#responsejson)
 191 |   * [response.ok()](#responseok)
 192 |   * [response.request()](#responserequest)
 193 |   * [response.status()](#responsestatus)
 194 |   * [response.text()](#responsetext)
 195 |   * [response.url()](#responseurl)
 196 | - [class: Target](#class-target)
 197 |   * [target.page()](#targetpage)
 198 |   * [target.type()](#targettype)
 199 |   * [target.url()](#targeturl)
 200 | - [class: Coverage](#class-coverage)
 201 |   * [coverage.startCSSCoverage(options)](#coveragestartcsscoverageoptions)
 202 |   * [coverage.startJSCoverage(options)](#coveragestartjscoverageoptions)
 203 |   * [coverage.stopCSSCoverage()](#coveragestopcsscoverage)
 204 |   * [coverage.stopJSCoverage()](#coveragestopjscoverage)
 205 | 
 206 | <!-- tocstop -->
 207 | 
 208 | ### 概览
 209 | 
 210 | Puppeteer 是一个 Node 库，它提供了一系列高级 API 来使用 DevTools协议 控制 Chromium 或者 Chrome。
 211 | 
 212 | Puppeteer API 是分层并且镜像于浏览器的结构。在下面的图表上，褪色的实体当前没有在Puppeteer 中表现出来。
 213 | 
 214 | ![puppeteer overview](https://user-images.githubusercontent.com/746130/31592143-089f6f9a-b1db-11e7-9a20-16b7fc754fa1.png)
 215 | 
 216 | - [`Puppeteer`](#class-puppeteer) 使用 [devtools 协议](https://chromedevtools.github.io/devtools-protocol/) 与浏览器通信。
 217 | - [`Browser`](#class-browser) 实例拥有多个页面。
 218 | - [`Page`](#class-page) 至少有一个框架: 主框架。 可能还有其他由 [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) 或 [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame) 标签创建的框架。
 219 | - [`Frame`](#class-frame) 至少有一个可执行上下文 - 默认可执行上下文 - 其中框架的 JavaScript 被执行。框架可能有额外的与[扩展](https://developer.chrome.com/extensions)相关联的执行上下文。
 220 | 
 221 | (图表资源: [link](https://docs.google.com/drawings/d/1Q_AM6KYs9kbyLZF-Lpp5mtpAWth73Cq8IKCsWYgi8MM/edit?usp=sharing))
 222 | 
 223 | 
 224 | ### 环境变量
 225 | 
 226 | Puppeteer 会查找某些 [环境变量](https://en.wikipedia.org/wiki/Environment_variable) 来帮助其操作。 这些变量既可以在环境中设置，也可以在 [npm 配置](https://docs.npmjs.com/cli/config) 中设置。
 227 | 
 228 | - `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` - 定义用于下载和运行 Chromium 的 HTTP 代理设置。
 229 | - `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD` - 安装过程中不要下载捆绑的 Chromium。
 230 | - `PUPPETEER_DOWNLOAD_HOST` - 覆盖用于下载 Chromium 的 URL 的主机部分
 231 | 
 232 | ### class: Puppeteer
 233 | 
 234 | Puppeteer module provides a method to launch a Chromium instance.
 235 | The following is a typical example of using a Puppeteer to drive automation:
 236 | ```js
 237 | const puppeteer = require('puppeteer');
 238 | 
 239 | puppeteer.launch().then(async browser => {
 240 |   const page = await browser.newPage();
 241 |   await page.goto('https://www.google.com');
 242 |   // other actions...
 243 |   await browser.close();
 244 | });
 245 | ```
 246 | 
 247 | #### puppeteer.connect(options)
 248 | - `options` <[Object]>
 249 |   - `browserWSEndpoint` <[string]> a [browser websocket endpoint](#browserwsendpoint) to connect to.
 250 |   - `ignoreHTTPSErrors` <[boolean]> Whether to ignore HTTPS errors during navigation. Defaults to `false`.
 251 | - returns: <[Promise]<[Browser]>>
 252 | 
 253 | This methods attaches Puppeteer to an existing Chromium instance.
 254 | 
 255 | #### puppeteer.defaultArgs()
 256 | - returns: <[Array]<[string]>> The default flags that Chromium will be launched with.
 257 | 
 258 | #### puppeteer.executablePath()
 259 | - returns: <[string]> A path where Puppeteer expects to find bundled Chromium. Chromium might not exist there if the download was skipped with [`PUPPETEER_SKIP_CHROMIUM_DOWNLOAD`](#environment-variables).
 260 | 
 261 | #### puppeteer.launch([options])
 262 | - `options` <[Object]>  Set of configurable options to set on the browser. Can have the following fields:
 263 |   - `ignoreHTTPSErrors` <[boolean]> Whether to ignore HTTPS errors during navigation. Defaults to `false`.
 264 |   - `headless` <[boolean]> Whether to run browser in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome). Defaults to `true` unless the `devtools` option is `true`.
 265 |   - `executablePath` <[string]> Path to a Chromium or Chrome executable to run instead of bundled Chromium. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
 266 |   - `slowMo` <[number]> Slows down Puppeteer operations by the specified amount of milliseconds. Useful so that you can see what is going on.
 267 |   - `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. List of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/).
 268 |   - `ignoreDefaultArgs` <[boolean]> Do not use [`puppeteer.defaultArgs()`](#puppeteerdefaultargs). Dangerous option; use with care. Defaults to `false`.
 269 |   - `handleSIGINT` <[boolean]> Close browser process on Ctrl-C. Defaults to `true`.
 270 |   - `handleSIGTERM` <[boolean]> Close browser process on SIGTERM. Defaults to `true`.
 271 |   - `handleSIGHUP` <[boolean]> Close browser process on SIGHUP. Defaults to `true`.
 272 |   - `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
 273 |   - `dumpio` <[boolean]> Whether to pipe browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`.
 274 |   - `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md).
 275 |   - `env` <[Object]> Specify environment variables that will be visible to browser. Defaults to `process.env`.
 276 |   - `devtools` <[boolean]> Whether to auto-open DevTools panel for each tab. If this option is `true`, the `headless` option will be set `false`.
 277 | - returns: <[Promise]<[Browser]>> Promise which resolves to browser instance.
 278 | 
 279 | The method launches a browser instance with given arguments. The browser will be closed when the parent node.js process is closed.
 280 | 
 281 | > **NOTE** Puppeteer can also be used to control the Chrome browser, but it works best with the version of Chromium it is bundled with. There is no
 282 |  guarantee it will work with any other version. Use `executablePath` option with extreme caution.
 283 | If Google Chrome (rather than Chromium) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested.
 284 | >
 285 | > In [puppeteer.launch([options])](#puppeteerlaunchoptions) above, any mention of Chromium also applies to Chrome.
 286 | >
 287 | > See [`this article`](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for a description
 288 |   of the differences between Chromium and Chrome. [`This article`](https://chromium.googlesource.com/chromium/src/+/lkcr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users.
 289 | 
 290 | ### class: Browser
 291 | 
 292 | * extends: [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter)
 293 | 
 294 | A Browser is created when Puppeteer connects to a Chromium instance, either through [`puppeteer.launch`](#puppeteerlaunchoptions) or [`puppeteer.connect`](#puppeteerconnectoptions).
 295 | 
 296 | An example of using a [Browser] to create a [Page]:
 297 | ```js
 298 | const puppeteer = require('puppeteer');
 299 | 
 300 | puppeteer.launch().then(async browser => {
 301 |   const page = await browser.newPage();
 302 |   await page.goto('https://example.com');
 303 |   await browser.close();
 304 | });
 305 | ```
 306 | 
 307 | An example of disconnecting from and reconnecting to a [Browser]:
 308 | ```js
 309 | const puppeteer = require('puppeteer');
 310 | 
 311 | puppeteer.launch().then(async browser => {
 312 |   // Store the endpoint to be able to reconnect to Chromium
 313 |   const browserWSEndpoint = browser.wsEndpoint();
 314 |   // Disconnect puppeteer from Chromium
 315 |   browser.disconnect();
 316 | 
 317 |   // Use the endpoint to reestablish a connection
 318 |   const browser2 = await puppeteer.connect({browserWSEndpoint});
 319 |   // Close Chromium
 320 |   await browser2.close();
 321 | });
 322 | ```
 323 | #### event: 'disconnected'
 324 | Emitted when puppeteer gets disconnected from the Chromium instance. This might happen because one of the following:
 325 | - Chromium is closed or crashed
 326 | - `browser.disconnect` method was called
 327 | 
 328 | #### event: 'targetchanged'
 329 | - <[Target]>
 330 | 
 331 | Emitted when the url of a target changes.
 332 | 
 333 | #### event: 'targetcreated'
 334 | - <[Target]>
 335 | 
 336 | Emitted when a target is created, for example when a new page is opened by [`window.open`](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) or [`browser.newPage`](#browsernewpage).
 337 | 
 338 | #### event: 'targetdestroyed'
 339 | - <[Target]>
 340 | 
 341 | Emitted when a target is destroyed, for example when a page is closed.
 342 | 
 343 | #### browser.close()
 344 | - returns: <[Promise]>
 345 | 
 346 | Closes Chromium and all of its pages (if any were opened). The browser object itself is considered disposed and cannot be used anymore.
 347 | 
 348 | #### browser.disconnect()
 349 | 
 350 | Disconnects Puppeteer from the browser, but leaves the Chromium process running. After calling `disconnect`, the browser object is considered disposed and cannot be used anymore.
 351 | 
 352 | #### browser.newPage()
 353 | - returns: <[Promise]<[Page]>> Promise which resolves to a new [Page] object.
 354 | 
 355 | #### browser.pages()
 356 | - returns: <[Promise]<[Array]<[Page]>>> Promise which resolves to an array of all open pages.
 357 | 
 358 | #### browser.process()
 359 | - returns: <?[ChildProcess]> Spawned browser process. Returns `null` if the browser instance was created with `puppeteer.connect` method.
 360 | 
 361 | #### browser.targets()
 362 | - returns: <[Array]<[Target]>> An array of all active targets.
 363 | 
 364 | #### browser.userAgent()
 365 | - returns: <[Promise]<[string]>> Promise which resolves to the browser's original user agent.
 366 | 
 367 | > **NOTE** Pages can override browser user agent with [page.setUserAgent](#pagesetuseragentuseragent)
 368 | 
 369 | #### browser.version()
 370 | - returns: <[Promise]<[string]>> For headless Chromium, this is similar to `HeadlessChrome/61.0.3153.0`. For non-headless, this is similar to `Chrome/61.0.3153.0`.
 371 | 
 372 | > **NOTE** the format of browser.version() might change with future releases of Chromium.
 373 | 
 374 | #### browser.wsEndpoint()
 375 | - returns: <[string]> Browser websocket url.
 376 | 
 377 | Browser websocket endpoint which can be used as an argument to
 378 | [puppeteer.connect](#puppeteerconnectoptions). The format is `ws://${host}:${port}/devtools/browser/<id>`
 379 | 
 380 | You can find the `webSocketDebuggerUrl` from `http://${host}:${port}/json/version`. Learn more about the [devtools protocol](https://chromedevtools.github.io/devtools-protocol) and the [browser endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target).
 381 | 
 382 | ### class: Page
 383 | 
 384 | * extends: [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter)
 385 | 
 386 | Page provides methods to interact with a single tab in Chromium. One [Browser] instance might have multiple [Page] instances.
 387 | 
 388 | This example creates a page, navigates it to a URL, and then saves a screenshot:
 389 | ```js
 390 | const puppeteer = require('puppeteer');
 391 | 
 392 | puppeteer.launch().then(async browser => {
 393 |   const page = await browser.newPage();
 394 |   await page.goto('https://example.com');
 395 |   await page.screenshot({path: 'screenshot.png'});
 396 |   await browser.close();
 397 | });
 398 | ```
 399 | 
 400 | The Page class emits various events (described below) which can be handled using any of Node's native EventEmitter methods, such as `on` or `once`.
 401 | 
 402 | This example logs a message for a single page `load` event:
 403 | ```js
 404 | page.once('load', () => console.log('Page loaded!'));
 405 | ```
 406 | 
 407 | #### event: 'console'
 408 | - <[ConsoleMessage]>
 409 | 
 410 | Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. Also emitted if the page throws an error or a warning.
 411 | 
 412 | The arguments passed into `console.log` appear as arguments on the event handler.
 413 | 
 414 | An example of handling `console` event:
 415 | ```js
 416 | page.on('console', msg => {
 417 |   for (let i = 0; i < msg.args.length; ++i)
 418 |     console.log(`${i}: ${msg.args[i]}`);
 419 | });
 420 | page.evaluate(() => console.log('hello', 5, {foo: 'bar'}));
 421 | ```
 422 | 
 423 | #### event: 'dialog'
 424 | - <[Dialog]>
 425 | 
 426 | Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Puppeteer can respond to the dialog via [Dialog]'s [accept](#dialogacceptprompttext) or [dismiss](#dialogdismiss) methods.
 427 | 
 428 | #### event: 'error'
 429 | - <[Error]>
 430 | 
 431 | Emitted when the page crashes.
 432 | 
 433 | > **NOTE** `error` event has a special meaning in Node, see [error events](https://nodejs.org/api/events.html#events_error_events) for details.
 434 | 
 435 | #### event: 'frameattached'
 436 | - <[Frame]>
 437 | 
 438 | Emitted when a frame is attached.
 439 | 
 440 | #### event: 'framedetached'
 441 | - <[Frame]>
 442 | 
 443 | Emitted when a frame is detached.
 444 | 
 445 | #### event: 'framenavigated'
 446 | - <[Frame]>
 447 | 
 448 | Emitted when a frame is navigated to a new url.
 449 | 
 450 | #### event: 'load'
 451 | 
 452 | Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched.
 453 | 
 454 | #### event: 'metrics'
 455 | - <[Object]>
 456 |   - `title` <[string]> The title passed to `console.timeStamp`.
 457 |   - `metrics` <[Object]> Object containing metrics as key/value pairs. The values
 458 |     of metrics are of <[number]> type.
 459 | 
 460 | Emitted when the JavaScript code makes a call to `console.timeStamp`. For the list
 461 | of metrics see `page.metrics`.
 462 | 
 463 | #### event: 'pageerror'
 464 | - <[string]> The exception message
 465 | 
 466 | Emitted when an uncaught exception happens within the page.
 467 | 
 468 | #### event: 'request'
 469 | - <[Request]>
 470 | 
 471 | Emitted when a page issues a request. The [request] object is read-only.
 472 | In order to intercept and mutate requests, see `page.setRequestInterception`.
 473 | 
 474 | #### event: 'requestfailed'
 475 | - <[Request]>
 476 | 
 477 | Emitted when a request fails, for example by timing out.
 478 | 
 479 | #### event: 'requestfinished'
 480 | - <[Request]>
 481 | 
 482 | Emitted when a request finishes successfully.
 483 | 
 484 | #### event: 'response'
 485 | - <[Response]>
 486 | 
 487 | Emitted when a [response] is received.
 488 | 
 489 | #### page.$(selector)
 490 | - `selector` <[string]> A [selector] to query page for
 491 | - returns: <[Promise]<?[ElementHandle]>>
 492 | 
 493 | The method runs `document.querySelector` within the page. If no element matches the selector, the return value resolve to `null`.
 494 | 
 495 | Shortcut for [page.mainFrame().$(selector)](#frameselector).
 496 | 
 497 | #### page.$$(selector)
 498 | - `selector` <[string]> A [selector] to query page for
 499 | - returns: <[Promise]<[Array]<[ElementHandle]>>>
 500 | 
 501 | The method runs `document.querySelectorAll` within the page. If no elements match the selector, the return value resolve to `[]`.
 502 | 
 503 | Shortcut for [page.mainFrame().$$(selector)](#frameselector-1).
 504 | 
 505 | 
 506 | #### page.$$eval(selector, pageFunction[, ...args])
 507 | - `selector` <[string]> A [selector] to query frame for
 508 | - `pageFunction` <[function]> Function to be evaluated in browser context
 509 | - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
 510 | - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
 511 | 
 512 | This method runs `document.querySelectorAll` within the page and passes it as the first argument to `pageFunction`.
 513 | 
 514 | If `pageFunction` returns a [Promise], then `page.$$eval` would wait for the promise to resolve and return its value.
 515 | 
 516 | Examples:
 517 | ```js
 518 | const divsCounts = await page.$$eval('div', divs => divs.length);
 519 | ```
 520 | 
 521 | #### page.$eval(selector, pageFunction[, ...args])
 522 | - `selector` <[string]> A [selector] to query page for
 523 | - `pageFunction` <[function]> Function to be evaluated in browser context
 524 | - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
 525 | - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
 526 | 
 527 | This method runs `document.querySelector` within the page and passes it as the first argument to `pageFunction`. If there's no element matching `selector`, the method throws an error.
 528 | 
 529 | If `pageFunction` returns a [Promise], then `page.$eval` would wait for the promise to resolve and return its value.
 530 | 
 531 | Examples:
 532 | ```js
 533 | const searchValue = await page.$eval('#search', el => el.value);
 534 | const preloadHref = await page.$eval('link[rel=preload]', el => el.href);
 535 | const html = await page.$eval('.main-container', e => e.outerHTML);
 536 | ```
 537 | 
 538 | Shortcut for [page.mainFrame().$eval(selector, pageFunction)](#frameevalselector-pagefunction-args).
 539 | 
 540 | #### page.$x(expression)
 541 | - `expression` <[string]> Expression to [evaluate](https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate).
 542 | - returns: <[Promise]<[Array]<[ElementHandle]>>>
 543 | 
 544 | The method evluates the XPath expression.
 545 | 
 546 | Shortcut for [page.mainFrame().$x(expression)](#frameexpression)
 547 | 
 548 | #### page.addScriptTag(options)
 549 | - `options` <[Object]>
 550 |   - `url` <[string]> Url of a script to be added.
 551 |   - `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
 552 |   - `content` <[string]> Raw JavaScript content to be injected into frame.
 553 | - returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the script's onload fires or when the script content was injected into frame.
 554 | 
 555 | Adds a `<script>` tag into the page with the desired url or content.
 556 | 
 557 | Shortcut for [page.mainFrame().addScriptTag(options)](#frameaddscripttagoptions).
 558 | 
 559 | #### page.addStyleTag(options)
 560 | - `options` <[Object]>
 561 |   - `url` <[string]> Url of the `<link>` tag.
 562 |   - `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
 563 |   - `content` <[string]> Raw CSS content to be injected into frame.
 564 | - returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
 565 | 
 566 | Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the content.
 567 | 
 568 | Shortcut for [page.mainFrame().addStyleTag(options)](#frameaddstyletagoptions).
 569 | 
 570 | #### page.authenticate(credentials)
 571 | - `credentials` <?[Object]>
 572 |   - `username` <[string]>
 573 |   - `password` <[string]>
 574 | - returns: <[Promise]>
 575 | 
 576 | Provide credentials for [http authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
 577 | 
 578 | To disable authentication, pass `null`.
 579 | 
 580 | #### page.bringToFront()
 581 | 
 582 | - returns: <[Promise]>
 583 | 
 584 | Brings page to front (activates tab).
 585 | 
 586 | #### page.click(selector[, options])
 587 | - `selector` <[string]> A [selector] to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked.
 588 | - `options` <[Object]>
 589 |   - `button` <[string]> `left`, `right`, or `middle`, defaults to `left`.
 590 |   - `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
 591 |   - `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
 592 | - returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully clicked. The Promise will be rejected if there is no element matching `selector`.
 593 | 
 594 | This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.mouse](#pagemouse) to click in the center of the element.
 595 | If there's no element matching `selector`, the method throws an error.
 596 | 
 597 | #### page.close()
 598 | - returns: <[Promise]>
 599 | 
 600 | #### page.content()
 601 | - returns: <[Promise]<[String]>>
 602 | 
 603 | Gets the full HTML contents of the page, including the doctype.
 604 | 
 605 | #### page.cookies(...urls)
 606 | - `...urls` <...[string]>
 607 | - returns: <[Promise]<[Array]<[Object]>>>
 608 |   - `name` <[string]>
 609 |   - `value` <[string]>
 610 |   - `domain` <[string]>
 611 |   - `path` <[string]>
 612 |   - `expires` <[number]> Unix time in seconds.
 613 |   - `httpOnly` <[boolean]>
 614 |   - `secure` <[boolean]>
 615 |   - `session` <[boolean]>
 616 |   - `sameSite` <[string]> `"Strict"` or `"Lax"`.
 617 | 
 618 | If no URLs are specified, this method returns cookies for the current page URL.
 619 | If URLs are specified, only cookies for those URLs are returned.
 620 | 
 621 | #### page.coverage
 622 | 
 623 | - returns: <[Coverage]>
 624 | 
 625 | #### page.deleteCookie(...cookies)
 626 | - `...cookies` <...[Object]>
 627 |   - `name` <[string]> **required**
 628 |   - `url` <[string]>
 629 |   - `domain` <[string]>
 630 |   - `path` <[string]>
 631 |   - `secure` <[boolean]>
 632 | - returns: <[Promise]>
 633 | 
 634 | #### page.emulate(options)
 635 | - `options` <[Object]>
 636 |   - `viewport` <[Object]>
 637 |     - `width` <[number]> page width in pixels.
 638 |     - `height` <[number]> page height in pixels.
 639 |     - `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as dpr). Defaults to `1`.
 640 |     - `isMobile` <[boolean]> Whether the `meta viewport` tag is taken into account. Defaults to `false`.
 641 |     - `hasTouch`<[boolean]> Specifies if viewport supports touch events. Defaults to `false`
 642 |     - `isLandscape` <[boolean]> Specifies if viewport is in landscape mode. Defaults to `false`.
 643 |   - `userAgent` <[string]>
 644 | - returns: <[Promise]>
 645 | 
 646 | Emulates given device metrics and user agent. This method is a shortcut for calling two methods:
 647 | - [page.setUserAgent(userAgent)](#pagesetuseragentuseragent)
 648 | - [page.setViewport(viewport)](#pagesetviewportviewport)
 649 | 
 650 | To aid emulation, puppeteer provides a list of device descriptors which can be obtained via the `require('puppeteer/DeviceDescriptors')` command.
 651 | Below is an example of emulating an iPhone 6 in puppeteer:
 652 | ```js
 653 | const puppeteer = require('puppeteer');
 654 | const devices = require('puppeteer/DeviceDescriptors');
 655 | const iPhone = devices['iPhone 6'];
 656 | 
 657 | puppeteer.launch().then(async browser => {
 658 |   const page = await browser.newPage();
 659 |   await page.emulate(iPhone);
 660 |   await page.goto('https://www.google.com');
 661 |   // other actions...
 662 |   await browser.close();
 663 | });
 664 | ```
 665 | 
 666 | List of all available devices is available in the source code: [DeviceDescriptors.js](https://github.com/GoogleChrome/puppeteer/blob/master/DeviceDescriptors.js).
 667 | 
 668 | #### page.emulateMedia(mediaType)
 669 |   - `mediaType` <?[string]> Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables media emulation.
 670 |   - returns: <[Promise]>
 671 | 
 672 | #### page.evaluate(pageFunction, ...args)
 673 | - `pageFunction` <[function]|[string]> Function to be evaluated in the page context
 674 | - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
 675 | - returns: <[Promise]<[Serializable]>> Resolves to the return value of `pageFunction`
 676 | 
 677 | If the function, passed to the `page.evaluate`, returns a [Promise], then `page.evaluate` would wait for the promise to resolve and return its value.
 678 | 
 679 | If the function passed into `page.evaluate` returns a non-[Serializable] value, then `page.evaluate` resolves to `undefined`.
 680 | 
 681 | ```js
 682 | const result = await page.evaluate(() => {
 683 |   return Promise.resolve(8 * 7);
 684 | });
 685 | console.log(result); // prints "56"
 686 | ```
 687 | 
 688 | A string can also be passed in instead of a function.
 689 | 
 690 | ```js
 691 | console.log(await page.evaluate('1 + 2')); // prints "3"
 692 | ```
 693 | 
 694 | [ElementHandle] instances can be passed as arguments to the `page.evaluate`:
 695 | ```js
 696 | const bodyHandle = await page.$('body');
 697 | const html = await page.evaluate(body => body.innerHTML, bodyHandle);
 698 | await bodyHandle.dispose();
 699 | ```
 700 | 
 701 | Shortcut for [page.mainFrame().evaluate(pageFunction, ...args)](#frameevaluatepagefunction-args).
 702 | 
 703 | #### page.evaluateHandle(pageFunction, ...args)
 704 | - `pageFunction` <[function]|[string]> Function to be evaluated in the page context
 705 | - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
 706 | - returns: <[Promise]<[JSHandle]>> Resolves to the return value of `pageFunction`
 707 | 
 708 | If the function, passed to the `page.evaluateHandle`, returns a [Promise], then `page.evaluateHandle` would wait for the promise to resolve and return its value.
 709 | 
 710 | ```js
 711 | const aWindowHandle = await page.evaluateHandle(() => Promise.resolve(window));
 712 | aWindowHandle; // Handle for the window object.
 713 | ```
 714 | 
 715 | A string can also be passed in instead of a function.
 716 | 
 717 | ```js
 718 | const aHandle = await page.evaluateHandle('document'); // Handle for the 'document'.
 719 | ```
 720 | 
 721 | [JSHandle] instances can be passed as arguments to the `page.evaluateHandle`:
 722 | ```js
 723 | const aHandle = await page.evaluateHandle(() => document.body);
 724 | const resultHandle = await page.evaluateHandle(body => body.innerHTML, aHandle);
 725 | console.log(await resultHandle.jsonValue());
 726 | await resultHandle.dispose();
 727 | ```
 728 | 
 729 | Shortcut for [page.mainFrame().executionContext().evaluateHandle(pageFunction, ...args)](#executioncontextevaluatehandlepagefunction-args).
 730 | 
 731 | 
 732 | #### page.evaluateOnNewDocument(pageFunction, ...args)
 733 | - `pageFunction` <[function]|[string]> Function to be evaluated in browser context
 734 | - `...args` <...[Serializable]> Arguments to pass to `pageFunction`
 735 | - returns: <[Promise]>
 736 | 
 737 | Adds a function which would be invoked in one of the following scenarios:
 738 | - whenever the page is navigated
 739 | - whenever the child frame is attached or navigated. In this case, the function is invoked in the context of the newly attached frame
 740 | 
 741 | The function is invoked after the document was created but before any of its scripts were run. This is useful to amend JavaScript environment, e.g. to seed `Math.random`.
 742 | 
 743 | An example of overriding the navigator.languages property before the page loads:
 744 | 
 745 | ```js
 746 | // preload.js
 747 | 
 748 | // overwrite the `languages` property to use a custom getter
 749 | Object.defineProperty(navigator, "languages", {
 750 |   get: function() {
 751 |     return ["en-US", "en", "bn"];
 752 |   };
 753 | });
 754 | 
 755 | // In your puppeteer script, assuming the preload.js file is in same folder of our script
 756 | const preloadFile = fs.readFileSync('./preload.js', 'utf8');
 757 | await page.evaluateOnNewDocument(preloadFile);
 758 | ```
 759 | 
 760 | #### page.exposeFunction(name, puppeteerFunction)
 761 | - `name` <[string]> Name of the function on the window object
 762 | - `puppeteerFunction` <[function]> Callback function which will be called in Puppeteer's context.
 763 | - returns: <[Promise]>
 764 | 
 765 | The method adds a function called `name` on the page's `window` object.
 766 | When called, the function executes `puppeteerFunction` in node.js and returns a [Promise] which resolves to the return value of `puppeteerFunction`.
 767 | 
 768 | If the `puppeteerFunction` returns a [Promise], it will be awaited.
 769 | 
 770 | > **NOTE** Functions installed via `page.exposeFunction` survive navigations.
 771 | 
 772 | An example of adding an `md5` function into the page:
 773 | ```js
 774 | const puppeteer = require('puppeteer');
 775 | const crypto = require('crypto');
 776 | 
 777 | puppeteer.launch().then(async browser => {
 778 |   const page = await browser.newPage();
 779 |   page.on('console', msg => console.log(msg.text));
 780 |   await page.exposeFunction('md5', text =>
 781 |     crypto.createHash('md5').update(text).digest('hex')
 782 |   );
 783 |   await page.evaluate(async () => {
 784 |     // use window.md5 to compute hashes
 785 |     const myString = 'PUPPETEER';
 786 |     const myHash = await window.md5(myString);
 787 |     console.log(`md5 of ${myString} is ${myHash}`);
 788 |   });
 789 |   await browser.close();
 790 | });
 791 | ```
 792 | 
 793 | An example of adding a `window.readfile` function into the page:
 794 | 
 795 | ```js
 796 | const puppeteer = require('puppeteer');
 797 | const fs = require('fs');
 798 | 
 799 | puppeteer.launch().then(async browser => {
 800 |   const page = await browser.newPage();
 801 |   page.on('console', msg => console.log(msg.text));
 802 |   await page.exposeFunction('readfile', async filePath => {
 803 |     return new Promise((resolve, reject) => {
 804 |       fs.readFile(filePath, 'utf8', (err, text) => {
 805 |         if (err)
 806 |           reject(err);
 807 |         else
 808 |           resolve(text);
 809 |       });
 810 |     });
 811 |   });
 812 |   await page.evaluate(async () => {
 813 |     // use window.readfile to read contents of a file
 814 |     const content = await window.readfile('/etc/hosts');
 815 |     console.log(content);
 816 |   });
 817 |   await browser.close();
 818 | });
 819 | 
 820 | ```
 821 | 
 822 | #### page.focus(selector)
 823 | - `selector` <[string]> A [selector] of an element to focus. If there are multiple elements satisfying the selector, the first will be focused.
 824 | - returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully focused. The promise will be rejected if there is no element matching `selector`.
 825 | 
 826 | This method fetches an element with `selector` and focuses it.
 827 | If there's no element matching `selector`, the method throws an error.
 828 | 
 829 | #### page.frames()
 830 | - returns: <[Array]<[Frame]>> An array of all frames attached to the page.
 831 | 
 832 | #### page.goBack(options)
 833 | - `options` <[Object]> Navigation parameters which might have the following properties:
 834 |   - `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout.
 835 |   - `waitUntil` <[string]|[Array]<[string]>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
 836 |     - `load` - consider navigation to be finished when the `load` event is fired.
 837 |     - `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
 838 |     - `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
 839 |     - `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
 840 | - returns: <[Promise]<?[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. If
 841 | can not go back, resolves to `null`.
 842 | 
 843 | Navigate to the previous page in history.
 844 | 
 845 | #### page.goForward(options)
 846 | - `options` <[Object]> Navigation parameters which might have the following properties:
 847 |   - `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout.
 848 |   - `waitUntil` <[string]|[Array]<[string]>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
 849 |     - `load` - consider navigation to be finished when the `load` event is fired.
 850 |     - `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
 851 |     - `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
 852 |     - `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
 853 | - returns: <[Promise]<?[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. If
 854 | can not go back, resolves to `null`.
 855 | 
 856 | Navigate to the next page in history.
 857 | 
 858 | #### page.goto(url, options)
 859 | - `url` <[string]> URL to navigate page to. The url should include scheme, e.g. `https://`.
 860 | - `options` <[Object]> Navigation parameters which might have the following properties:
 861 |   - `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout.
 862 |   - `waitUntil` <[string]|[Array]<[string]>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
 863 |     - `load` - consider navigation to be finished when the `load` event is fired.
 864 |     - `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
 865 |     - `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
 866 |     - `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
 867 | - returns: <[Promise]<?[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
 868 | 
 869 | The `page.goto` will throw an error if:
 870 | - there's an SSL error (e.g. in case of self-signed certificates).
 871 | - target URL is invalid.
 872 | - the `timeout` is exceeded during navigation.
 873 | - the main resource failed to load.
 874 | 
 875 | > **NOTE** `page.goto` either throw or return a main resource response. The only exception is navigation to `about:blank`, which would succeed and return `null`.
 876 | 
 877 | > **NOTE** Headless mode doesn't support navigating to a PDF document. See the [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
 878 | 
 879 | #### page.hover(selector)
 880 | - `selector` <[string]> A [selector] to search for element to hover. If there are multiple elements satisfying the selector, the first will be hovered.
 881 | - returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully hovered. Promise gets rejected if there's no element matching `selector`.
 882 | 
 883 | This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.mouse](#pagemouse) to hover over the center of the element.
 884 | If there's no element matching `selector`, the method throws an error.
 885 | 
 886 | #### page.keyboard
 887 | 
 888 | - returns: <[Keyboard]>
 889 | 
 890 | #### page.mainFrame()
 891 | - returns: <[Frame]> returns page's main frame.
 892 | 
 893 | Page is guaranteed to have a main frame which persists during navigations.
 894 | 
 895 | #### page.metrics()
 896 | - returns: <[Promise]<[Object]>> Object containing metrics as key/value pairs.
 897 |   - `Timestamp` <[number]> The timestamp when the metrics sample was taken.
 898 |   - `Documents` <[number]> Number of documents in the page.
 899 |   - `Frames` <[number]> Number of frames in the page.
 900 |   - `JSEventListeners` <[number]> Number of events in the page.
 901 |   - `Nodes` <[number]> Number of DOM nodes in the page.
 902 |   - `LayoutCount` <[number]> Total number of full or partial page layout.
 903 |   - `RecalcStyleCount` <[number]> Total number of page style recalculations.
 904 |   - `LayoutDuration` <[number]> Combined durations of all page layouts.
 905 |   - `RecalcStyleDuration` <[number]> Combined duration of all page style recalculations.
 906 |   - `ScriptDuration` <[number]> Combined duration of JavaScript execution.
 907 |   - `TaskDuration` <[number]> Combined duration of all tasks performed by the browser.
 908 |   - `JSHeapUsedSize` <[number]> Used JavaScript heap size.
 909 |   - `JSHeapTotalSize` <[number]> Total JavaScript heap size.
 910 | 
 911 | > **NOTE** All timestamps are in monotonic time: monotonically increasing time in seconds since an arbitrary point in the past.
 912 | 
 913 | #### page.mouse
 914 | 
 915 | - returns: <[Mouse]>
 916 | 
 917 | #### page.pdf(options)
 918 | - `options` <[Object]> Options object which might have the following properties:
 919 |   - `path` <[string]> The file path to save the PDF to. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). If no path is provided, the PDF won't be saved to the disk.
 920 |   - `scale` <[number]> Scale of the webpage rendering. Defaults to `1`.
 921 |   - `displayHeaderFooter` <[boolean]> Display header and footer. Defaults to `false`.
 922 |   - `headerTemplate` <[string]> HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them:
 923 |     - `date` formatted print date
 924 |     - `title` document title
 925 |     - `url` document location
 926 |     - `pageNumber` current page number
 927 |     - `totalPages` total pages in the document
 928 |   - `footerTemplate` <[string]> HTML template for the print footer. Should use the same format as the `headerTemplate`.
 929 |   - `printBackground` <[boolean]> Print background graphics. Defaults to `false`.
 930 |   - `landscape` <[boolean]> Paper orientation. Defaults to `false`.
 931 |   - `pageRanges` <[string]> Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages.
 932 |   - `format` <[string]> Paper format. If set, takes priority over `width` or `height` options. Defaults to 'Letter'.
 933 |   - `width` <[string]> Paper width, accepts values labeled with units.
 934 |   - `height` <[string]> Paper height, accepts values labeled with units.
 935 |   - `margin` <[Object]> Paper margins, defaults to none.
 936 |     - `top` <[string]> Top margin, accepts values labeled with units.
 937 |     - `right` <[string]> Right margin, accepts values labeled with units.
 938 |     - `bottom` <[string]> Bottom margin, accepts values labeled with units.
 939 |     - `left` <[string]> Left margin, accepts values labeled with units.
 940 | - returns: <[Promise]<[Buffer]>> Promise which resolves with PDF buffer.
 941 | 
 942 | > **NOTE** Generating a pdf is currently only supported in Chrome headless.
 943 | 
 944 | `page.pdf()` generates a pdf of the page with `print` css media. To generate a pdf with `screen` media, call [page.emulateMedia('screen')](#pageemulatemediamediatype) before calling `page.pdf()`:
 945 | 
 946 | ```js
 947 | // Generates a PDF with 'screen' media type.
 948 | await page.emulateMedia('screen');
 949 | await page.pdf({path: 'page.pdf'});
 950 | ```
 951 | 
 952 | The `width`, `height`, and `margin` options accept values labeled with units. Unlabeled values are treated as pixels.
 953 | 
 954 | A few examples:
 955 | - `page.pdf({width: 100})` - prints with width set to 100 pixels
 956 | - `page.pdf({width: '100px'})` - prints with width set to 100 pixels
 957 | - `page.pdf({width: '10cm'})` - prints with width set to 10 centimeters.
 958 | 
 959 | All possible units are:
 960 | - `px` - pixel
 961 | - `in` - inch
 962 | - `cm` - centimeter
 963 | - `mm` - millimeter
 964 | 
 965 | The `format` options are:
 966 | - `Letter`: 8.5in x 11in
 967 | - `Legal`: 8.5in x 14in
 968 | - `Tabloid`: 11in x 17in
 969 | - `Ledger`: 17in x 11in
 970 | - `A0`: 33.1in x 46.8in
 971 | - `A1`: 23.4in x 33.1in
 972 | - `A2`: 16.5in x 23.4in
 973 | - `A3`: 11.7in x 16.5in
 974 | - `A4`: 8.27in x 11.7in
 975 | - `A5`: 5.83in x 8.27in
 976 | - `A6`: 4.13in x 5.83in
 977 | 
 978 | #### page.queryObjects(prototypeHandle)
 979 | - `prototypeHandle` <[JSHandle]> A handle to the object prototype.
 980 | - returns: <[Promise]<[JSHandle]>> Promise which resolves to a handle to an array of objects with this prototype.
 981 | 
 982 | The method iterates JavaScript heap and finds all the objects with the given prototype.
 983 | 
 984 | ```js
 985 | // Create a Map object
 986 | await page.evaluate(() => window.map = new Map());
 987 | // Get a handle to the Map object prototype
 988 | const mapPrototype = await page.evaluateHandle(() => Map.prototype);
 989 | // Query all map instances into an array
 990 | const mapInstances = await page.queryObjects(mapPrototype);
 991 | // Count amount of map objects in heap
 992 | const count = await page.evaluate(maps => maps.length, mapInstances);
 993 | await mapInstances.dispose();
 994 | await mapPrototype.dispose();
 995 | ```
 996 | 
 997 | Shortcut for [page.mainFrame().executionContext().queryObjects(prototypeHandle)](#executioncontextqueryobjectsprototypehandle).
 998 | 
 999 | #### page.reload(options)
1000 | - `options` <[Object]> Navigation parameters which might have the following properties:
1001 |   - `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout.
1002 |   - `waitUntil` <[string]|[Array]<[string]>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
1003 |     - `load` - consider navigation to be finished when the `load` event is fired.
1004 |     - `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
1005 |     - `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
1006 |     - `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
1007 | - returns: <[Promise]<[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
1008 | 
1009 | #### page.screenshot([options])
1010 | - `options` <[Object]> Options object which might have the following properties:
1011 |     - `path` <[string]> The file path to save the image to. The screenshot type will be inferred from file extension. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). If no path is provided, the image won't be saved to the disk.
1012 |     - `type` <[string]> Specify screenshot type, can be either `jpeg` or `png`. Defaults to 'png'.
1013 |     - `quality` <[number]> The quality of the image, between 0-100. Not applicable to `png` images.
1014 |     - `fullPage` <[boolean]> When true, takes a screenshot of the full scrollable page. Defaults to `false`.
1015 |     - `clip` <[Object]> An object which specifies clipping region of the page. Should have the following fields:
1016 |         - `x` <[number]> x-coordinate of top-left corner of clip area
1017 |         - `y` <[number]> y-coordinate of top-left corner of clip area
1018 |         - `width` <[number]> width of clipping area
1019 |         - `height` <[number]> height of clipping area
1020 |     - `omitBackground` <[boolean]> Hides default white background and allows capturing screenshots with transparency. Defaults to `false`.
1021 | - returns: <[Promise]<[Buffer]>> Promise which resolves to buffer with captured screenshot
1022 | 
1023 | #### page.select(selector, ...values)
1024 | - `selector` <[string]> A [selector] to query page for
1025 | - `...values` <...[string]> Values of options to select. If the `<select>` has the `multiple` attribute, all values are considered, otherwise only the first one is taken into account.
1026 | - returns: <[Promise]<[Array]<[string]>>> Returns an array of option values that have been successfully selected.
1027 | 
1028 | Triggers a `change` and `input` event once all the provided options have been selected.
1029 | If there's no `<select>` element matching `selector`, the method throws an error.
1030 | 
1031 | ```js
1032 | page.select('select#colors', 'blue'); // single selection
1033 | page.select('select#colors', 'red', 'green', 'blue'); // multiple selections
1034 | ```
1035 | 
1036 | Shortcut for [page.mainFrame.select()](#frameselectselector-values)
1037 | 
1038 | #### page.setContent(html)
1039 | - `html` <[string]> HTML markup to assign to the page.
1040 | - returns: <[Promise]>
1041 | 
1042 | #### page.setCookie(...cookies)
1043 | - `...cookies` <...[Object]>
1044 |   - `name` <[string]> **required**
1045 |   - `value` <[string]> **required**
1046 |   - `url` <[string]>
1047 |   - `domain` <[string]>
1048 |   - `path` <[string]>
1049 |   - `expires` <[number]> Unix time in seconds.
1050 |   - `httpOnly` <[boolean]>
1051 |   - `secure` <[boolean]>
1052 |   - `sameSite` <[string]> `"Strict"` or `"Lax"`.
1053 | - returns: <[Promise]>
1054 | 
1055 | #### page.setExtraHTTPHeaders(headers)
1056 | - `headers` <[Object]> An object containing additional http headers to be sent with every request. All header values must be strings.
1057 | - returns: <[Promise]>
1058 | 
1059 | The extra HTTP headers will be sent with every request the page initiates.
1060 | 
1061 | > **NOTE** page.setExtraHTTPHeaders does not guarantee the order of headers in the outgoing requests.
1062 | 
1063 | #### page.setJavaScriptEnabled(enabled)
1064 | - `enabled` <[boolean]> Whether or not to enable JavaScript on the page.
1065 | - returns: <[Promise]>
1066 | 
1067 | > **NOTE** changing this value won't affect scripts that have already been run. It will take full effect on the next [navigation](#pagegotourl-options).
1068 | 
1069 | #### page.setOfflineMode(enabled)
1070 | - `enabled` <[boolean]> When `true`, enables offline mode for the page.
1071 | - returns: <[Promise]>
1072 | 
1073 | #### page.setRequestInterception(value)
1074 | - `value` <[boolean]> Whether to enable request interception.
1075 | - returns: <[Promise]>
1076 | 
1077 | Activating request interception enables `request.abort`, `request.continue` and
1078 | `request.respond` methods.
1079 | 
1080 | An example of a naïve request interceptor that aborts all image requests:
1081 | ```js
1082 | const puppeteer = require('puppeteer');
1083 | 
1084 | puppeteer.launch().then(async browser => {
1085 |   const page = await browser.newPage();
1086 |   await page.setRequestInterception(true);
1087 |   page.on('request', interceptedRequest => {
1088 |     if (interceptedRequest.url.endsWith('.png') || interceptedRequest.url.endsWith('.jpg'))
1089 |       interceptedRequest.abort();
1090 |     else
1091 |       interceptedRequest.continue();
1092 |   });
1093 |   await page.goto('https://example.com');
1094 |   await browser.close();
1095 | });
1096 | ```
1097 | 
1098 | > **NOTE** Enabling request interception disables page caching.
1099 | 
1100 | #### page.setUserAgent(userAgent)
1101 | - `userAgent` <[string]> Specific user agent to use in this page
1102 | - returns: <[Promise]> Promise which resolves when the user agent is set.
1103 | 
1104 | #### page.setViewport(viewport)
1105 | - `viewport` <[Object]>
1106 |   - `width` <[number]> page width in pixels.
1107 |   - `height` <[number]> page height in pixels.
1108 |   - `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as dpr). Defaults to `1`.
1109 |   - `isMobile` <[boolean]> Whether the `meta viewport` tag is taken into account. Defaults to `false`.
1110 |   - `hasTouch`<[boolean]> Specifies if viewport supports touch events. Defaults to `false`
1111 |   - `isLandscape` <[boolean]> Specifies if viewport is in landscape mode. Defaults to `false`.
1112 | - returns: <[Promise]>
1113 | 
1114 | > **NOTE** in certain cases, setting viewport will reload the page in order to set the `isMobile` or `hasTouch` properties.
1115 | 
1116 | In the case of multiple pages in a single browser, each page can have its own viewport size.
1117 | 
1118 | #### page.tap(selector)
1119 | - `selector` <[string]> A [selector] to search for element to tap. If there are multiple elements satisfying the selector, the first will be tapped.
1120 | - returns: <[Promise]>
1121 | 
1122 | This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.touchscreen](#pagetouchscreen) to tap in the center of the element.
1123 | If there's no element matching `selector`, the method throws an error.
1124 | 
1125 | #### page.title()
1126 | - returns: <[Promise]<[string]>> Returns page's title.
1127 | 
1128 | Shortcut for [page.mainFrame().title()](#frametitle).
1129 | 
1130 | #### page.touchscreen
1131 | - returns: <[Touchscreen]>
1132 | 
1133 | #### page.tracing
1134 | - returns: <[Tracing]>
1135 | 
1136 | #### page.type(selector, text[, options])
1137 | - `selector` <[string]> A [selector] of an element to type into. If there are multiple elements satisfying the selector, the first will be used.
1138 | - `text` <[string]> A text to type into a focused element.
1139 | - `options` <[Object]>
1140 |   - `delay` <[number]> Time to wait between key presses in milliseconds. Defaults to 0.
1141 | - returns: <[Promise]>
1142 | 
1143 | Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
1144 | 
1145 | To press a special key, like `Control` or `ArrowDown`, use [`keyboard.press`](#keyboardpresskey-options).
1146 | 
1147 | ```js
1148 | page.type('#mytextarea', 'Hello'); // Types instantly
1149 | page.type('#mytextarea', 'World', {delay: 100}); // Types slower, like a user
1150 | ```
1151 | 
1152 | #### page.url()
1153 | - returns: <[string]>
1154 | 
1155 | This is a shortcut for [page.mainFrame().url()](#frameurl)
1156 | 
1157 | #### page.viewport()
1158 | - returns: <[Object]>
1159 |   - `width` <[number]> page width in pixels.
1160 |   - `height` <[number]> page height in pixels.
1161 |   - `deviceScaleFactor` <[number]> Specify device scale factor (can be though of as dpr). Defaults to `1`.
1162 |   - `isMobile` <[boolean]> Whether the `meta viewport` tag is taken into account. Defaults to `false`.
1163 |   - `hasTouch`<[boolean]> Specifies if viewport supports touch events. Defaults to `false`
1164 |   - `isLandscape` <[boolean]> Specifies if viewport is in landscape mode. Defaults to `false`.
1165 | 
1166 | #### page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])
1167 | - `selectorOrFunctionOrTimeout` <[string]|[number]|[function]> A [selector], predicate or timeout to wait for
1168 | - `options` <[Object]> Optional waiting parameters
1169 | - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to  `pageFunction`
1170 | - returns: <[Promise]<[JSHandle]>> Promise which resolves to a JSHandle of the success value
1171 | 
1172 | This method behaves differently with respect to the type of the first parameter:
1173 | - if `selectorOrFunctionOrTimeout` is a `string`, then the first argument is treated as a [selector] to wait for and the method is a shortcut for [page.waitForSelector](#pagewaitforselectorselector-options)
1174 | - if `selectorOrFunctionOrTimeout` is a `function`, then the first argument is treated as a predicate to wait for and the method is a shortcut for [page.waitForFunction()](#pagewaitforfunctionpagefunction-options-args).
1175 | - if `selectorOrFunctionOrTimeout` is a `number`, then the first argument is treated as a timeout in milliseconds and the method returns a promise which resolves after the timeout
1176 | - otherwise, an exception is thrown
1177 | 
1178 | Shortcut for [page.mainFrame().waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#framewaitforselectororfunctionortimeout-options-args).
1179 | 
1180 | #### page.waitForFunction(pageFunction[, options[, ...args]])
1181 | - `pageFunction` <[function]|[string]> Function to be evaluated in browser context
1182 | - `options` <[Object]> Optional waiting parameters
1183 |   - `polling` <[string]|[number]> An interval at which the `pageFunction` is executed, defaults to `raf`. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. If `polling` is a string, then it can be one of the following values:
1184 |     - `raf` - to constantly execute `pageFunction` in `requestAnimationFrame` callback. This is the tightest polling mode which is suitable to observe styling changes.
1185 |     - `mutation` - to execute `pageFunction` on every DOM mutation.
1186 |   - `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds).
1187 | - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to  `pageFunction`
1188 | - returns: <[Promise]<[JSHandle]>> Promise which resolves when the `pageFunction` returns a truthy value. It resolves to a JSHandle of the truthy value.
1189 | 
1190 | The `waitForFunction` can be used to observe viewport size change:
1191 | ```js
1192 | const puppeteer = require('puppeteer');
1193 | 
1194 | puppeteer.launch().then(async browser => {
1195 |   const page = await browser.newPage();
1196 |   const watchDog = page.waitForFunction('window.innerWidth < 100');
1197 |   page.setViewport({width: 50, height: 50});
1198 |   await watchDog;
1199 |   await browser.close();
1200 | });
1201 | ```
1202 | Shortcut for [page.mainFrame().waitForFunction(pageFunction[, options[, ...args]])](#framewaitforfunctionpagefunction-options-args).
1203 | 
1204 | #### page.waitForNavigation(options)
1205 | - `options` <[Object]> Navigation parameters which might have the following properties:
1206 |   - `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout.
1207 |   - `waitUntil` <[string]|[Array]<[string]>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
1208 |     - `load` - consider navigation to be finished when the `load` event is fired.
1209 |     - `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
1210 |     - `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
1211 |     - `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
1212 | - returns: <[Promise]<[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
1213 | 
1214 | #### page.waitForSelector(selector[, options])
1215 | - `selector` <[string]> A [selector] of an element to wait for,
1216 | - `options` <[Object]> Optional waiting parameters
1217 |   - `visible` <[boolean]> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
1218 |   - `hidden` <[boolean]> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
1219 |   - `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds).
1220 | - returns: <[Promise]<[ElementHandle]>> Promise which resolves when element specified by selector string is added to DOM.
1221 | 
1222 | Wait for the `selector` to appear in page. If at the moment of calling
1223 | the method the `selector` already exists, the method will return
1224 | immediately. If the selector doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
1225 | 
1226 | This method works across navigations:
1227 | ```js
1228 | const puppeteer = require('puppeteer');
1229 | 
1230 | puppeteer.launch().then(async browser => {
1231 |   const page = await browser.newPage();
1232 |   let currentURL;
1233 |   page
1234 |     .waitForSelector('img')
1235 |     .then(() => console.log('First URL with image: ' + currentURL));
1236 |   for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com'])
1237 |     await page.goto(currentURL);
1238 |   await browser.close();
1239 | });
1240 | ```
1241 | Shortcut for [page.mainFrame().waitForSelector(selector[, options])](#framewaitforselectorselector-options).
1242 | 
1243 | 
1244 | ### class: Keyboard
1245 | 
1246 | Keyboard provides an api for managing a virtual keyboard. The high level api is [`keyboard.type`](#keyboardtypetext-options), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.
1247 | 
1248 | For finer control, you can use [`keyboard.down`](#keyboarddownkey-options), [`keyboard.up`](#keyboardupkey), and [`keyboard.sendCharacter`](#keyboardsendcharacterchar) to manually fire events as if they were generated from a real keyboard.
1249 | 
1250 | An example of holding down `Shift` in order to select and delete some text:
1251 | ```js
1252 | await page.keyboard.type('Hello World!');
1253 | await page.keyboard.press('ArrowLeft');
1254 | 
1255 | await page.keyboard.down('Shift');
1256 | for (let i = 0; i < ' World'.length; i++)
1257 |   await page.keyboard.press('ArrowLeft');
1258 | await page.keyboard.up('Shift');
1259 | 
1260 | await page.keyboard.press('Backspace');
1261 | // Result text will end up saying 'Hello!'
1262 | ```
1263 | 
1264 | An example of pressing `A`
1265 | ```js
1266 | await page.keyboard.down('Shift');
1267 | await page.keyboard.press('KeyA');
1268 | await page.keyboard.up('Shift');
1269 | ```
1270 | 
1271 | > **NOTE** On MacOS, keyboard shortcuts like `⌘ A` -> Select All do not work. See [#1313](https://github.com/GoogleChrome/puppeteer/issues/1313)
1272 | 
1273 | #### keyboard.down(key[, options])
1274 | - `key` <[string]> Name of key to press, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names.
1275 | - `options` <[Object]>
1276 |   - `text` <[string]> If specified, generates an input event with this text.
1277 | - returns: <[Promise]>
1278 | 
1279 | Dispatches a `keydown` event.
1280 | 
1281 | If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also generated. The `text` option can be specified to force an input event to be generated.
1282 | 
1283 | If `key` is a modifier key, `Shift`, `Meta`, `Control`, or `Alt`, subsequent key presses will be sent with that modifier active. To release the modifier key, use [`keyboard.up`](#keyboardupkey).
1284 | 
1285 | After the key is pressed once, subsequent calls to [`keyboard.down`](#keyboarddownkey-options) will have [repeat](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat) set to true. To release the key, use [`keyboard.up`](#keyboardupkey).
1286 | 
1287 | > **NOTE** Modifier keys DO influence `keyboard.down`. Holding down `Shift` will type the text in upper case.
1288 | 
1289 | #### keyboard.press(key[, options])
1290 | - `key` <[string]> Name of key to press, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names.
1291 | - `options` <[Object]>
1292 |   - `text` <[string]> If specified, generates an input event with this text.
1293 |   - `delay` <[number]> Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
1294 | - returns: <[Promise]>
1295 | 
1296 | If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also generated. The `text` option can be specified to force an input event to be generated.
1297 | 
1298 | > **NOTE** Modifier keys DO effect `elementHandle.press`. Holding down `Shift` will type the text in upper case.
1299 | 
1300 | Shortcut for [`keyboard.down`](#keyboarddownkey-options) and [`keyboard.up`](#keyboardupkey).
1301 | 
1302 | #### keyboard.sendCharacter(char)
1303 | - `char` <[string]> Character to send into the page.
1304 | - returns: <[Promise]>
1305 | 
1306 | Dispatches a `keypress` and `input` event. This does not send a `keydown` or `keyup` event.
1307 | 
1308 | ```js
1309 | page.keyboard.sendCharacter('嗨');
1310 | ```
1311 | 
1312 | > **NOTE** Modifier keys DO NOT effect `keyboard.sendCharacter`. Holding down `Shift` will not type the text in upper case.
1313 | 
1314 | #### keyboard.type(text, options)
1315 | - `text` <[string]> A text to type into a focused element.
1316 | - `options` <[Object]>
1317 |   - `delay` <[number]> Time to wait between key presses in milliseconds. Defaults to 0.
1318 | - returns: <[Promise]>
1319 | 
1320 | Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
1321 | 
1322 | To press a special key, like `Control` or `ArrowDown`, use [`keyboard.press`](#keyboardpresskey-options).
1323 | 
1324 | ```js
1325 | page.keyboard.type('Hello'); // Types instantly
1326 | page.keyboard.type('World', {delay: 100}); // Types slower, like a user
1327 | ```
1328 | 
1329 | > **NOTE** Modifier keys DO NOT effect `keyboard.type`. Holding down `Shift` will not type the text in upper case.
1330 | 
1331 | #### keyboard.up(key)
1332 | - `key` <[string]> Name of key to release, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names.
1333 | - returns: <[Promise]>
1334 | 
1335 | Dispatches a `keyup` event.
1336 | 
1337 | ### class: Mouse
1338 | 
1339 | #### mouse.click(x, y, [options])
1340 | - `x` <[number]>
1341 | - `y` <[number]>
1342 | - `options` <[Object]>
1343 |   - `button` <[string]> `left`, `right`, or `middle`, defaults to `left`.
1344 |   - `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
1345 |   - `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
1346 | - returns: <[Promise]>
1347 | 
1348 | Shortcut for [`mouse.move`](#mousemovex-y-options), [`mouse.down`](#mousedownoptions) and [`mouse.up`](#mouseupoptions).
1349 | 
1350 | #### mouse.down([options])
1351 | - `options` <[Object]>
1352 |   - `button` <[string]> `left`, `right`, or `middle`, defaults to `left`.
1353 |   - `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
1354 | - returns: <[Promise]>
1355 | 
1356 | Dispatches a `mousedown` event.
1357 | 
1358 | #### mouse.move(x, y, [options])
1359 | - `x` <[number]>
1360 | - `y` <[number]>
1361 | - `options` <[Object]>
1362 |   - `steps` <[number]> defaults to 1. Sends intermediate `mousemove` events.
1363 | - returns: <[Promise]>
1364 | 
1365 | Dispatches a `mousemove` event.
1366 | 
1367 | #### mouse.up([options])
1368 | - `options` <[Object]>
1369 |   - `button` <[string]> `left`, `right`, or `middle`, defaults to `left`.
1370 |   - `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
1371 | - returns: <[Promise]>
1372 | 
1373 | Dispatches a `mouseup` event.
1374 | 
1375 | ### class: Touchscreen
1376 | 
1377 | #### touchscreen.tap(x, y)
1378 | - `x` <[number]>
1379 | - `y` <[number]>
1380 | - returns: <[Promise]>
1381 | 
1382 | Dispatches a `touchstart` and `touchend` event.
1383 | 
1384 | ### class: Tracing
1385 | 
1386 | You can use [`tracing.start`](#tracingstartoptions) and [`tracing.stop`](#tracingstop) to create a trace file which can be opened in Chrome DevTools or [timeline viewer](https://chromedevtools.github.io/timeline-viewer/).
1387 | 
1388 | ```js
1389 | await page.tracing.start({path: 'trace.json'});
1390 | await page.goto('https://www.google.com');
1391 | await page.tracing.stop();
1392 | ```
1393 | 
1394 | #### tracing.start(options)
1395 | - `options` <[Object]>
1396 |   - `path` <[string]> A path to write the trace file to. **required**
1397 |   - `screenshots` <[boolean]> captures screenshots in the trace.
1398 |   - `categories` <[Array]<[string]>> specify custom categories to use instead of default.
1399 | - returns: <[Promise]>
1400 | 
1401 | Only one trace can be active at a time per browser.
1402 | 
1403 | #### tracing.stop()
1404 | - returns: <[Promise]>
1405 | 
1406 | ### class: Dialog
1407 | 
1408 | [Dialog] objects are dispatched by page via the ['dialog'](#event-dialog) event.
1409 | 
1410 | An example of using `Dialog` class:
1411 | ```js
1412 | const puppeteer = require('puppeteer');
1413 | 
1414 | puppeteer.launch().then(async browser => {
1415 |   const page = await browser.newPage();
1416 |   page.on('dialog', async dialog => {
1417 |     console.log(dialog.message());
1418 |     await dialog.dismiss();
1419 |     await browser.close();
1420 |   });
1421 |   page.evaluate(() => alert('1'));
1422 | });
1423 | ```
1424 | 
1425 | #### dialog.accept([promptText])
1426 | - `promptText` <[string]> A text to enter in prompt. Does not cause any effects if the dialog's `type` is not prompt.
1427 | - returns: <[Promise]> Promise which resolves when the dialog has been accepted.
1428 | 
1429 | #### dialog.defaultValue()
1430 | - returns: <[string]> If dialog is prompt, returns default prompt value. Otherwise, returns empty string.
1431 | 
1432 | #### dialog.dismiss()
1433 | - returns: <[Promise]> Promise which resolves when the dialog has been dismissed.
1434 | 
1435 | #### dialog.message()
1436 | - returns: <[string]> A message displayed in the dialog.
1437 | 
1438 | #### dialog.type()
1439 | - returns: <[string]> Dialog's type, can be one of `alert`, `beforeunload`, `confirm` or `prompt`.
1440 | 
1441 | ### class: ConsoleMessage
1442 | 
1443 | [ConsoleMessage] objects are dispatched by page via the ['console'](#event-console) event.
1444 | 
1445 | #### consoleMessage.args()
1446 | - returns: <[Array]<[JSHandle]>>
1447 | 
1448 | #### consoleMessage.text()
1449 | - returns: <[string]>
1450 | 
1451 | #### consoleMessage.type()
1452 | - returns: <[string]>
1453 | 
1454 | One of the following values: `'log'`, `'debug'`, `'info'`, `'error'`, `'warning'`, `'dir'`, `'dirxml'`, `'table'`, `'trace'`, `'clear'`, `'startGroup'`, `'startGroupCollapsed'`, `'endGroup'`, `'assert'`, `'profile'`, `'profileEnd'`, `'count'`, `'timeEnd'`.
1455 | 
1456 | ### class: Frame
1457 | 
1458 | At every point of time, page exposes its current frame tree via the [page.mainFrame()](#pagemainframe) and [frame.childFrames()](#framechildframes) methods.
1459 | 
1460 | [Frame] object's lifecycle is controlled by three events, dispatched on the page object:
1461 | - ['frameattached'](#event-frameattached) - fired when the frame gets attached to the page. A Frame can be attached to the page only once.
1462 | - ['framenavigated'](#event-framenavigated) - fired when the frame commits navigation to a different URL.
1463 | - ['framedetached'](#event-framedetached) - fired when the frame gets detached from the page.  A Frame can be detached from the page only once.
1464 | 
1465 | An example of dumping frame tree:
1466 | 
1467 | ```js
1468 | const puppeteer = require('puppeteer');
1469 | 
1470 | puppeteer.launch().then(async browser => {
1471 |   const page = await browser.newPage();
1472 |   await page.goto('https://www.google.com/chrome/browser/canary.html');
1473 |   dumpFrameTree(page.mainFrame(), '');
1474 |   await browser.close();
1475 | 
1476 |   function dumpFrameTree(frame, indent) {
1477 |     console.log(indent + frame.url());
1478 |     for (let child of frame.childFrames())
1479 |       dumpFrameTree(child, indent + '  ');
1480 |   }
1481 | });
1482 | ```
1483 | 
1484 | #### frame.$(selector)
1485 | - `selector` <[string]> Selector to query page for
1486 | - returns: <[Promise]<?[ElementHandle]>> Promise which resolves to ElementHandle pointing to the frame element.
1487 | 
1488 | The method queries frame for the selector. If there's no such element within the frame, the method will resolve to `null`.
1489 | 
1490 | #### frame.$$(selector)
1491 | - `selector` <[string]> Selector to query page for
1492 | - returns: <[Promise]<[Array]<[ElementHandle]>>> Promise which resolves to ElementHandles pointing to the frame elements.
1493 | 
1494 | The method runs `document.querySelectorAll` within the frame. If no elements match the selector, the return value resolve to `[]`.
1495 | 
1496 | #### frame.$$eval(selector, pageFunction[, ...args])
1497 | - `selector` <[string]> A [selector] to query frame for
1498 | - `pageFunction` <[function]> Function to be evaluated in browser context
1499 | - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
1500 | - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
1501 | 
1502 | This method runs `document.querySelectorAll` within the frame and passes it as the first argument to `pageFunction`.
1503 | 
1504 | If `pageFunction` returns a [Promise], then `frame.$$eval` would wait for the promise to resolve and return its value.
1505 | 
1506 | Examples:
1507 | ```js
1508 | const divsCounts = await frame.$$eval('div', divs => divs.length);
1509 | ```
1510 | 
1511 | #### frame.$eval(selector, pageFunction[, ...args])
1512 | - `selector` <[string]> A [selector] to query frame for
1513 | - `pageFunction` <[function]> Function to be evaluated in browser context
1514 | - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
1515 | - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
1516 | 
1517 | This method runs `document.querySelector` within the frame and passes it as the first argument to `pageFunction`. If there's no element matching `selector`, the method throws an error.
1518 | 
1519 | If `pageFunction` returns a [Promise], then `frame.$eval` would wait for the promise to resolve and return its value.
1520 | 
1521 | Examples:
1522 | ```js
1523 | const searchValue = await frame.$eval('#search', el => el.value);
1524 | const preloadHref = await frame.$eval('link[rel=preload]', el => el.href);
1525 | const html = await frame.$eval('.main-container', e => e.outerHTML);
1526 | ```
1527 | 
1528 | #### frame.$x(expression)
1529 | - `expression` <[string]> Expression to [evaluate](https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate).
1530 | - returns: <[Promise]<[Array]<[ElementHandle]>>>
1531 | 
1532 | The method evluates the XPath expression.
1533 | 
1534 | #### frame.addScriptTag(options)
1535 | - `options` <[Object]>
1536 |   - `url` <[string]> Url of a script to be added.
1537 |   - `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
1538 |   - `content` <[string]> Raw JavaScript content to be injected into frame.
1539 | - returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the script's onload fires or when the script content was injected into frame.
1540 | 
1541 | Adds a `<script>` tag into the page with the desired url or content.
1542 | 
1543 | #### frame.addStyleTag(options)
1544 | - `options` <[Object]>
1545 |   - `url` <[string]> Url of the `<link>` tag.
1546 |   - `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
1547 |   - `content` <[string]> Raw CSS content to be injected into frame.
1548 | - returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
1549 | 
1550 | Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the content.
1551 | 
1552 | #### frame.childFrames()
1553 | - returns: <[Array]<[Frame]>>
1554 | 
1555 | #### frame.content()
1556 | - returns: <[Promise]<[String]>>
1557 | 
1558 | Gets the full HTML contents of the frame, including the doctype.
1559 | 
1560 | #### frame.evaluate(pageFunction, ...args)
1561 | - `pageFunction` <[function]|[string]> Function to be evaluated in browser context
1562 | - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to  `pageFunction`
1563 | - returns: <[Promise]<[Serializable]>> Promise which resolves to function return value
1564 | 
1565 | If the function, passed to the `frame.evaluate`, returns a [Promise], then `frame.evaluate` would wait for the promise to resolve and return its value.
1566 | 
1567 | If the function passed into `frame.evaluate` returns a non-[Serializable] value, then `frame.evaluate` resolves to `undefined`.
1568 | 
1569 | ```js
1570 | const result = await frame.evaluate(() => {
1571 |   return Promise.resolve(8 * 7);
1572 | });
1573 | console.log(result); // prints "56"
1574 | ```
1575 | 
1576 | A string can also be passed in instead of a function.
1577 | 
1578 | ```js
1579 | console.log(await frame.evaluate('1 + 2')); // prints "3"
1580 | ```
1581 | 
1582 | [ElementHandle] instances can be passed as arguments to the `frame.evaluate`:
1583 | ```js
1584 | const bodyHandle = await frame.$('body');
1585 | const html = await frame.evaluate(body => body.innerHTML, bodyHandle);
1586 | await bodyHandle.dispose();
1587 | ```
1588 | 
1589 | #### frame.executionContext()
1590 | - returns: <[Promise]<[ExecutionContext]>> Execution context associated with this frame.
1591 | 
1592 | #### frame.isDetached()
1593 | - returns: <[boolean]>
1594 | 
1595 | Returns `true` if the frame has been detached, or `false` otherwise.
1596 | 
1597 | #### frame.name()
1598 | - returns: <[string]>
1599 | 
1600 | Returns frame's name attribute as specified in the tag.
1601 | 
1602 | If the name is empty, returns the id attribute instead.
1603 | 
1604 | > **NOTE** This value is calculated once when the frame is created, and will not update if the attribute is changed later.
1605 | 
1606 | #### frame.parentFrame()
1607 | - returns: <?[Frame]> Returns parent frame, if any. Detached frames and main frames return `null`.
1608 | 
1609 | #### frame.select(selector, ...values)
1610 | - `selector` <[string]> A [selector] to query frame for
1611 | - `...values` <...[string]> Values of options to select. If the `<select>` has the `multiple` attribute, all values are considered, otherwise only the first one is taken into account.
1612 | - returns: <[Promise]<[Array]<[string]>>> Returns an array of option values that have been successfully selected.
1613 | 
1614 | Triggers a `change` and `input` event once all the provided options have been selected.
1615 | If there's no `<select>` element matching `selector`, the method throws an error.
1616 | 
1617 | ```js
1618 | frame.select('select#colors', 'blue'); // single selection
1619 | frame.select('select#colors', 'red', 'green', 'blue'); // multiple selections
1620 | ```
1621 | 
1622 | #### frame.setContent(html)
1623 | - `html` <[string]> HTML markup to assign to the page.
1624 | - returns: <[Promise]>
1625 | 
1626 | #### frame.title()
1627 | - returns: <[Promise]<[string]>> Returns page's title.
1628 | 
1629 | #### frame.url()
1630 | - returns: <[string]>
1631 | 
1632 | Returns frame's url.
1633 | 
1634 | #### frame.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])
1635 | - `selectorOrFunctionOrTimeout` <[string]|[number]|[function]> A [selector], predicate or timeout to wait for
1636 | - `options` <[Object]> Optional waiting parameters
1637 | - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to  `pageFunction`
1638 | - returns: <[Promise]<[JSHandle]>> Promise which resolves to a JSHandle of the success value
1639 | 
1640 | This method behaves differently with respect to the type of the first parameter:
1641 | - if `selectorOrFunctionOrTimeout` is a `string`, then the first argument is treated as a [selector] to wait for and the method is a shortcut for [frame.waitForSelector](#framewaitforselectorselector-options)
1642 | - if `selectorOrFunctionOrTimeout` is a `function`, then the first argument is treated as a predicate to wait for and the method is a shortcut for [frame.waitForFunction()](#framewaitforfunctionpagefunction-options-args).
1643 | - if `selectorOrFunctionOrTimeout` is a `number`, then the first argument is treated as a timeout in milliseconds and the method returns a promise which resolves after the timeout
1644 | - otherwise, an exception is thrown
1645 | 
1646 | 
1647 | #### frame.waitForFunction(pageFunction[, options[, ...args]])
1648 | - `pageFunction` <[function]|[string]> Function to be evaluated in browser context
1649 | - `options` <[Object]> Optional waiting parameters
1650 |   - `polling` <[string]|[number]> An interval at which the `pageFunction` is executed, defaults to `raf`. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. If `polling` is a string, then it can be one of the following values:
1651 |     - `raf` - to constantly execute `pageFunction` in `requestAnimationFrame` callback. This is the tightest polling mode which is suitable to observe styling changes.
1652 |     - `mutation` - to execute `pageFunction` on every DOM mutation.
1653 |   - `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds).
1654 | - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to  `pageFunction`
1655 | - returns: <[Promise]<[JSHandle]>> Promise which resolves when the `pageFunction` returns a truthy value. It resolves to a JSHandle of the truthy value.
1656 | 
1657 | The `waitForFunction` can be used to observe viewport size change:
1658 | ```js
1659 | const puppeteer = require('puppeteer');
1660 | 
1661 | puppeteer.launch().then(async browser => {
1662 |   const page = await browser.newPage();
1663 |   const watchDog = page.mainFrame().waitForFunction('window.innerWidth < 100');
1664 |   page.setViewport({width: 50, height: 50});
1665 |   await watchDog;
1666 |   await browser.close();
1667 | });
1668 | ```
1669 | 
1670 | #### frame.waitForSelector(selector[, options])
1671 | - `selector` <[string]> A [selector] of an element to wait for,
1672 | - `options` <[Object]> Optional waiting parameters
1673 |   - `visible` <[boolean]> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
1674 |   - `hidden` <[boolean]> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
1675 |   - `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds).
1676 | - returns: <[Promise]<[ElementHandle]>> Promise which resolves when element specified by selector string is added to DOM.
1677 | 
1678 | Wait for the `selector` to appear in page. If at the moment of calling
1679 | the method the `selector` already exists, the method will return
1680 | immediately. If the selector doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
1681 | 
1682 | This method works across navigations:
1683 | ```js
1684 | const puppeteer = require('puppeteer');
1685 | 
1686 | puppeteer.launch().then(async browser => {
1687 |   const page = await browser.newPage();
1688 |   let currentURL;
1689 |   page.mainFrame()
1690 |     .waitForSelector('img')
1691 |     .then(() => console.log('First URL with image: ' + currentURL));
1692 |   for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com'])
1693 |     await page.goto(currentURL);
1694 |   await browser.close();
1695 | });
1696 | ```
1697 | 
1698 | ### class: ExecutionContext
1699 | 
1700 | The class represents a context for JavaScript execution. Examples of JavaScript contexts are:
1701 | - each [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) has a separate execution context
1702 | - all kind of [workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) have their own contexts
1703 | 
1704 | #### executionContext.evaluate(pageFunction, ...args)
1705 | - `pageFunction` <[function]|[string]> Function to be evaluated in `executionContext`
1706 | - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
1707 | - returns: <[Promise]<[Serializable]>> Promise which resolves to function return value
1708 | 
1709 | If the function, passed to the `executionContext.evaluate`, returns a [Promise], then `executionContext.evaluate` would wait for the promise to resolve and return its value.
1710 | 
1711 | ```js
1712 | const executionContext = page.mainFrame().executionContext();
1713 | const result = await executionContext.evaluate(() => Promise.resolve(8 * 7));
1714 | console.log(result); // prints "56"
1715 | ```
1716 | 
1717 | A string can also be passed in instead of a function.
1718 | 
1719 | ```js
1720 | console.log(await executionContext.evaluate('1 + 2')); // prints "3"
1721 | ```
1722 | 
1723 | [JSHandle] instances can be passed as arguments to the `executionContext.evaluate`:
1724 | ```js
1725 | const oneHandle = await executionContext.evaluateHandle(() => 1);
1726 | const twoHandle = await executionContext.evaluateHandle(() => 2);
1727 | const result = await executionContext.evaluate((a, b) => a + b, oneHandle, twoHandle);
1728 | await oneHandle.dispose();
1729 | await twoHandle.dispose();
1730 | console.log(result); // prints '3'.
1731 | ```
1732 | 
1733 | #### executionContext.evaluateHandle(pageFunction, ...args)
1734 | - `pageFunction` <[function]|[string]> Function to be evaluated in the `executionContext`
1735 | - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
1736 | - returns: <[Promise]<[JSHandle]>> Resolves to the return value of `pageFunction`
1737 | 
1738 | If the function, passed to the `executionContext.evaluateHandle`, returns a [Promise], then `executionContext.evaluteHandle` would wait for the promise to resolve and return its value.
1739 | 
1740 | ```js
1741 | const context = page.mainFrame().executionContext();
1742 | const aHandle = await context.evaluateHandle(() => Promise.resolve(self));
1743 | aHandle; // Handle for the global object.
1744 | ```
1745 | 
1746 | A string can also be passed in instead of a function.
1747 | 
1748 | ```js
1749 | const aHandle = await context.evaluateHandle('1 + 2'); // Handle for the '3' object.
1750 | ```
1751 | 
1752 | [JSHandle] instances can be passed as arguments to the `executionContext.evaluateHandle`:
1753 | ```js
1754 | const aHandle = await context.evaluateHandle(() => document.body);
1755 | const resultHandle = await context.evaluateHandle(body => body.innerHTML, aHandle);
1756 | console.log(await resultHandle.jsonValue()); // prints body's innerHTML
1757 | await aHandle.dispose();
1758 | await resultHandle.dispose();
1759 | ```
1760 | 
1761 | #### executionContext.queryObjects(prototypeHandle)
1762 | - `prototypeHandle` <[JSHandle]> A handle to the object prototype.
1763 | - returns: <[JSHandle]> A handle to an array of objects with this prototype
1764 | 
1765 | The method iterates JavaScript heap and finds all the objects with the given prototype.
1766 | 
1767 | ```js
1768 | // Create a Map object
1769 | await page.evaluate(() => window.map = new Map());
1770 | // Get a handle to the Map object prototype
1771 | const mapPrototype = await page.evaluateHandle(() => Map.prototype);
1772 | // Query all map instances into an array
1773 | const mapInstances = await page.queryObjects(mapPrototype);
1774 | // Count amount of map objects in heap
1775 | const count = await page.evaluate(maps => maps.length, mapInstances);
1776 | await mapInstances.dispose();
1777 | await mapPrototype.dispose();
1778 | ```
1779 | 
1780 | ### class: JSHandle
1781 | 
1782 | JSHandle represents an in-page JavaScript object. JSHandles can be created with the [page.evaluateHandle](#pageevaluatehandlepagefunction-args) method.
1783 | 
1784 | ```js
1785 | const windowHandle = await page.evaluateHandle(() => window);
1786 | // ...
1787 | ```
1788 | 
1789 | JSHandle prevents references JavaScript objects from garbage collection unless the handle is [disposed](#jshandledispose). JSHandles are auto-disposed when their origin frame gets navigated or the parent context gets destroyed.
1790 | 
1791 | JSHandle instances can be used as arguments in [`page.$eval()`](#pageevalselector-pagefunction-args), [`page.evaluate()`](#pageevaluatepagefunction-args) and [`page.evaluateHandle`](#pageevaluatehandlepagefunction-args) methods.
1792 | 
1793 | #### jsHandle.asElement()
1794 | - returns: <?[ElementHandle]>
1795 | 
1796 | Returns either `null` or the object handle itself, if the object handle is an instance of [ElementHandle].
1797 | 
1798 | #### jsHandle.dispose()
1799 | - returns: <[Promise]> Promise which resolves when the object handle is successfully disposed.
1800 | 
1801 | The `jsHandle.dispose` method stops referencing the element handle.
1802 | 
1803 | #### jsHandle.executionContext()
1804 | - returns: [ExecutionContext]
1805 | 
1806 | Returns execution context the handle belongs to.
1807 | 
1808 | #### jsHandle.getProperties()
1809 | - returns: <[Promise]<[Map]<[string], [JSHandle]>>>
1810 | 
1811 | The method returns a map with property names as keys and JSHandle instances for the property values.
1812 | 
1813 | ```js
1814 | const handle = await page.evaluateHandle(() => ({window, document}));
1815 | const properties = await handle.getProperties();
1816 | const windowHandle = properties.get('window');
1817 | const documentHandle = properties.get('document');
1818 | await handle.dispose();
1819 | ```
1820 | 
1821 | #### jsHandle.getProperty(propertyName)
1822 | - `propertyName` <[string]> property to get
1823 | - returns: <[Promise]<[JSHandle]>>
1824 | 
1825 | Fetches a single property from the referenced object.
1826 | 
1827 | #### jsHandle.jsonValue()
1828 | - returns: <[Promise]<[Object]>>
1829 | 
1830 | Returns a JSON representation of the object. If the object has a
1831 | [`toJSON`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#toJSON()_behavior)
1832 | function, it **will not be called**.
1833 | 
1834 | > **NOTE** The method will return an empty JSON if the referenced object is not stringifiable. It will throw an error if the object has circular references.
1835 | 
1836 | ### class: ElementHandle
1837 | 
1838 | > **NOTE** Class [ElementHandle] extends [JSHandle].
1839 | 
1840 | ElementHandle represents an in-page DOM element. ElementHandles can be created with the [page.$](#pageselector) method.
1841 | 
1842 | ```js
1843 | const puppeteer = require('puppeteer');
1844 | 
1845 | puppeteer.launch().then(async browser => {
1846 |   const page = await browser.newPage();
1847 |   await page.goto('https://google.com');
1848 |   const inputElement = await page.$('input[type=submit]');
1849 |   await inputElement.click();
1850 |   // ...
1851 | });
1852 | ```
1853 | 
1854 | ElementHandle prevents DOM element from garbage collection unless the handle is [disposed](#elementhandledispose). ElementHandles are auto-disposed when their origin frame gets navigated.
1855 | 
1856 | ElementHandle instances can be used as arguments in [`page.$eval()`](#pageevalselector-pagefunction-args) and [`page.evaluate()`](#pageevaluatepagefunction-args) methods.
1857 | 
1858 | #### elementHandle.$(selector)
1859 | - `selector` <[string]> A [selector] to query element for
1860 | - returns: <[Promise]<?[ElementHandle]>>
1861 | 
1862 | The method runs `element.querySelector` within the page. If no element matches the selector, the return value resolve to `null`.
1863 | 
1864 | #### elementHandle.$$(selector)
1865 | - `selector` <[string]> A [selector] to query element for
1866 | - returns: <[Promise]<[Array]<[ElementHandle]>>>
1867 | 
1868 | The method runs `element.querySelectorAll` within the page. If no elements match the selector, the return value resolve to `[]`.
1869 | 
1870 | #### elementHandle.$x(expression)
1871 | - `expression` <[string]> Expression to [evaluate](https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate).
1872 | - returns: <[Promise]<?[ElementHandle]>> Promise which resolves to ElementHandle pointing to the frame element.
1873 | 
1874 | The method evluates the XPath expression relative to the elementHandle. If there's no such element, the method will resolve to `null`.
1875 | 
1876 | #### elementHandle.asElement()
1877 | - returns: <[elementhandle]>
1878 | 
1879 | #### elementHandle.boundingBox()
1880 | - returns: <[Promise]<?[Object]>>
1881 |     - x <[number]> the x coordinate of the element in pixels.
1882 |     - y <[number]> the y coordinate of the element in pixels.
1883 |     - width <[number]> the width of the element in pixels.
1884 |     - height <[number]> the height of the element in pixels.
1885 | 
1886 | This method returns the bounding box of the element (relative to the main frame), or `null` if the element is not visible.
1887 | 
1888 | #### elementHandle.click([options])
1889 | - `options` <[Object]>
1890 |   - `button` <[string]> `left`, `right`, or `middle`, defaults to `left`.
1891 |   - `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
1892 |   - `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
1893 | - returns: <[Promise]> Promise which resolves when the element is successfully clicked. Promise gets rejected if the element is detached from DOM.
1894 | 
1895 | This method scrolls element into view if needed, and then uses [page.mouse](#pagemouse) to click in the center of the element.
1896 | If the element is detached from DOM, the method throws an error.
1897 | 
1898 | #### elementHandle.dispose()
1899 | - returns: <[Promise]> Promise which resolves when the element handle is successfully disposed.
1900 | 
1901 | The `elementHandle.dispose` method stops referencing the element handle.
1902 | 
1903 | #### elementHandle.executionContext()
1904 | - returns: [ExecutionContext]
1905 | 
1906 | #### elementHandle.focus()
1907 | - returns: <[Promise]>
1908 | 
1909 | Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
1910 | 
1911 | #### elementHandle.getProperties()
1912 | - returns: <[Promise]<[Map]<[string], [JSHandle]>>>
1913 | 
1914 | The method returns a map with property names as keys and JSHandle instances for the property values.
1915 | 
1916 | ```js
1917 | const listHandle = await page.evaluateHandle(() => document.body.children);
1918 | const properties = await listHandle.getProperties();
1919 | const children = [];
1920 | for (const property of properties.values()) {
1921 |   const element = property.asElement();
1922 |   if (element)
1923 |     children.push(element);
1924 | }
1925 | children; // holds elementHandles to all children of document.body
1926 | ```
1927 | 
1928 | #### elementHandle.getProperty(propertyName)
1929 | - `propertyName` <[string]> property to get
1930 | - returns: <[Promise]<[JSHandle]>>
1931 | 
1932 | Fetches a single property from the objectHandle.
1933 | 
1934 | #### elementHandle.hover()
1935 | - returns: <[Promise]> Promise which resolves when the element is successfully hovered.
1936 | 
1937 | This method scrolls element into view if needed, and then uses [page.mouse](#pagemouse) to hover over the center of the element.
1938 | If the element is detached from DOM, the method throws an error.
1939 | 
1940 | #### elementHandle.jsonValue()
1941 | - returns: <[Promise]<[Object]>>
1942 | 
1943 | Returns a JSON representation of the object. The JSON is generated by running [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) on the object in page and consequent [`JSON.parse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) in puppeteer.
1944 | 
1945 | > **NOTE** The method will throw if the referenced object is not stringifiable.
1946 | 
1947 | #### elementHandle.press(key[, options])
1948 | - `key` <[string]> Name of key to press, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names.
1949 | - `options` <[Object]>
1950 |   - `text` <[string]> If specified, generates an input event with this text.
1951 |   - `delay` <[number]> Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
1952 | - returns: <[Promise]>
1953 | 
1954 | Focuses the element, and then uses [`keyboard.down`](#keyboarddownkey-options) and [`keyboard.up`](#keyboardupkey).
1955 | 
1956 | If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also be generated. The `text` option can be specified to force an input event to be generated.
1957 | 
1958 | > **NOTE** Modifier keys DO effect `elementHandle.press`. Holding down `Shift` will type the text in upper case.
1959 | 
1960 | #### elementHandle.screenshot([options])
1961 | - `options` <[Object]> Same options as in [page.screenshot](#pagescreenshotoptions).
1962 | - returns: <[Promise]<[Buffer]>> Promise which resolves to buffer with captured screenshot.
1963 | 
1964 | This method scrolls element into view if needed, and then uses [page.screenshot](#pagescreenshotoptions) to take a screenshot of the element.
1965 | If the element is detached from DOM, the method throws an error.
1966 | 
1967 | #### elementHandle.tap()
1968 | - returns: <[Promise]> Promise which resolves when the element is successfully tapped. Promise gets rejected if the element is detached from DOM.
1969 | 
1970 | This method scrolls element into view if needed, and then uses [touchscreen.tap](#touchscreentapx-y) to tap in the center of the element.
1971 | If the element is detached from DOM, the method throws an error.
1972 | 
1973 | #### elementHandle.toString()
1974 | - returns: <[string]>
1975 | 
1976 | #### elementHandle.type(text[, options])
1977 | - `text` <[string]> A text to type into a focused element.
1978 | - `options` <[Object]>
1979 |   - `delay` <[number]> Time to wait between key presses in milliseconds. Defaults to 0.
1980 | - returns: <[Promise]>
1981 | 
1982 | Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
1983 | 
1984 | To press a special key, like `Control` or `ArrowDown`, use [`elementHandle.press`](#elementhandlepresskey-options).
1985 | 
1986 | ```js
1987 | elementHandle.type('Hello'); // Types instantly
1988 | elementHandle.type('World', {delay: 100}); // Types slower, like a user
1989 | ```
1990 | 
1991 | An example of typing into a text field and then submitting the form:
1992 | ```js
1993 | const elementHandle = await page.$('input');
1994 | await elementHandle.type('some text');
1995 | await elementHandle.press('Enter');
1996 | ```
1997 | 
1998 | #### elementHandle.uploadFile(...filePaths)
1999 | - `...filePaths` <...[string]> Sets the value of the file input these paths. If some of the  `filePaths` are relative paths, then they are resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
2000 | - returns: <[Promise]>
2001 | 
2002 | This method expects `elementHandle` to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
2003 | 
2004 | ### class: Request
2005 | 
2006 | Whenever the page sends a request, the following events are emitted by puppeteer's page:
2007 | - ['request'](#event-request) emitted when the request is issued by the page.
2008 | - ['response'](#event-response) emitted when/if the response is received for the request.
2009 | - ['requestfinished'](#event-requestfinished) emitted when the response body is downloaded and the request is complete.
2010 | 
2011 | If request fails at some point, then instead of 'requestfinished' event (and possibly instead of 'response' event), the  ['requestfailed'](#event-requestfailed) event is emitted.
2012 | 
2013 | If request gets a 'redirect' response, the request is successfully finished with the 'requestfinished' event, and a new request is  issued to a redirected url.
2014 | 
2015 | #### request.abort([errorCode])
2016 | - `errorCode` <[string]> Optional error code. Defaults to `failed`, could be
2017 |   one of the following:
2018 |   - `aborted` - An operation was aborted (due to user action)
2019 |   - `accessdenied` - Permission to access a resource, other than the network, was denied
2020 |   - `addressunreachable` - The IP address is unreachable. This usually means
2021 |     that there is no route to the specified host or network.
2022 |   - `connectionaborted` - A connection timed out as a result of not receiving an ACK for data sent.
2023 |   - `connectionclosed` - A connection was closed (corresponding to a TCP FIN).
2024 |   - `connectionfailed` - A connection attempt failed.
2025 |   - `connectionrefused` - A connection attempt was refused.
2026 |   - `connectionreset` - A connection was reset (corresponding to a TCP RST).
2027 |   - `internetdisconnected` - The Internet connection has been lost.
2028 |   - `namenotresolved` - The host name could not be resolved.
2029 |   - `timedout` - An operation timed out.
2030 |   - `failed` - A generic failure occurred.
2031 | - returns: <[Promise]>
2032 | 
2033 | Aborts request. To use this, request interception should be enabled with `page.setRequestInterception`.
2034 | Exception is immediately thrown if the request interception is not enabled.
2035 | 
2036 | #### request.continue([overrides])
2037 | - `overrides` <[Object]> Optional request overwrites, which can be one of the following:
2038 |   - `url` <[string]> If set, the request url will be changed
2039 |   - `method` <[string]> If set changes the request method (e.g. `GET` or `POST`)
2040 |   - `postData` <[string]> If set changes the post data of request
2041 |   - `headers` <[Object]> If set changes the request HTTP headers
2042 | - returns: <[Promise]>
2043 | 
2044 | Continues request with optional request overrides. To use this, request interception should be enabled with `page.setRequestInterception`.
2045 | Exception is immediately thrown if the request interception is not enabled.
2046 | 
2047 | #### request.failure()
2048 | - returns: <?[Object]> Object describing request failure, if any
2049 |   - `errorText` <[string]> Human-readable error message, e.g. `'net::ERR_FAILED'`.
2050 | 
2051 | The method returns `null` unless this request was failed, as reported by
2052 | `requestfailed` event.
2053 | 
2054 | Example of logging all failed requests:
2055 | 
2056 | ```js
2057 | page.on('requestfailed', request => {
2058 |   console.log(request.url + ' ' + request.failure().errorText);
2059 | });
2060 | ```
2061 | 
2062 | #### request.headers()
2063 | - returns: <[Object]> An object with HTTP headers associated with the request. All header names are lower-case.
2064 | 
2065 | #### request.method()
2066 | - returns: <[string]> Request's method (GET, POST, etc.)
2067 | 
2068 | #### request.postData()
2069 | - returns: <[string]> Request's post body, if any.
2070 | 
2071 | #### request.resourceType()
2072 | - returns: <[string]>
2073 | 
2074 | Contains the request's resource type as it was perceived by the rendering engine.
2075 | ResourceType will be one of the following: `document`, `stylesheet`, `image`, `media`, `font`, `script`, `texttrack`, `xhr`, `fetch`, `eventsource`, `websocket`, `manifest`, `other`.
2076 | 
2077 | #### request.respond(response)
2078 | - `response` <[Object]> Response that will fulfill this request
2079 |   - `status` <[number]> Response status code, defaults to `200`.
2080 |   - `headers` <[Object]> Optional response headers
2081 |   - `contentType` <[string]> If set, equals to setting `Content-Type` response header
2082 |   - `body` <[Buffer]|[string]> Optional response body
2083 | - returns: <[Promise]>
2084 | 
2085 | Fulfills request with given response. To use this, request interception should
2086 | be enabled with `page.setRequestInterception`. Exception is thrown if
2087 | request interception is not enabled.
2088 | 
2089 | An example of fulfilling all requests with 404 responses:
2090 | 
2091 | ```js
2092 | await page.setRequestInterception(true);
2093 | page.on('request', request => {
2094 |   request.respond({
2095 |     status: 404,
2096 |     contentType: 'text/plain',
2097 |     body: 'Not Found!'
2098 |   });
2099 | });
2100 | ```
2101 | 
2102 | > **NOTE** Mocking responses for dataURL requests is not supported.
2103 | > Calling `request.respond` for a dataURL request is a noop.
2104 | 
2105 | #### request.response()
2106 | - returns: <?[Response]> A matching [Response] object, or `null` if the response has not been received yet.
2107 | 
2108 | #### request.url()
2109 | - returns: <[string]> URL of the request.
2110 | 
2111 | ### class: Response
2112 | 
2113 | [Response] class represents responses which are received by page.
2114 | 
2115 | #### response.buffer()
2116 | - returns: <Promise<[Buffer]>> Promise which resolves to a buffer with response body.
2117 | 
2118 | #### response.headers()
2119 | - returns: <[Object]> An object with HTTP headers associated with the response. All header names are lower-case.
2120 | 
2121 | #### response.json()
2122 | - returns: <Promise<[Object]>> Promise which resolves to a JSON representation of response body.
2123 | 
2124 | This method will throw if the response body is not parsable via `JSON.parse`.
2125 | 
2126 | #### response.ok()
2127 | - returns: <[boolean]>
2128 | 
2129 | Contains a boolean stating whether the response was successful (status in the range 200-299) or not.
2130 | 
2131 | #### response.request()
2132 | - returns: <[Request]> A matching [Request] object.
2133 | 
2134 | #### response.status()
2135 | - returns: <[number]>
2136 | 
2137 | Contains the status code of the response (e.g., 200 for a success).
2138 | 
2139 | #### response.text()
2140 | - returns: <[Promise]<[string]>> Promise which resolves to a text representation of response body.
2141 | 
2142 | #### response.url()
2143 | - returns: <[string]>
2144 | 
2145 | Contains the URL of the response.
2146 | 
2147 | ### class: Target
2148 | 
2149 | #### target.page()
2150 | - returns: <[Promise]<?[Page]>>
2151 | 
2152 | If the target is not of type `"page"`, returns `null`.
2153 | 
2154 | #### target.type()
2155 | - returns: <[string]>
2156 | 
2157 | Identifies what kind of target this is. Can be `"page"`, `"service_worker"`, or `"other"`.
2158 | 
2159 | #### target.url()
2160 | - returns: <[string]>
2161 | 
2162 | ### class: Coverage
2163 | 
2164 | Coverage gathers information about parts of JavaScript and CSS that were used by the page.
2165 | 
2166 | An example of using JavaScript and CSS coverage to get percentage of initially
2167 | executed code:
2168 | 
2169 | ```js
2170 | // Enable both JavaScript and CSS coverage
2171 | await Promise.all([
2172 |   page.startJSCoverage(),
2173 |   page.startCSSCoverage()
2174 | ]);
2175 | // Navigate to page
2176 | await page.goto('https://example.com');
2177 | // Disable both JavaScript and CSS coverage
2178 | const [jsCoverage, cssCoverage] = await Promise.all([
2179 |   page.stopJSCoverage(),
2180 |   page.stopCSSCoverage(),
2181 | ]);
2182 | let totalBytes = 0;
2183 | let usedBytes = 0;
2184 | const coverage = [].concat(jsCoverage, cssCoverage);
2185 | for (const entry of coverage) {
2186 |   totalBytes += entry.text.length;
2187 |   for (const range of entry.ranges)
2188 |     usedBytes += range.end - range.start - 1;
2189 | }
2190 | console.log(`Bytes used: ${usedBytes / totalBytes * 100}%`);
2191 | ```
2192 | 
2193 | #### coverage.startCSSCoverage(options)
2194 | - `options` <[Object]>  Set of configurable options for coverage
2195 |   - `resetOnNavigation` <[boolean]> Whether to reset coverage on every navigation. Defaults to `true`.
2196 | - returns: <[Promise]> Promise that resolves when coverage is started
2197 | 
2198 | #### coverage.startJSCoverage(options)
2199 | - `options` <[Object]>  Set of configurable options for coverage
2200 |   - `resetOnNavigation` <[boolean]> Whether to reset coverage on every navigation. Defaults to `true`.
2201 | - returns: <[Promise]> Promise that resolves when coverage is started
2202 | 
2203 | #### coverage.stopCSSCoverage()
2204 | - returns: <[Promise]<[Array]<[Object]>>> Promise that resolves to the array of coverage reports for all stylesheets
2205 |   - `url` <[string]> StyleSheet URL
2206 |   - `text` <[string]> StyleSheet content
2207 |   - `ranges` <[Array]<[Object]>> StyleSheet ranges that were used. Ranges are sorted and non-overlapping.
2208 |     - `start` <[number]> A start offset in text, inclusive
2209 |     - `end` <[number]> An end offset in text, exclusive
2210 | 
2211 | > **NOTE** CSS Coverage doesn't include dynamically injected style tags without sourceURLs.
2212 | 
2213 | 
2214 | #### coverage.stopJSCoverage()
2215 | - returns: <[Promise]<[Array]<[Object]>>> Promise that resolves to the array of coverage reports for all non-anonymous scripts
2216 |   - `url` <[string]> Script URL
2217 |   - `text` <[string]> Script content
2218 |   - `ranges` <[Array]<[Object]>> Script ranges that were executed. Ranges are sorted and non-overlapping.
2219 |     - `start` <[number]> A start offset in text, inclusive
2220 |     - `end` <[number]> An end offset in text, exclusive
2221 | 
2222 | > **NOTE** JavaScript Coverage doesn't include anonymous scripts; however, scripts with sourceURLs are
2223 | reported.
2224 | 
2225 | 
2226 | [Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
2227 | [boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean"
2228 | [Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
2229 | [function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function "Function"
2230 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number"
2231 | [Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
2232 | [Page]: #class-page "Page"
2233 | [Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
2234 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String"
2235 | [stream.Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "stream.Readable"
2236 | [Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
2237 | [Frame]: #class-frame "Frame"
2238 | [ConsoleMessage]: #class-consolemessage "ConsoleMessage"
2239 | [ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
2240 | [Coverage]: #class-coverage "Coverage"
2241 | [iterator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols "Iterator"
2242 | [Response]: #class-response  "Response"
2243 | [Request]: #class-request  "Request"
2244 | [Browser]: #class-browser  "Browser"
2245 | [Body]: #class-body  "Body"
2246 | [Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
2247 | [Keyboard]: #class-keyboard "Keyboard"
2248 | [Dialog]: #class-dialog  "Dialog"
2249 | [JSHandle]: #class-jshandle "JSHandle"
2250 | [ExecutionContext]: #class-executioncontext "ExecutionContext"
2251 | [Mouse]: #class-mouse "Mouse"
2252 | [Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
2253 | [selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
2254 | [Tracing]: #class-tracing "Tracing"
2255 | [ElementHandle]: #class-elementhandle "ElementHandle"
2256 | [UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
2257 | [Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
2258 | [Touchscreen]: #class-touchscreen "Touchscreen"
2259 | [Target]: #class-target "Target"
2260 | [USKeyboardLayout]: ../lib/USKeyboardLayout.js "USKeyboardLayout"
2261 | 


--------------------------------------------------------------------------------