From 7611f002d477718485c31492555f187223a2405f Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Tue, 3 Oct 2023 15:05:22 -0700 Subject: [PATCH 01/10] docs: Updated docs on testing Electron using WebdriverIO --- docs/tutorial/automated-testing.md | 101 +++++++++++++++++++++++++---- 1 file changed, 90 insertions(+), 11 deletions(-) diff --git a/docs/tutorial/automated-testing.md b/docs/tutorial/automated-testing.md index 40b7e9c17f009..cdc2f3d704f40 100644 --- a/docs/tutorial/automated-testing.md +++ b/docs/tutorial/automated-testing.md @@ -27,29 +27,102 @@ Node.js package for testing with WebDriver. Its ecosystem also includes various First you need to run the WebdriverIO starter toolkit in your project root directory: ```sh npm2yarn -npx wdio . --yes +npm init wdio@latest ./ ``` -This installs all necessary packages for you and generates a `wdio.conf.js` configuration file. +This starts a configuration wizard that helps you put together the right setup, installs all necessary packages for you and generates a `wdio.conf.js` configuration file. Make sure to select _"Desktop Testing - of Electron Applications"_ on one of the first questions asking _"What type of testing would you like to do?"_. #### Connect WDIO to your Electron app -Update the capabilities in your configuration file to point to your Electron app binary: +After the configuration wizard finished running your `wdio.conf.js` will look as following: -```javascript title='wdio.conf.js' -exports.config = { +```js title='wdio.conf.js' @ts-nocheck +import fs from 'node:fs' +import url from 'node:url' +import path from 'node:path' + +import { getBinaryPath } from 'wdio-electron-service/utils' + +const __dirname = path.dirname(url.fileURLToPath(import.meta.url)) +const packageJson = JSON.parse(fs.readFileSync('./package.json').toString()) + +export const config = { // ... - capabilities: [{ - browserName: 'chrome', - 'goog:chromeOptions': { - binary: '/path/to/your/electron/binary', // Path to your Electron binary. - args: [/* cli arguments */] // Optional, perhaps 'app=' + /path/to/your/app/ + services: ['electron'], + capabilities: [ + { + browserName: 'electron', + 'wdio:electronServiceOptions': { + appBinaryPath: getBinaryPath(__dirname, productName), + appArgs: ['foo', 'bar=baz'] + } } - }] + ] // ... } ``` +#### Write your tests + +To interacting with elements on the screen you can use the [WebdriverIO API](https://webdriver.io/docs/api) that helps you to write concise and expressive tests. The framework provides custom "matchers" that make asserting the state of your application easy, e.g.: + +```js @ts-nocheck +import { browser, $, expect } from '@wdio/globals' + +describe('keyboard input', () => { + it('should detect keyboard input', async () => { + await browser.keys(['y', 'o']) + await expect($('keypress-count')).toHaveText('YO') + }) +}) +``` + +Furthermore WebdriverIO allows you to access Electron APIs to get static information about your application: + +```js @ts-nocheck +import { browser, $, expect } from '@wdio/globals' + +describe('when the make smaller button is clicked', () => { + it('should decrease the window height and width by 10 pixels', async () => { + const boundsBefore = await browser.electron.browserWindow('getBounds') + expect(boundsBefore.width).toEqual(210) + expect(boundsBefore.height).toEqual(310) + + await $('.make-smaller').click() + const boundsAfter = await browser.electron.browserWindow('getBounds') + expect(boundsAfter.width).toEqual(200) + expect(boundsAfter.height).toEqual(300) + }) +}) +``` + +or to retrieve other Electron process information: + +```js @ts-nocheck +import fs from 'node:fs' +import path from 'node:path' +import { browser, expect } from '@wdio/globals' + +const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), { encoding: 'utf-8' })) +const { name, version } = packageJson + +describe('electron APIs', () => { + it('should retrieve app metadata through the electron API', async () => { + const appName = await browser.electron.app('getName') + expect(appName).toEqual(name) + const appVersion = await browser.electron.app('getVersion') + expect(appVersion).toEqual(version) + }) + + it('should pass args through to the launched application', async () => { + // custom args are set in the wdio.conf.js file as they need to be set before WDIO starts + const argv = await browser.electron.mainProcess('argv') + expect(argv).toContain('--foo') + expect(argv).toContain('--bar=baz') + }) +}) +``` + #### Run your tests To run your tests: @@ -58,6 +131,12 @@ To run your tests: $ npx wdio run wdio.conf.js ``` +WebdriverIO helps managing to launch and shut down the application for you. + +#### More Documentation + +Find more documentation on Mocking Electron APIs and other useful resources in the [official WebdriverIO documentation](https://webdriver.io/docs/desktop-testing/electron). + ### With Selenium [Selenium](https://www.selenium.dev/) is a web automation framework that From 4158b30f3a2a434a3c746883bc46a24a94776aa7 Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Wed, 4 Oct 2023 09:31:46 -0700 Subject: [PATCH 02/10] Update docs/tutorial/automated-testing.md Co-authored-by: Felix Rieseberg --- docs/tutorial/automated-testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/automated-testing.md b/docs/tutorial/automated-testing.md index cdc2f3d704f40..b08d906f5a1fa 100644 --- a/docs/tutorial/automated-testing.md +++ b/docs/tutorial/automated-testing.md @@ -30,7 +30,7 @@ First you need to run the WebdriverIO starter toolkit in your project root direc npm init wdio@latest ./ ``` -This starts a configuration wizard that helps you put together the right setup, installs all necessary packages for you and generates a `wdio.conf.js` configuration file. Make sure to select _"Desktop Testing - of Electron Applications"_ on one of the first questions asking _"What type of testing would you like to do?"_. +This starts a configuration wizard that helps you put together the right setup, installs all necessary packages, and generates a `wdio.conf.js` configuration file. Make sure to select _"Desktop Testing - of Electron Applications"_ on one of the first questions asking _"What type of testing would you like to do?"_. #### Connect WDIO to your Electron app From d4d338932193fa1906ad9d570e6c4ec2663b0791 Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Wed, 4 Oct 2023 09:32:26 -0700 Subject: [PATCH 03/10] Update docs/tutorial/automated-testing.md Co-authored-by: Felix Rieseberg --- docs/tutorial/automated-testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/automated-testing.md b/docs/tutorial/automated-testing.md index b08d906f5a1fa..6c6ca5f9ce31e 100644 --- a/docs/tutorial/automated-testing.md +++ b/docs/tutorial/automated-testing.md @@ -34,7 +34,7 @@ This starts a configuration wizard that helps you put together the right setup, #### Connect WDIO to your Electron app -After the configuration wizard finished running your `wdio.conf.js` will look as following: +After the configuration wizard finished running your `wdio.conf.js` should include roughly the following content: ```js title='wdio.conf.js' @ts-nocheck import fs from 'node:fs' From 8162aa83663da91173de3bc6e7bea46fb989ae1a Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Thu, 12 Oct 2023 16:09:21 -0700 Subject: [PATCH 04/10] more updates --- docs/tutorial/automated-testing.md | 26 +++++++++----------------- 1 file changed, 9 insertions(+), 17 deletions(-) diff --git a/docs/tutorial/automated-testing.md b/docs/tutorial/automated-testing.md index 6c6ca5f9ce31e..3d8117f8e0c0c 100644 --- a/docs/tutorial/automated-testing.md +++ b/docs/tutorial/automated-testing.md @@ -37,27 +37,19 @@ This starts a configuration wizard that helps you put together the right setup, After the configuration wizard finished running your `wdio.conf.js` should include roughly the following content: ```js title='wdio.conf.js' @ts-nocheck -import fs from 'node:fs' -import url from 'node:url' -import path from 'node:path' - -import { getBinaryPath } from 'wdio-electron-service/utils' - -const __dirname = path.dirname(url.fileURLToPath(import.meta.url)) -const packageJson = JSON.parse(fs.readFileSync('./package.json').toString()) - export const config = { // ... services: ['electron'], - capabilities: [ - { - browserName: 'electron', - 'wdio:electronServiceOptions': { - appBinaryPath: getBinaryPath(__dirname, productName), - appArgs: ['foo', 'bar=baz'] - } + capabilities: [{ + browserName: 'electron', + 'wdio:electronServiceOptions': { + // WebdriverIO can automatically find your bundled application + // if you use Electron Forge or electron-builder, otherwise you + // can define it here, e.g.: + // appBinaryPath: './path/to/bundled/application.exe', + appArgs: ['foo', 'bar=baz'] } - ] + }] // ... } ``` From a9849acd2604fcefaf2820e5ecee405f37c6bc48 Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Mon, 16 Oct 2023 11:29:11 -0700 Subject: [PATCH 05/10] address PR comments --- docs/tutorial/automated-testing.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/tutorial/automated-testing.md b/docs/tutorial/automated-testing.md index 3d8117f8e0c0c..a247fcd2903fe 100644 --- a/docs/tutorial/automated-testing.md +++ b/docs/tutorial/automated-testing.md @@ -22,9 +22,11 @@ There are a few ways that you can set up testing using WebDriver. Node.js package for testing with WebDriver. Its ecosystem also includes various plugins (e.g. reporter and services) that can help you put together your test setup. +If you already have an existing WebdriverIO setup, it is recommended to update your dependencies and validate your existing configuration with how it is [outlined in the docs](https://webdriver.io/docs/desktop-testing/electron#configuration). + #### Install the test runner -First you need to run the WebdriverIO starter toolkit in your project root directory: +If you don't use WebdriverIO in your project yet, you can add it by running the starter toolkit in your project root directory: ```sh npm2yarn npm init wdio@latest ./ From b49a3dfa0e31f4ebca20b2aa2a55890d91e83c26 Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Mon, 16 Oct 2023 11:30:32 -0700 Subject: [PATCH 06/10] Update docs/tutorial/automated-testing.md Co-authored-by: Erick Zhao --- docs/tutorial/automated-testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/automated-testing.md b/docs/tutorial/automated-testing.md index a247fcd2903fe..4b58cae7ddbb1 100644 --- a/docs/tutorial/automated-testing.md +++ b/docs/tutorial/automated-testing.md @@ -125,7 +125,7 @@ To run your tests: $ npx wdio run wdio.conf.js ``` -WebdriverIO helps managing to launch and shut down the application for you. +WebdriverIO helps launch and shut down the application for you. #### More Documentation From 7840047f2918dccbc690ef5ef9e2d511c2919ca8 Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Mon, 16 Oct 2023 11:30:41 -0700 Subject: [PATCH 07/10] Update docs/tutorial/automated-testing.md Co-authored-by: Erick Zhao --- docs/tutorial/automated-testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/automated-testing.md b/docs/tutorial/automated-testing.md index 4b58cae7ddbb1..8490c34b6c8ea 100644 --- a/docs/tutorial/automated-testing.md +++ b/docs/tutorial/automated-testing.md @@ -36,7 +36,7 @@ This starts a configuration wizard that helps you put together the right setup, #### Connect WDIO to your Electron app -After the configuration wizard finished running your `wdio.conf.js` should include roughly the following content: +After running the configuration wizard, your `wdio.conf.js` should include roughly the following content: ```js title='wdio.conf.js' @ts-nocheck export const config = { From ba359cc3e40f33ed1c25eea9657bcf476c9edb59 Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Mon, 16 Oct 2023 11:30:49 -0700 Subject: [PATCH 08/10] Update docs/tutorial/automated-testing.md Co-authored-by: Erick Zhao --- docs/tutorial/automated-testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/automated-testing.md b/docs/tutorial/automated-testing.md index 8490c34b6c8ea..85c5a816ac674 100644 --- a/docs/tutorial/automated-testing.md +++ b/docs/tutorial/automated-testing.md @@ -127,7 +127,7 @@ $ npx wdio run wdio.conf.js WebdriverIO helps launch and shut down the application for you. -#### More Documentation +#### More documentation Find more documentation on Mocking Electron APIs and other useful resources in the [official WebdriverIO documentation](https://webdriver.io/docs/desktop-testing/electron). From df9d312f29d0fb9e47e61162491fbd24a99824e7 Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Mon, 16 Oct 2023 11:30:54 -0700 Subject: [PATCH 09/10] Update docs/tutorial/automated-testing.md Co-authored-by: Erick Zhao --- docs/tutorial/automated-testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/automated-testing.md b/docs/tutorial/automated-testing.md index 85c5a816ac674..f97bc3062c8e3 100644 --- a/docs/tutorial/automated-testing.md +++ b/docs/tutorial/automated-testing.md @@ -71,7 +71,7 @@ describe('keyboard input', () => { }) ``` -Furthermore WebdriverIO allows you to access Electron APIs to get static information about your application: +Furthermore, WebdriverIO allows you to access Electron APIs to get static information about your application: ```js @ts-nocheck import { browser, $, expect } from '@wdio/globals' From c269bfa802c7dce97a88c64f32a9476232115488 Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Mon, 16 Oct 2023 11:31:01 -0700 Subject: [PATCH 10/10] Update docs/tutorial/automated-testing.md Co-authored-by: Erick Zhao --- docs/tutorial/automated-testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/automated-testing.md b/docs/tutorial/automated-testing.md index f97bc3062c8e3..5f5c5d76ec01f 100644 --- a/docs/tutorial/automated-testing.md +++ b/docs/tutorial/automated-testing.md @@ -58,7 +58,7 @@ export const config = { #### Write your tests -To interacting with elements on the screen you can use the [WebdriverIO API](https://webdriver.io/docs/api) that helps you to write concise and expressive tests. The framework provides custom "matchers" that make asserting the state of your application easy, e.g.: +Use the [WebdriverIO API](https://webdriver.io/docs/api) to interact with elements on the screen. The framework provides custom "matchers" that make asserting the state of your application easy, e.g.: ```js @ts-nocheck import { browser, $, expect } from '@wdio/globals'