diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index 587bcba13b3fb..84ce8b832a403 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -35,7 +35,7 @@ | [TimeoutError](./puppeteer.timeouterror.md) | | | [Touchscreen](./puppeteer.touchscreen.md) | | | [Tracing](./puppeteer.tracing.md) | | -| [WebWorker](./puppeteer.webworker.md) | | +| [WebWorker](./puppeteer.webworker.md) | The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | ## Enumerations diff --git a/new-docs/puppeteer.webworker._constructor_.md b/new-docs/puppeteer.webworker._constructor_.md deleted file mode 100644 index 503a1e75e5ae6..0000000000000 --- a/new-docs/puppeteer.webworker._constructor_.md +++ /dev/null @@ -1,23 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [WebWorker](./puppeteer.webworker.md) > [(constructor)](./puppeteer.webworker._constructor_.md) - -## WebWorker.(constructor) - -Constructs a new instance of the `WebWorker` class - -Signature: - -```typescript -constructor(client: CDPSession, url: string, consoleAPICalled: ConsoleAPICalledCallback, exceptionThrown: ExceptionThrownCallback); -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| client | [CDPSession](./puppeteer.cdpsession.md) | | -| url | string | | -| consoleAPICalled | ConsoleAPICalledCallback | | -| exceptionThrown | ExceptionThrownCallback | | - diff --git a/new-docs/puppeteer.webworker.evaluate.md b/new-docs/puppeteer.webworker.evaluate.md index aa9774ee1d8de..5a0334d2a7153 100644 --- a/new-docs/puppeteer.webworker.evaluate.md +++ b/new-docs/puppeteer.webworker.evaluate.md @@ -4,6 +4,8 @@ ## WebWorker.evaluate() method +If the function passed to the `worker.evaluate` returns a Promise, then `worker.evaluate` would wait for the promise to resolve and return its value. If the function passed to the `worker.evaluate` returns a non-serializable value, then `worker.evaluate` resolves to `undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals. Shortcut for `await worker.executionContext()).evaluate(pageFunction, ...args)`. + Signature: ```typescript @@ -14,10 +16,12 @@ evaluate(pageFunction: Function | string, ...args: any[] | Parameter | Type | Description | | --- | --- | --- | -| pageFunction | Function \| string | | -| args | any\[\] | | +| pageFunction | Function \| string | Function to be evaluated in the worker context. | +| args | any\[\] | Arguments to pass to pageFunction. | Returns: Promise<ReturnType> +Promise which resolves to the return value of `pageFunction`. + diff --git a/new-docs/puppeteer.webworker.evaluatehandle.md b/new-docs/puppeteer.webworker.evaluatehandle.md index d882d863d6328..8482842f8ca00 100644 --- a/new-docs/puppeteer.webworker.evaluatehandle.md +++ b/new-docs/puppeteer.webworker.evaluatehandle.md @@ -4,6 +4,8 @@ ## WebWorker.evaluateHandle() method +The only difference between `worker.evaluate` and `worker.evaluateHandle` is that `worker.evaluateHandle` returns in-page object (JSHandle). If the function passed to the `worker.evaluateHandle` returns a \[Promise\], then `worker.evaluateHandle` would wait for the promise to resolve and return its value. Shortcut for \[(await worker.executionContext()).evaluateHandle(pageFunction, ...args)\](\#executioncontextevaluatehandlepagefunction-args). + Signature: ```typescript @@ -14,10 +16,12 @@ evaluateHandle(pageFunction: Function | string, ...args: any[]): PromisepageFunction. | Returns: Promise<[JSHandle](./puppeteer.jshandle.md)> +Promise which resolves to the return value of `pageFunction`. + diff --git a/new-docs/puppeteer.webworker.executioncontext.md b/new-docs/puppeteer.webworker.executioncontext.md index e798b2827eaaf..3cac964e50d76 100644 --- a/new-docs/puppeteer.webworker.executioncontext.md +++ b/new-docs/puppeteer.webworker.executioncontext.md @@ -4,6 +4,8 @@ ## WebWorker.executionContext() method +Returns the ExecutionContext the WebWorker runs in + Signature: ```typescript @@ -13,3 +15,5 @@ executionContext(): Promise; Promise<[ExecutionContext](./puppeteer.executioncontext.md)> +The ExecutionContext the web worker runs in. + diff --git a/new-docs/puppeteer.webworker.md b/new-docs/puppeteer.webworker.md index c041406b478b9..e40442961090d 100644 --- a/new-docs/puppeteer.webworker.md +++ b/new-docs/puppeteer.webworker.md @@ -4,17 +4,33 @@ ## WebWorker class +The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). + Signature: ```typescript export declare class WebWorker extends EventEmitter ``` -## Constructors +## Remarks -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(client, url, consoleAPICalled, exceptionThrown)](./puppeteer.webworker._constructor_.md) | | Constructs a new instance of the WebWorker class | +The events `workercreated` and `workerdestroyed` are emitted on the page object to signal the worker lifecycle. + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `WebWorker` class. + +## Example + + +```js +page.on('workercreated', worker => console.log('Worker created: ' + worker.url())); +page.on('workerdestroyed', worker => console.log('Worker destroyed: ' + worker.url())); + +console.log('Current workers:'); +for (const worker of page.workers()) { + console.log(' ' + worker.url()); +} + +``` ## Properties @@ -29,8 +45,8 @@ export declare class WebWorker extends EventEmitter | Method | Modifiers | Description | | --- | --- | --- | -| [evaluate(pageFunction, args)](./puppeteer.webworker.evaluate.md) | | | -| [evaluateHandle(pageFunction, args)](./puppeteer.webworker.evaluatehandle.md) | | | -| [executionContext()](./puppeteer.webworker.executioncontext.md) | | | +| [evaluate(pageFunction, args)](./puppeteer.webworker.evaluate.md) | | If the function passed to the worker.evaluate returns a Promise, then worker.evaluate would wait for the promise to resolve and return its value. If the function passed to the worker.evaluate returns a non-serializable value, then worker.evaluate resolves to undefined. DevTools Protocol also supports transferring some additional values that are not serializable by JSON: -0, NaN, Infinity, -Infinity, and bigint literals. Shortcut for await worker.executionContext()).evaluate(pageFunction, ...args). | +| [evaluateHandle(pageFunction, args)](./puppeteer.webworker.evaluatehandle.md) | | The only difference between worker.evaluate and worker.evaluateHandle is that worker.evaluateHandle returns in-page object (JSHandle). If the function passed to the worker.evaluateHandle returns a \[Promise\], then worker.evaluateHandle would wait for the promise to resolve and return its value. Shortcut for \[(await worker.executionContext()).evaluateHandle(pageFunction, ...args)\](\#executioncontextevaluatehandlepagefunction-args). | +| [executionContext()](./puppeteer.webworker.executioncontext.md) | | Returns the ExecutionContext the WebWorker runs in | | [url()](./puppeteer.webworker.url.md) | | | diff --git a/new-docs/puppeteer.webworker.url.md b/new-docs/puppeteer.webworker.url.md index 2d458a0a981f2..83fc2b80c2a0a 100644 --- a/new-docs/puppeteer.webworker.url.md +++ b/new-docs/puppeteer.webworker.url.md @@ -13,3 +13,5 @@ url(): string; string +The URL of this web worker. + diff --git a/src/WebWorker.ts b/src/WebWorker.ts index 42f4a692a6076..9960d2e73189f 100644 --- a/src/WebWorker.ts +++ b/src/WebWorker.ts @@ -30,12 +30,35 @@ type ExceptionThrownCallback = ( ) => void; type JSHandleFactory = (obj: Protocol.Runtime.RemoteObject) => JSHandle; +/** + * The WebWorker class represents a {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API | WebWorker}. + * + * @remarks + * The events `workercreated` and `workerdestroyed` are emitted on the page object to signal the worker lifecycle. + * + * @example + * ```js + * page.on('workercreated', worker => console.log('Worker created: ' + worker.url())); + * page.on('workerdestroyed', worker => console.log('Worker destroyed: ' + worker.url())); + * + * console.log('Current workers:'); + * for (const worker of page.workers()) { + * console.log(' ' + worker.url()); + * } + * ``` + * + * @public + */ export class WebWorker extends EventEmitter { _client: CDPSession; _url: string; _executionContextPromise: Promise; _executionContextCallback: (value: ExecutionContext) => void; + /** + * + * @internal + */ constructor( client: CDPSession, url: string, @@ -76,14 +99,30 @@ export class WebWorker extends EventEmitter { ); } + /** + * @returns The URL of this web worker. + */ url(): string { return this._url; } + /** + * Returns the ExecutionContext the WebWorker runs in + * @returns The ExecutionContext the web worker runs in. + */ async executionContext(): Promise { return this._executionContextPromise; } + /** + * If the function passed to the `worker.evaluate` returns a Promise, then `worker.evaluate` would wait for the promise to resolve and return its value. + * If the function passed to the `worker.evaluate` returns a non-serializable value, then `worker.evaluate` resolves to `undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals. + * Shortcut for `await worker.executionContext()).evaluate(pageFunction, ...args)`. + * + * @param pageFunction - Function to be evaluated in the worker context. + * @param args - Arguments to pass to `pageFunction`. + * @returns Promise which resolves to the return value of `pageFunction`. + */ async evaluate( pageFunction: Function | string, ...args: any[] @@ -94,6 +133,14 @@ export class WebWorker extends EventEmitter { ); } + /** + * The only difference between `worker.evaluate` and `worker.evaluateHandle` is that `worker.evaluateHandle` returns in-page object (JSHandle). + * If the function passed to the `worker.evaluateHandle` returns a [Promise], then `worker.evaluateHandle` would wait for the promise to resolve and return its value. + * Shortcut for [(await worker.executionContext()).evaluateHandle(pageFunction, ...args)](#executioncontextevaluatehandlepagefunction-args). + * @param pageFunction - Function to be evaluated in the page context. + * @param args - Arguments to pass to `pageFunction`. + * @returns Promise which resolves to the return value of `pageFunction`. + */ async evaluateHandle( pageFunction: Function | string, ...args: any[]