(feat): support function execution in main process (#254)

* (feat): support function execution in main process

* fix unit tests

* warn any rather than throw

* prettier fix

.editorconfig

@@ -0,0 +1,14 @@
+# EditorConfig helps developers define and maintain consistent
+# coding styles between different editors and IDEs
+# editorconfig.org
+
+root = true
+
+[*]
+
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

@types/wdio-electron-service/index.d.ts

@@ -1,4 +1,5 @@
 export type WdioElectronWindowObj = {
+  execute: (script: string, args: unknown[]) => any;
   [Key: string]: {
     invoke: (...args: unknown[]) => Promise<unknown>;
   };

README.md

@@ -123,6 +123,28 @@ import { browser } from 'wdio-electron-service';
 const appName = await browser.electron.app('getName');
 ```
 
+### Execute Electron Scripts
+
+You can execute arbitrary scripts within the context of your Electron application main process using `browser.electron.execute(...)`. This allows you to potentially change the behavior of your application at runtime or trigger certain events.
+
+For example you can trigger an message modal from your test via:
+
+```ts
+await browser.electron.execute((electron, param1, param2, param3) => {
+  const appWindow = electron.BrowserWindow.getFocusedWindow();
+  electron.dialog.showMessageBox(appWindow, {
+    message: 'Hello World!',
+    detail: `${param1} + ${param2} + ${param3} = ${param1 + param2 + param3}`
+  });
+}, 1, 2, 3)
+```
+
+which will make the application trigger the following alert:
+
+![Execute Demo](./.github/assets/execute-demo.png "Execute Demo")
+
+__Note:__ The first argument of the function will be always the default export of the `electron` package that contains the [Electron API](https://www.electronjs.org/docs/latest/api/app).
+
 ### 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:
@@ -212,7 +234,7 @@ Type: `string[]`
 
 The browser command used to access the custom electron API.
 
-Type: `string`  
+Type: `string`
 Default: `'api'`
 
 ## Chromedriver configuration

eslint.config.js

@@ -82,6 +82,7 @@ export default [
           destructuredArrayIgnorePattern: '^_',
         },
       ],
+      '@typescript-eslint/no-explicit-any': ['warn'],
     },
   },
   // Example app TS files

example-cjs/e2e/api.spec.ts

@@ -62,4 +62,22 @@ describe('electron APIs', () => {
       expect(result).toEqual('I opened a dialog!');
     });
   });
+
+  describe('execute', () => {
+    it('should allow to execute an arbitrary function in the main process', async () => {
+      expect(
+        await browser.electron.execute(
+          (electron, a, b, c) => {
+            const win = electron.BrowserWindow.getFocusedWindow();
+            return [typeof win, a + b + c];
+          },
+          1,
+          2,
+          3,
+        ),
+      ).toEqual(['object', 6]);
+
+      expect(await browser.electron.execute('return 1 + 2 + 3')).toBe(6);
+    });
+  });
 });