docs: document electron api (#5229)

docs/src/api/class-dialog.md

@@ -1,4 +1,3 @@
-
 # class: Dialog
 
 [Dialog] objects are dispatched by page via the [`event: Page.dialog`] event.

docs/src/api/class-electron.md

@@ -0,0 +1,76 @@
+# class: Electron
+* langs: js
+
+Playwright has **experimental** support for Electron automation. You can access electron namespace via:
+
+```js
+const { _electron } = require('playwright');
+```
+
+An example of the Electron automation script would be:
+
+```js
+const { _electron: electron } = require('playwright');
+
+(async () => {
+  // Launch Electron app.
+  const electronApp = await electron.launch({ args: ['main.js'] });
+
+  // Evaluation expression in the Electron context.
+  const appPath = await electronApp.evaluate(async (electron) => {
+    // This runs in the main Electron process, |electron| parameter
+    // here is always the result of the require('electron') in the main
+    // app script.
+    return electron.getAppPath();
+  });
+
+  // Get the first window that the app opens, wait if necessary.
+  const window = await electronApp.firstWindow();
+  // Print the title.
+  console.log(await window.title());
+  // Capture a screenshot.
+  await window.screenshot({ path: 'intro.png' });
+  // Direct Electron console to Node terminal.
+  window.on('console', console.log);
+  // Click button.
+  await window.click('text=Click me');
+})();
+```
+
+Note that since you don't need Playwright to install web browsers when testing Electron, you can omit browser download via setting the following environment variable when installing Playwright:
+
+```sh js
+$ PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm i -D playwright
+```
+
+## async method: Electron.launch
+- returns: <[ElectronApplication]>
+
+Launches electron application specified with the [`option: executablePath`].
+
+### option: Electron.launch.executablePath
+- `executablePath` <[string]>
+
+Launches given Electron application. If not specified, launches the default Electron
+executable installed in this package, located at `node_modules/.bin/electron`.
+
+### option: Electron.launch.args
+- `args` <[Array]<[string]>>
+
+Additional arguments to pass to the application when launching. You typically pass the main
+script name here.
+
+### option: Electron.launch.cwd
+- `cwd` <[string]>
+
+Current working directory to launch application from.
+
+### option: Electron.launch.env
+- `env` <[Object]<[string], [string]>>
+
+Specifies environment variables that will be visible to Electron. Defaults to `process.env`.
+
+#### option: Electron.launch.timeout
+- `timeout` <[float]>
+
+Maximum time in milliseconds to wait for the application to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.

docs/src/api/class-electronapplication.md

@@ -0,0 +1,129 @@
+# class: ElectronApplication
+* langs: js
+
+Electron application representation. You can use [`method: Electron.launch`] to
+obtain the application instance. This instance you can control main electron process
+as well as work with Electron windows:
+
+```js
+const { _electron: electron } = require('playwright');
+
+(async () => {
+  // Launch Electron app.
+  const electronApp = await electron.launch({ args: ['main.js'] });
+
+  // Evaluation expression in the Electron context.
+  const appPath = await electronApp.evaluate(async (electron) => {
+    // This runs in the main Electron process, |electron| parameter
+    // here is always the result of the require('electron') in the main
+    // app script.
+    return electron.getAppPath();
+  });
+
+  // Get the first window that the app opens, wait if necessary.
+  const window = await electronApp.firstWindow();
+  // Print the title.
+  console.log(await window.title());
+  // Capture a screenshot.
+  await window.screenshot({ path: 'intro.png' });
+  // Direct Electron console to Node terminal.
+  window.on('console', console.log);
+  // Click button.
+  await window.click('text=Click me');
+})();
+```
+
+## event: ElectronApplication.close
+
+This event is issued when the application closes.
+
+## event: ElectronApplication.window
+- type: <[Page]>
+
+This event is issued for every window that is created **and loaded** in Electron. It contains a [Page] that can
+be used for Playwright automation.
+
+## async method: ElectronApplication.close
+
+Closes Electron application.
+
+## method: ElectronApplication.context
+- type: <[BrowserContext]>
+
+This method returns browser context that can be used for setting up context-wide routing, etc.
+
+## async method: ElectronApplication.evaluate
+- returns: <[Serializable]>
+
+Returns the return value of [`param: expression`].
+
+If the function passed to the [`method: ElectronApplication.evaluate`] returns a [Promise], then
+[`method: ElectronApplication.evaluate`] would wait for the promise to resolve and return its value.
+
+If the function passed to the [`method: ElectronApplication.evaluate`] returns a non-[Serializable] value, then
+[`method: ElectronApplication.evaluate`] returns `undefined`. Playwright also supports transferring
+some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`.
+
+### param: ElectronApplication.evaluate.expression = %%-evaluate-expression-%%
+
+### param: ElectronApplication.evaluate.arg
+- `arg` <[EvaluationArgument]>
+
+Optional argument to pass to [`param: expression`].
+
+## async method: ElectronApplication.evaluateHandle
+- returns: <[JSHandle]>
+
+Returns the return value of [`param: expression`] as a [JSHandle].
+
+The only difference between [`method: ElectronApplication.evaluate`] and [`method: ElectronApplication.evaluateHandle`] is that [`method: ElectronApplication.evaluateHandle`] returns [JSHandle].
+
+If the function passed to the [`method: ElectronApplication.evaluateHandle`] returns a [Promise], then
+[`method: ElectronApplication.evaluateHandle`] would wait for the promise to resolve and return its value.
+
+### param: ElectronApplication.evaluateHandle.expression = %%-evaluate-expression-%%
+
+### param: ElectronApplication.evaluateHandle.arg
+- `arg` <[EvaluationArgument]>
+
+## async method: ElectronApplication.firstWindow
+- returns: <[Page]>
+
+Convenience method that waits for the first application window to be opened.
+Typically your script will start with:
+
+```js
+  const electronApp = await electron.launch({
+    args: ['main.js']
+  });
+  const window = await electronApp.firstWindow();
+  // ...
+```
+
+## async method: ElectronApplication.waitForEvent
+- returns: <[any]>
+
+Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy value. Will throw an error if the application is closed before the event is fired. Returns the event data value.
+
+```js
+const [window] = await Promise.all([
+  electronApp.waitForEvent('window'),
+  mainWindow.click('button')
+]);
+```
+
+### param: ElectronApplication.waitForEvent.event = %%-wait-for-event-event-%%
+
+### param: ElectronApplication.waitForEvent.optionsOrPredicate
+* langs: js
+- `optionsOrPredicate` <[function]|[Object]>
+  - `predicate` <[function]> receives the event data and resolves to truthy value when the waiting should resolve.
+  - `timeout` <[float]> 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 [`method: BrowserContext.setDefaultTimeout`].
+
+Either a predicate that receives an event or an options object. Optional.
+
+## method: ElectronApplication.windows
+- returns: <[Array]<[Page]>>
+
+Convenience method that returns all the opened windows.

docs/src/api/class-elementhandle.md

@@ -247,7 +247,7 @@ Optional event-specific initialization properties.
   - alias-js: $eval
 - returns: <[Serializable]>
 
-Returns the return value of [`param: expression`]
+Returns the return value of [`param: expression`].
 
 The method finds an element matching the specified selector in the `ElementHandle`s subtree and passes it as a first
 argument to [`param: expression`]. See [Working with selectors](./selectors.md) for more
@@ -291,7 +291,7 @@ Optional argument to pass to [`param: expression`]
   - alias-js: $$eval
 - returns: <[Serializable]>
 
-Returns the return value of [`param: expression`]
+Returns the return value of [`param: expression`].
 
 The method finds all elements matching the specified selector in the `ElementHandle`'s subtree and passes an array of
 matched elements as a first argument to [`param: expression`]. See

docs/src/api/class-frame.md

@@ -300,7 +300,7 @@ Optional event-specific initialization properties.
   - alias-js: $eval
 - returns: <[Serializable]>
 
-Returns the return value of [`param: expression`]
+Returns the return value of [`param: expression`].
 
 The method finds an element matching the specified selector within the frame and passes it as a first argument to
 [`param: expression`]. See [Working with selectors](./selectors.md) for more details. If no
@@ -344,7 +344,7 @@ Optional argument to pass to [`param: expression`]
   - alias-js: $$eval
 - returns: <[Serializable]>
 
-Returns the return value of [`param: expression`]
+Returns the return value of [`param: expression`].
 
 The method finds all elements matching the specified selector within the frame and passes an array of matched elements
 as a first argument to [`param: expression`]. See [Working with selectors](./selectors.md) for
@@ -379,14 +379,14 @@ Optional argument to pass to [`param: expression`]
 ## async method: Frame.evaluate
 - returns: <[Serializable]>
 
-Returns the return value of [`param: expression`]
+Returns the return value of [`param: expression`].
 
 If the function passed to the [`method: Frame.evaluate`] returns a [Promise], then [`method: Frame.evaluate`] would wait for the promise to
 resolve and return its value.
 
 If the function passed to the [`method: Frame.evaluate`] returns a non-[Serializable] value, then
-[`method: Frame.evaluate`] returns `undefined`. DevTools Protocol also supports transferring some additional values that
-are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
+[`method: Frame.evaluate`] returns `undefined`. Playwright also supports transferring some 
+additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`.
 
 ```js
 const result = await frame.evaluate(([x, y]) => {
@@ -455,10 +455,10 @@ Optional argument to pass to [`param: expression`]
 ## async method: Frame.evaluateHandle
 - returns: <[JSHandle]>
 
-Returns the return value of [`param: expression`] as in-page object (JSHandle).
+Returns the return value of [`param: expression`] as a [JSHandle].
 
 The only difference between [`method: Frame.evaluate`] and [`method: Frame.evaluateHandle`] is that
-[method: Frame.evaluateHandle`] returns in-page object (JSHandle).
+[method: Frame.evaluateHandle`] returns [JSHandle].
 
 If the function, passed to the [`method: Frame.evaluateHandle`], returns a [Promise], then
 [`method: Frame.evaluateHandle`] would wait for the promise to resolve and return its value.

docs/src/api/class-jshandle.md

@@ -37,7 +37,7 @@ The `jsHandle.dispose` method stops referencing the element handle.
 ## async method: JSHandle.evaluate
 - returns: <[Serializable]>
 
-Returns the return value of [`param: expression`]
+Returns the return value of [`param: expression`].
 
 This method passes this handle as the first argument to [`param: expression`].
 
@@ -71,12 +71,11 @@ Optional argument to pass to [`param: expression`]
 ## async method: JSHandle.evaluateHandle
 - returns: <[JSHandle]>
 
-Returns the return value of [`param: expression`] as in-page object (JSHandle).
+Returns the return value of [`param: expression`] as a [JSHandle].
 
 This method passes this handle as the first argument to [`param: expression`].
 
-The only difference between `jsHandle.evaluate` and `jsHandle.evaluateHandle` is that `jsHandle.evaluateHandle` returns
-in-page object (JSHandle).
+The only difference between `jsHandle.evaluate` and `jsHandle.evaluateHandle` is that `jsHandle.evaluateHandle` returns [JSHandle].
 
 If the function passed to the `jsHandle.evaluateHandle` returns a [Promise], then `jsHandle.evaluateHandle` would wait
 for the promise to resolve and return its value.

docs/src/api/class-page.md

@@ -808,8 +808,8 @@ If the function passed to the [`method: Page.evaluate`] returns a [Promise], the
 for the promise to resolve and return its value.
 
 If the function passed to the [`method: Page.evaluate`] returns a non-[Serializable] value, then
-[`method: Page.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.
+[`method: Page.evaluate`] resolves to `undefined`. Playwright also supports transferring some 
+additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`.
 
 Passing argument to [`param: expression`]:
 
@@ -882,10 +882,9 @@ Optional argument to pass to [`param: expression`]
 ## async method: Page.evaluateHandle
 - returns: <[JSHandle]>
 
-Returns the value of the [`param: expression`] invocation as in-page object (JSHandle).
+Returns the value of the [`param: expression`] invocation as a [JSHandle].
 
-The only difference between [`method: Page.evaluate`] and [`method: Page.evaluateHandle`] is that [`method: Page.evaluateHandle`] returns in-page
-object (JSHandle).
+The only difference between [`method: Page.evaluate`] and [`method: Page.evaluateHandle`] is that [`method: Page.evaluateHandle`] returns [JSHandle].
 
 If the function passed to the [`method: Page.evaluateHandle`] returns a [Promise], then [`method: Page.evaluateHandle`] would wait for the
 promise to resolve and return its value.

docs/src/api/class-worker.md

@@ -35,14 +35,13 @@ Emitted when this dedicated [WebWorker](https://developer.mozilla.org/en-US/docs
 ## async method: Worker.evaluate
 - returns: <[Serializable]>
 
-Returns the return value of [`param: expression`]
+Returns the return value of [`param: expression`].
 
-If the function passed to the `worker.evaluate` returns a [Promise], then `worker.evaluate` would wait for the promise
+If the function passed to the [`method: Worker.evaluate`] returns a [Promise], then [`method: 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` returns
-`undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`:
-`-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
+If the function passed to the [`method: Worker.evaluate`] returns a non-[Serializable] value, then [`method: Worker.evaluate`] returns `undefined`. Playwright also supports transferring some 
+additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`.
 
 ### param: Worker.evaluate.expression = %%-evaluate-expression-%%
 
@@ -54,12 +53,13 @@ Optional argument to pass to [`param: expression`]
 ## async method: Worker.evaluateHandle
 - returns: <[JSHandle]>
 
-Returns the return value of [`param: expression`] as in-page object (JSHandle).
+Returns the return value of [`param: expression`] as a [JSHandle].
 
-The only difference between `worker.evaluate` and `worker.evaluateHandle` is that `worker.evaluateHandle` returns
-in-page object (JSHandle).
+The only difference between [`method: Worker.evaluate`] and
+[`method: Worker.evaluateHandle`] is that [`method: Worker.evaluateHandle`] 
+returns [JSHandle].
 
-If the function passed to the `worker.evaluateHandle` returns a [Promise], then `worker.evaluateHandle` would wait for
+If the function passed to the [`method: Worker.evaluateHandle`] returns a [Promise], then [`method: Worker.evaluateHandle`] would wait for
 the promise to resolve and return its value.
 
 ### param: Worker.evaluateHandle.expression = %%-evaluate-expression-%%

docs/src/api/javascript.md

@@ -14,3 +14,5 @@
 ### param: Page.waitForFunction.expression = %%-js-evaluate-pagefunction-%%
 ### param: Worker.evaluate.expression = %%-js-worker-evaluate-workerfunction-%%
 ### param: Worker.evaluateHandle.expression = %%-js-worker-evaluate-workerfunction-%%
+### param: ElectronApplication.evaluate.expression = %%-js-electron-evaluate-workerfunction-%%
+### param: ElectronApplication.evaluateHandle.expression = %%-js-electron-evaluate-workerfunction-%%