github/puppeteer
0
0
Fork 0
mirror of https://github.com/puppeteer/puppeteer synced 2024-06-14 14:02:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore: add more comments to page class

Browse Source
This commit is contained in:
TASNEEM KOUSHAR 2021-06-25 18:10:53 +05:30 committed by GitHub
parent e94a6b73d3
commit e5eed1efaf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 260 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

261
src/common/Page.ts
View File

@ -629,8 +629,26 @@ export class Page extends EventEmitter {
} }
/** /**
* This method is typically coupled with an action that triggers file
* choosing. The following example clicks a button that issues a file chooser
* and then responds with `/tmp/myfile.pdf` as if a user has selected this file.
*
* ```js
* const [fileChooser] = await Promise.all([
* page.waitForFileChooser(),
* page.click('#upload-file-button'),
* // some button that triggers file selection
* ]);
* await fileChooser.accept(['/tmp/myfile.pdf']);
* ```
*
* NOTE: This must be called before the file chooser is launched. It will not
* return a currently active file chooser.
* @param options - Optional waiting parameters * @param options - Optional waiting parameters
* @returns Resolves after a page requests a file picker. * @returns Resolves after a page requests a file picker.
* @remarks
* NOTE: In non-headless Chromium, this method results in the native file picker
* dialog `not showing up` for the user.
*/ */
async waitForFileChooser( async waitForFileChooser(
options: WaitTimeoutOptions = {} options: WaitTimeoutOptions = {}
@ -764,8 +782,11 @@ export class Page extends EventEmitter {
/** /**
* @returns all of the dedicated * @returns all of the dedicated
* {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API | WebWorkers} * {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API |
* WebWorkers}
* associated with the page. * associated with the page.
* @remarks
* NOTE: This does not contain ServiceWorkers
*/ */
workers(): WebWorker[] { workers(): WebWorker[] {
return Array.from(this._workers.values()); return Array.from(this._workers.values());
@ -1719,6 +1740,30 @@ export class Page extends EventEmitter {
return result[0]; return result[0];
} }
/**
* This resolves when the page navigates to a new URL or reloads. It is useful
* when you run code that will indirectly cause the page to navigate. Consider
* this example:
* ```js
* const [response] = await Promise.all([
* page.waitForNavigation(), // The promise resolves after navigation has finished
* page.click('a.my-link'), // Clicking the link will indirectly cause a navigation
* ]);
* ```
*
* @param options - Navigation parameters which might have the following properties:
* @returns Promise which resolves to the main resource response. In case of
* multiple redirects, the navigation will resolve with the response of the
* last redirect. In case of navigation to a different anchor or navigation
* due to History API usage, the navigation will resolve with `null`.
* @remarks
* NOTE: Usage of the
* {@link https://developer.mozilla.org/en-US/docs/Web/API/History_API | History API}
* to change the URL is considered a navigation.
*
* Shortcut for
* {@link Frame.waitForNavigation | page.mainFrame().waitForNavigation(options)}.
*/
async waitForNavigation( async waitForNavigation(
options: WaitForOptions = {} options: WaitForOptions = {}
): Promise<HTTPResponse | null> { ): Promise<HTTPResponse | null> {
@ -1735,6 +1780,31 @@ export class Page extends EventEmitter {
return this._disconnectPromise; return this._disconnectPromise;
} }
/**
* @param urlOrPredicate - A URL or predicate to wait for
* @param options - Optional waiting parameters
* @returns Promise which resolves to the matched response
* @example
* ```js
* const firstResponse = await page.waitForResponse(
* 'https://example.com/resource'
* );
* const finalResponse = await page.waitForResponse(
* (response) =>
* response.url() === 'https://example.com' && response.status() === 200
* );
* const finalResponse = await page.waitForResponse(async (response) => {
* return (await response.text()).includes('<html>');
* });
* return finalResponse.ok();
* ```
* @remarks
* Optional Waiting Parameters have:
*
* - `timeout`: Maximum wait time in milliseconds, defaults to `30` seconds, pass
* `0` to disable the timeout. The default value can be changed by using the
* {@link Page.setDefaultTimeout} method.
*/
async waitForRequest( async waitForRequest(
urlOrPredicate: string | ((req: HTTPRequest) => boolean | Promise<boolean>), urlOrPredicate: string | ((req: HTTPRequest) => boolean | Promise<boolean>),
options: { timeout?: number } = {} options: { timeout?: number } = {}
@ -1755,6 +1825,31 @@ export class Page extends EventEmitter {
); );
} }
/**
* @param urlOrPredicate - A URL or predicate to wait for.
* @param options - Optional waiting parameters
* @returns Promise which resolves to the matched response.
* @example
* ```js
* const firstResponse = await page.waitForResponse(
* 'https://example.com/resource'
* );
* const finalResponse = await page.waitForResponse(
* (response) =>
* response.url() === 'https://example.com' && response.status() === 200
* );
* const finalResponse = await page.waitForResponse(async (response) => {
* return (await response.text()).includes('<html>');
* });
* return finalResponse.ok();
* ```
* @remarks
* Optional Parameter have:
*
* - `timeout`: Maximum wait time in milliseconds, defaults to `30` seconds,
* pass `0` to disable the timeout. The default value can be changed by using
* the {@link Page.setDefaultTimeout} method.
*/
async waitForResponse( async waitForResponse(
urlOrPredicate: urlOrPredicate:
| string | string
@ -2611,7 +2706,7 @@ export class Page extends EventEmitter {
/** /**
* @param {!PDFOptions=} options * @param {!PDFOptions=} options
* @return {!Promise<!Buffer>} * @returns {!Promise<!Buffer>}
*/ */
async pdf(options: PDFOptions = {}): Promise<Buffer> { async pdf(options: PDFOptions = {}): Promise<Buffer> {
const { path = undefined } = options; const { path = undefined } = options;
@ -2862,6 +2957,54 @@ export class Page extends EventEmitter {
return this.mainFrame().waitForTimeout(milliseconds); return this.mainFrame().waitForTimeout(milliseconds);
} }
/**
* Wait for the `selector` to appear in page. If at the moment of calling the
* method the `selector` already exists, the method will return immediately. If
* the `selector` doesn't appear after the `timeout` milliseconds of waiting, the
* function will throw.
*
* This method works across navigations:
* ```js
* const puppeteer = require('puppeteer');
* (async () => {
* const browser = await puppeteer.launch();
* const page = await browser.newPage();
* let currentURL;
* page
* .waitForSelector('img')
* .then(() => console.log('First URL with image: ' + currentURL));
* for (currentURL of [
* 'https://example.com',
* 'https://google.com',
* 'https://bbc.com',
* ]) {
* await page.goto(currentURL);
* }
* await browser.close();
* })();
* ```
* @param selector - A
* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
* of an element to wait for
* @param options - Optional waiting parameters
* @returns Promise which resolves when element specified by selector string
* is added to DOM. Resolves to `null` if waiting for hidden: `true` and
* selector is not found in DOM.
* @remarks
* The optional Parameter in Arguments `options` are :
*
* - `Visible`: A 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`.
*
* - `hidden`: ait 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`.
*
* - `timeout`: maximum time to wait for in milliseconds. Defaults to `30000`
* (30 seconds). Pass `0` to disable timeout. The default value can be changed
* by using the {@link Page.setDefaultTimeout} method.
*/
waitForSelector( waitForSelector(
selector: string, selector: string,
options: { options: {
@ -2873,6 +3016,54 @@ export class Page extends EventEmitter {
return this.mainFrame().waitForSelector(selector, options); return this.mainFrame().waitForSelector(selector, options);
} }
/**
* Wait for the `xpath` to appear in page. If at the moment of calling the
* method the `xpath` already exists, the method will return immediately. If
* the `xpath` doesn't appear after the `timeout` milliseconds of waiting, the
* function will throw.
*
* This method works across navigation
* ```js
* const puppeteer = require('puppeteer');
* (async () => {
* const browser = await puppeteer.launch();
* const page = await browser.newPage();
* let currentURL;
* page
* .waitForXPath('//img')
* .then(() => console.log('First URL with image: ' + currentURL));
* for (currentURL of [
* 'https://example.com',
* 'https://google.com',
* 'https://bbc.com',
* ]) {
* await page.goto(currentURL);
* }
* await browser.close();
* })();
* ```
* @param xpath - A
* {@link https://developer.mozilla.org/en-US/docs/Web/XPath | xpath} of an
* element to wait for
* @param options - Optional waiting parameters
* @returns Promise which resolves when element specified by xpath string is
* added to DOM. Resolves to `null` if waiting for `hidden: true` and xpath is
* not found in DOM.
* @remarks
* The optional Argument `options` have properties:
*
* - `visible`: A boolean to 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`.
*
* - `hidden`: A 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`.
*
* - `timeout`: A number which is maximum time to wait for in milliseconds.
* Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default
* value can be changed by using the {@link Page.setDefaultTimeout} method.
*/
waitForXPath( waitForXPath(
xpath: string, xpath: string,
options: { options: {
@ -2884,6 +3075,72 @@ export class Page extends EventEmitter {
return this.mainFrame().waitForXPath(xpath, options); return this.mainFrame().waitForXPath(xpath, options);
} }
/**
* The `waitForFunction` can be used to observe viewport size change:
*
* ```
* const puppeteer = require('puppeteer');
* (async () => {
* const browser = await puppeteer.launch();
* const page = await browser.newPage();
* const watchDog = page.waitForFunction('window.innerWidth < 100');
* await page.setViewport({ width: 50, height: 50 });
* await watchDog;
* await browser.close();
* })();
* ```
* To pass arguments from node.js to the predicate of `page.waitForFunction` function:
* ```
* const selector = '.foo';
* await page.waitForFunction(
* (selector) => !!document.querySelector(selector),
* {},
* selector
* );
* ```
* The predicate of `page.waitForFunction` can be asynchronous too:
* ```
* const username = 'github-username';
* await page.waitForFunction(
* async (username) => {
* const githubResponse = await fetch(
* `https://api.github.com/users/${username}`
* );
* const githubUser = await githubResponse.json();
* // show the avatar
* const img = document.createElement('img');
* img.src = githubUser.avatar_url;
* // wait 3 seconds
* await new Promise((resolve, reject) => setTimeout(resolve, 3000));
* img.remove();
* },
* {},
* username
* );
* ```
* @param pageFunction - Function to be evaluated in browser context
* @param options - Optional waiting parameters
* @param args - Arguments to pass to `pageFunction`
* @returns Promise which resolves when the `pageFunction` returns a truthy
* value. It resolves to a JSHandle of the truthy value.
*
* The optional waiting parameter can be:
*
* - `Polling`: 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:<br/>
* - `raf`: to constantly execute `pageFunction` in `requestAnimationFrame`
* callback. This is the tightest polling mode which is suitable to
* observe styling changes.<br/>
* - `mutation`: to execute pageFunction on every DOM mutation.
*
* - `timeout`: maximum time to wait for in milliseconds. Defaults to `30000`
* (30 seconds). Pass `0` to disable timeout. The default value can be changed
* by using the
* {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)} method.
*
*/
waitForFunction( waitForFunction(
pageFunction: Function | string, pageFunction: Function | string,
options: { options: {