docs: update for new mocking

webdriverio-community · Dec 1, 2023 · 5b3f4cf · 5b3f4cf
1 parent c2808f1
commit 5b3f4cf
Show file tree

Hide file tree

Showing 3 changed files with 81 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -139,12 +139,62 @@ which will make the application trigger the following alert:
 
 ### Mocking Electron APIs
 
-You can mock Electron API functionality by calling the mock function with the API name, function name and mock return value. e.g. in a spec file:
+You can mock Electron API functionality by calling the mock function with the API name and function name. e.g. in a spec file:
 
 ```ts
-await browser.electron.mock('dialog', 'showOpenDialog', 'dialog opened!');
-const result = await browser.electron.dialog('showOpenDialog');
-console.log(result); // 'dialog opened!'
+const showOpenDialog = await browser.electron.mock('dialog', 'showOpenDialog');
+await browser.electron.execute(
+  async (electron) =>
+    await electron.dialog.showOpenDialog({
+      properties: ['openFile', 'openDirectory'],
+    }),
+);
+
+const mockedShowOpenDialog = await showOpenDialog.update();
+expect(mockedShowOpenDialog).toHaveBeenCalledTimes(1);
+expect(mockedShowOpenDialog).toHaveBeenCalledWith({
+  properties: ['openFile', 'openDirectory'],
+});
+```
+
+Make sure to call `update()` on the mock before using it with `expect`.
+
+You can also pass a mockReturnValue, or set it after defining your mock:
+
+```ts
+const showOpenDialog = await browser.electron.mock('dialog', 'showOpenDialog', 'I opened a dialog!');
+```
+
+```ts
+const showOpenDialog = await browser.electron.mock('dialog', 'showOpenDialog');
+await showOpenDialog.mockReturnValue('I opened a dialog!');
+```
+
+Which results in the following:
+
+```ts
+const result = await browser.electron.execute(async (electron) => await electron.dialog.showOpenDialog());
+expect(result).toBe('I opened a dialog!');
+```
+
+You can mock all functions from an API using `mockAll`, the mocks are returned as an object:
+
+```ts
+const dialog = await browser.electron.mockAll('dialog');
+await dialog.showOpenDialog.mockReturnValue('I opened a dialog!');
+await dialog.showMessageBox.mockReturnValue('I opened a message box!');
+```
+
+Mocks can be removed by calling `removeMocks`, or directly by calling `unMock` on the mock itself:
+
+```ts
+// removes all mocked functions
+await browser.electron.removeMocks();
+// removes all mocked functions from the dialog API
+await browser.electron.removeMocks('dialog');
+// removes the showOpenDialog mock from the dialog API
+const showOpenDialog = await browser.electron.mock('dialog', 'showOpenDialog');
+await showOpenDialog.unMock();
 ```
 
 ## Example

diff --git a/src/index.ts b/src/index.ts
@@ -17,7 +17,10 @@ export interface BrowserExtension {
   /**
    * Access the WebdriverIO Electron Service API.
    *
-   * - {@link ElectronServiceAPI.mock `browser.electron.mock`} - Mock a function from the Electron API.
+   * - {@link ElectronServiceAPI.execute `browser.electron.execute`} - Execute code in the Electron main process context
+   * - {@link ElectronServiceAPI.mock `browser.electron.mock`} - Mock a function from the Electron API, e.g. `dialog.showOpenDialog`
+   * - {@link ElectronServiceAPI.mockAll `browser.electron.mockAll`} - Mock an entire API object of the Electron API, e.g. `app` or `dialog`
+   * - {@link ElectronServiceAPI.removeMocks `browser.electron.removeMocks`} - Remove mock functions from the Electron API
    */
   electron: ElectronServiceAPI;
 }

diff --git a/src/types.ts b/src/types.ts
@@ -35,10 +35,20 @@ export interface ElectronServiceAPI {
    *
    * @example
    * ```js
-   * // mock the app's getName function
-   * await browser.electron.mock('dialog', 'showOpenDialog', 'I opened a dialog!');
-   * const result = await browser.electron.dialog('showOpenDialog');
-   * expect(result).toEqual('I opened a dialog!');
+   * // mock the dialog API showOpenDialog method
+   * const showOpenDialog = await browser.electron.mock('dialog', 'showOpenDialog');
+   * await browser.electron.execute(
+   *   async (electron) =>
+   *     await electron.dialog.showOpenDialog({
+   *       properties: ['openFile', 'openDirectory'],
+   *     }),
+   * );
+   *
+   * const mockedShowOpenDialog = await showOpenDialog.update();
+   * expect(mockedShowOpenDialog).toHaveBeenCalledTimes(1);
+   * expect(mockedShowOpenDialog).toHaveBeenCalledWith({
+   *   properties: ['openFile', 'openDirectory'],
+   * });
    * ```
    */
   mock: <Interface extends ElectronInterface>(
@@ -53,10 +63,12 @@ export interface ElectronServiceAPI {
    *
    * @example
    * ```js
-   * // mock the app's getName function
-   * await browser.electron.mockAll('dialog');
-   * const result = await browser.electron.dialog('showOpenDialog');
-   * expect(result).toEqual('I opened a dialog!');
+   * // mock multiple functions from the app API
+   * const app = await browser.electron.mockAll('app');
+   * await app.getName.mockReturnValue('mocked-app');
+   * await app.getVersion.mockReturnValue('1.0.0-mocked.12');
+   * const result = await browser.electron.execute((electron) => `${electron.app.getName()}::${electron.app.getVersion()}`);
+   * expect(result).toEqual('mocked-app::1.0.0-mocked.12');
    * ```
    */
   mockAll: <Interface extends ElectronInterface>(apiName: Interface) => Promise<Record<string, WrappedMockFn>>;
@@ -86,13 +98,13 @@ export interface ElectronServiceAPI {
    *
    * @example
    * ```js
-   * // clears all mocked functions
+   * // removes all mocked functions
    * await browser.electron.removeMocks()
-   * // clears all mocked functions of dialog API
+   * // removes all mocked functions of dialog API
    * await browser.electron.removeMocks('dialog')
    * ```
    *
-   * @param apiName mocked api to clear
+   * @param apiName mocked api to remove
    */
   removeMocks: (apiName?: string) => Promise<void>;
 }