Merge branch 'master' into promise-types

Author: VerteDinde

README.md

@@ -36,6 +36,9 @@ For given versions of Electron you must depend on a very specific version range
 | `^11.0.0` | `^13.0.0`|
 | `^12.0.0` | `^14.0.0`|
 | `^13.0.0` | `^15.0.0`|
+| `^14.0.0` | `^16.0.0`|
+| `^15.0.0` | `^17.0.0`|
+| `^16.0.0` | `^18.0.0`|
 
 Learn more from [this presentation](https://speakerdeck.com/kevinsawicki/testing-your-electron-apps-with-chromedriver).
 
@@ -67,15 +70,15 @@ cd test
 Then simply include the following in your first `spec.js`.
 
 ```js
-const Application = require('spectron').Application
+const { Application } = require('spectron')
 const assert = require('assert')
 const electronPath = require('electron') // Require Electron from the binaries included in node_modules.
 const path = require('path')
 
 describe('Application launch', function () {
   this.timeout(10000)
 
-  beforeEach(function () {
+  beforeEach(async function () {
     this.app = new Application({
       // Your electron path can be any binary
       // i.e for OSX an example path could be '/Applications/MyApp.app/Contents/MacOS/MyApp'
@@ -97,21 +100,20 @@ describe('Application launch', function () {
       // and the package.json located 1 level above.
       args: [path.join(__dirname, '..')]
     })
-    return this.app.start()
+    await this.app.start()
   })
 
-  afterEach(function () {
+  afterEach(async function () {
     if (this.app && this.app.isRunning()) {
-      return this.app.stop()
+      await this.app.stop()
     }
   })
 
-  it('shows an initial window', function () {
-    return this.app.client.getWindowCount().then(function (count) {
-      assert.equal(count, 1)
-      // Please note that getWindowCount() will return 2 if `dev tools` are opened.
-      // assert.equal(count, 2)
-    })
+  it('shows an initial window', async function () {
+    const count = await this.app.client.getWindowCount()
+    assert.equal(count, 1)
+    // Please note that getWindowCount() will return 2 if `dev tools` are opened.
+    // assert.equal(count, 2)
   })
 })
 ```
@@ -221,7 +223,7 @@ Spectron uses [WebdriverIO](https://webdriver.io) and exposes the managed
 `client` property on the created `Application` instances.
 
 The `client` API is WebdriverIO's `browser` object. Documentation can be found
-[here](https://webdriver.io/docs/api).
+[here](https://webdriver.io/docs/browserobject/).
 
 Several additional commands are provided specific to Electron.
 
@@ -230,11 +232,9 @@ All the commands return a `Promise`.
 So if you wanted to get the text of an element you would do:
 
 ```js
-app.client.$('#error-alert').then(function (element) {
-  element.getText().then(function (errorText) {
-    console.log('The #error-alert text content is ' + errorText)
-  })
-})
+const element = await app.client.$('#error-alert')
+const errorText = await element.getText()
+console.log('The #error-alert text content is ' + errorText)
 ```
 
 #### electron
@@ -265,9 +265,8 @@ So if you wanted to check if the current window is visible in your tests you
 would do:
 
 ```js
-app.browserWindow.isVisible().then(function (visible) {
-  console.log('window is visible? ' + visible)
-})
+const visible = await app.browserWindow.isVisible()
+console.log('window is visible? ' + visible)
 ```
 
 It is named `browserWindow` instead of `window` so that it doesn't collide
@@ -280,9 +279,8 @@ returns a `Promise` that resolves to a `Buffer` that is the image data of
 screenshot.
 
 ```js
-app.browserWindow.capturePage().then(function (imageBuffer) {
-  fs.writeFile('page.png', imageBuffer)
-})
+const imageBuffer = await app.browserWindow.capturePage()
+fs.writeFile('page.png', imageBuffer)
 ```
 
 #### webContents
@@ -308,12 +306,12 @@ returns a `Promise` that will raise any errors and resolve to `undefined` when
 complete.
 
 ```js
-app.webContents.savePage('/Users/kevin/page.html', 'HTMLComplete')
-  .then(function () {
-    console.log('page saved')
-  }).catch(function (error) {
-    console.error('saving page failed', error.message)
-  })
+try {
+  await app.webContents.savePage('/Users/kevin/page.html', 'HTMLComplete')
+  console.log('page saved')
+catch (error) {
+  console.error('saving page failed', error.message)
+}
 ```
 
 ##### executeJavaScript
@@ -322,10 +320,8 @@ returns a `Promise` that will resolve with the result of the last statement of t
 script.
 
 ```js
-app.webContents.executeJavaScript('1 + 2')
-  .then(function (result) {
-    console.log(result) // prints 3
-  })
+const result = await app.webContents.executeJavaScript('1 + 2')
+console.log(result) // prints 3
 ```
 
 #### mainProcess
@@ -339,9 +335,8 @@ So if you wanted to get the `argv` for the main process in your tests you would
 do:
 
 ```js
-app.mainProcess.argv().then(function (argv) {
-  console.log('main process args: ' + argv)
-})
+const argv = await app.mainProcess.argv()
+console.log('main process args: ' + argv)
 ```
 
 Properties on the `process` are exposed as functions that return promises so
@@ -359,9 +354,8 @@ So if you wanted to get the environment variables for the renderer process in
 your tests you would do:
 
 ```js
-app.rendererProcess.env().then(function (env) {
-  console.log('renderer process env variables: ' + env)
-})
+const env = await app.rendererProcess.env()
+console.log('renderer process env variables: ' + env)
 ```
 
 ### Methods
@@ -403,10 +397,9 @@ after they are returned.
 Returns a `Promise` that resolves to an array of string log messages
 
 ```js
-app.client.getMainProcessLogs().then(function (logs) {
-  logs.forEach(function (log) {
-    console.log(log)
-  })
+const logs = await app.client.getMainProcessLogs()
+logs.forEach(function (log) {
+  console.log(log)
 })
 ```
 
@@ -418,12 +411,11 @@ after they are returned.
 Returns a `Promise` that resolves to an array of log objects.
 
 ```js
-app.client.getRenderProcessLogs().then(function (logs) {
-  logs.forEach(function (log) {
-    console.log(log.message)
-    console.log(log.source)
-    console.log(log.level)
-  })
+const logs = await app.client.getRenderProcessLogs()
+logs.forEach(function (log) {
+  console.log(log.message)
+  console.log(log.source)
+  console.log(log.level)
 })
 ```
 
@@ -432,9 +424,8 @@ app.client.getRenderProcessLogs().then(function (logs) {
 Get the selected text in the current window.
 
 ```js
-app.client.getSelectedText().then(function (selectedText) {
-  console.log(selectedText)
-})
+const selectedText = await app.client.getSelectedText()
+console.log(selectedText)
 ```
 
 #### client.getWindowCount()
@@ -443,9 +434,8 @@ Gets the number of open windows.
 `<webview>` tags are also counted as separate windows.
 
 ```js
-app.client.getWindowCount().then(function (count) {
-  console.log(count)
-})
+const count = await app.client.getWindowCount()
+console.log(count)
 ```
 
 #### client.waitUntilTextExists(selector, text, [timeout])
@@ -517,11 +507,10 @@ Returns an `audit` Object with the following properties:
   * `url` - A String URL providing more details about the failed rule
 
 ```js
-app.client.auditAccessibility().then(function (audit) {
-  if (audit.failed) {
-    console.error(audit.message)
-  }
-})
+const audit = await app.client.auditAccessibility()
+if (audit.failed) {
+  console.error(audit.message)
+}
 ```
 
 See https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules
@@ -532,24 +521,20 @@ page and the `<webview>`'s page then you will need to do the following:
 
 ```js
 // Focus main page and audit it
-app.client.windowByIndex(0).then(function() {
-  app.client.auditAccessibility().then(function (audit) {
-    if (audit.failed) {
-      console.error('Main page failed audit')
-      console.error(audit.message)
-    }
+await app.client.windowByIndex(0)
+const audit = await app.client.auditAccessibility()
+if (audit.failed) {
+  console.error('Main page failed audit')
+  console.error(audit.message)
+}
 
-    //Focus <webview> tag and audit it
-    app.client.windowByIndex(1).then(function() {
-      app.client.auditAccessibility().then(function (audit) {
-        if (audit.failed) {
-          console.error('<webview> page failed audit')
-          console.error(audit.message)
-        }
-      })
-    })
-  })
-})
+//Focus <webview> tag and audit it
+await app.client.windowByIndex(1)
+const audit = await app.client.auditAccessibility()
+if (audit.failed) {
+  console.error('<webview> page failed audit')
+  console.error(audit.message)
+}
 ```
 
 ## Continuous Integration

lib/api.js

@@ -79,6 +79,7 @@ Api.prototype.loadApi = function () {
       );
     }
     const electron = window[requireName]('electron');
+    electron.remote = window[requireName]('@electron/remote');
     const process = window[requireName]('process');
 
     const api = {
@@ -350,9 +351,8 @@ Api.prototype.addCapturePageSupport = function () {
       async function (rect, requireName, done) {
         const args = [];
         if (rect != null) args.push(rect);
-        const browserWindow = window[requireName](
-          'electron'
-        ).remote.getCurrentWindow();
+        const browserWindow =
+          window[requireName]('@electron/remote').getCurrentWindow();
         const image = await browserWindow.capturePage.apply(
           browserWindow,
           args
@@ -413,9 +413,8 @@ Api.prototype.addSavePageSupport = function () {
   app.client.addCommand('webContents.savePage', function (fullPath, saveType) {
     return this.executeAsync(
       async function (fullPath, saveType, requireName, done) {
-        const webContents = window[requireName](
-          'electron'
-        ).remote.getCurrentWebContents();
+        const webContents =
+          window[requireName]('@electron/remote').getCurrentWebContents();
         await webContents.savePage(fullPath, saveType);
         done();
       },
@@ -445,9 +444,8 @@ Api.prototype.addExecuteJavaScriptSupport = function () {
     function (code, useGesture) {
       return this.executeAsync(
         async function (code, useGesture, requireName, done) {
-          const webContents = window[requireName](
-            'electron'
-          ).remote.getCurrentWebContents();
+          const webContents =
+            window[requireName]('@electron/remote').getCurrentWebContents();
           const result = await webContents.executeJavaScript(code, useGesture);
           done(result);
         },
@@ -538,7 +536,7 @@ function callRenderApi(moduleName, api, args, requireName) {
 }
 
 function callMainApi(moduleName, api, args, requireName) {
-  let module = window[requireName]('electron').remote;
+  let module = window[requireName]('@electron/remote');
   if (moduleName) {
     module = module[moduleName];
   }
@@ -550,16 +548,14 @@ function callMainApi(moduleName, api, args, requireName) {
 }
 
 function callWebContentsApi(name, args, requireName) {
-  const webContents = window[requireName](
-    'electron'
-  ).remote.getCurrentWebContents();
+  const webContents =
+    window[requireName]('@electron/remote').getCurrentWebContents();
   return webContents[name].apply(webContents, args);
 }
 
 function callBrowserWindowApi(name, args, requireName) {
-  const browserWindow = window[requireName](
-    'electron'
-  ).remote.getCurrentWindow();
+  const browserWindow =
+    window[requireName]('@electron/remote').getCurrentWindow();
   return browserWindow[name].apply(browserWindow, args);
 }