Merge pull request #521 from webdriverio-community/sm/standalone-utility

(feat): session utility

.github/workflows/ci.yml

@@ -14,31 +14,35 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macOS-latest]
-        node-version: [16.x]
+        node-version: [18.x]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
       - name: Cache pnpm modules
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         env:
           cache-name: cache-pnpm-modules
         with:
           path: ~/.pnpm-store
           key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ matrix.node-version }}-${{ hashFiles('**/pnpm-lock.yaml') }}
           restore-keys: |
             ${{ runner.os }}-build-${{ env.cache-name }}-${{ matrix.node-version }}-
-      - uses: pnpm/action-setup@v2
+      - uses: pnpm/action-setup@v3
         with:
-          version: 8.10.0
+          version: 9.0.6
           run_install: false
-      - name: Run headless test
-        uses: coactions/setup-xvfb@v1.0.1
-        with:
-          run: pnpm run ci
+      - name: Run Tests
+        run: |
+          if [ "$RUNNER_OS" == "Linux" ]; then
+          xvfb-run pnpm run ci
+          else
+          pnpm run ci
+          fi
+        shell: bash
       - name: 🐛 Debug Build
         uses: stateful/vscode-server-action@v1
         if: failure()

.github/workflows/expense.yml

@@ -40,7 +40,7 @@ jobs:
   authorize:
     runs-on: ubuntu-latest
     steps:
-      - uses: octokit/request-action@v2.1.9
+      - uses: octokit/request-action@v2.x
         with:
           route: GET /orgs/:organisation/teams/:team/memberships/${{ github.actor }}
           team: technical-steering-committee

.github/workflows/release.yml

@@ -32,16 +32,16 @@ jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           ref: 'main'
           fetch-depth: 0
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v4
         with:
-          node-version: 16.x
-      - uses: pnpm/action-setup@v2
+          node-version: 18.x
+      - uses: pnpm/action-setup@v3
         with:
-          version: 8.10.0
+          version: 9.0.6
           run_install: false
       - name: NPM Setup
         run: |

README.md

@@ -82,6 +82,7 @@ export const config = {
 **[Chromedriver Configuration](./docs/configuration/chromedriver-configuration.md)** \
 **[Accessing Electron APIs](./docs/electron-apis/accessing-apis.md)** \
 **[Mocking Electron APIs](./docs/electron-apis/mocking-apis.md)** \
+**[Standalone Mode](./docs/standalone-mode.md)** \
 **[Development](./docs/development.md)** \
 **[Common Issues](./docs/common-issues.md)**
 

docs/standalone-mode.md

@@ -0,0 +1,16 @@
+# Standalone Mode
+
+You can also use the service without the WDIO testrunner, e.g. in a normal Node.js script.
+
+The `startElectron` method accepts [`ElectronServiceOptions`](./configuration/service-configuration.md#service-options), creates a new WDIO session using your configuration and returns the WebdriverIO browser object:
+
+```TS
+import { startElectron } from 'wdio-electron-service';
+
+const browser = await startElectron({
+  appBinaryPath: '/path/to/binary',
+  appArgs: ['foo', 'bar=baz'],
+});
+
+const appName = await browser.electron.execute((electron) => electron.app.getName());
+```

example-cjs/e2e-multiremote/api.spec.ts

@@ -0,0 +1,22 @@
+import { browser } from 'wdio-electron-service';
+import { multiremotebrowser, expect } from '@wdio/globals';
+
+const { name, version } = globalThis.packageJson;
+
+describe('Electron APIs using Multiremote', () => {
+  it('should retrieve app metadata through the electron API', async () => {
+    const appName = await browser.electron.execute((electron) => electron.app.getName());
+    expect(appName).toStrictEqual([name, name]);
+    const appVersion = await browser.electron.execute((electron) => electron.app.getVersion());
+    expect(appVersion).toStrictEqual([version, version]);
+  });
+
+  it('should retrieve instance-specific values from a single instance', async () => {
+    const browserA = multiremotebrowser.getInstance('browserA');
+    expect(await browserA.electron.execute(() => process.argv.includes('--browser=A'))).toBe(true);
+    expect(await browserA.electron.execute(() => process.argv.includes('--browser=B'))).toBe(false);
+    const browserB = multiremotebrowser.getInstance('browserB');
+    expect(await browserB.electron.execute(() => process.argv.includes('--browser=A'))).toBe(false);
+    expect(await browserB.electron.execute(() => process.argv.includes('--browser=B'))).toBe(true);
+  });
+});

example-cjs/e2e-standalone/api.spec.ts

@@ -0,0 +1,50 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import process from 'node:process';
+
+import { startElectron } from 'wdio-electron-service';
+import type { PackageJson } from 'read-package-up';
+
+process.env.TEST = 'true';
+
+const PACKAGE_NAME = 'wdio-electron-service-example-cjs';
+const packageJson = JSON.parse(
+  fs.readFileSync(path.join(__dirname, '..', 'package.json'), { encoding: 'utf-8' }),
+) as PackageJson;
+
+const getBinaryExtension = () => {
+  if (process.platform === 'darwin') {
+    return `.app/Contents/MacOS/${PACKAGE_NAME}`;
+  } else if (process.platform === 'win32') {
+    return '.exe';
+  }
+
+  return '';
+};
+
+const getBinaryPath = () =>
+  `./out/${PACKAGE_NAME}-${process.platform}-${process.arch}/${PACKAGE_NAME}${getBinaryExtension()}`;
+
+async function init() {
+  const browser = await startElectron({
+    appBinaryPath: getBinaryPath(),
+    appArgs: ['foo', 'bar=baz'],
+  });
+
+  const appName = await browser.electron.execute((electron) => electron.app.getName());
+  if (appName !== packageJson.name) {
+    throw new Error(`appName test failed: ${appName} !== ${packageJson.name}`);
+  }
+
+  const appVersion = await browser.electron.execute((electron) => electron.app.getVersion());
+  if (appVersion !== packageJson.version) {
+    throw new Error(`appVersion test failed: ${appVersion} !== ${packageJson.version}`);
+  }
+
+  // Clean up - quit the app
+  await browser.deleteSession();
+
+  process.exit();
+}
+
+init();

example-cjs/package.json

@@ -9,7 +9,9 @@
     "ci": "pnpm i && pnpm build && pnpm test",
     "clean": "pnpm clean:dist && rm -rf ./node_modules pnpm-lock.yaml ./wdio-logs ./out",
     "clean:dist": "pnpx rimraf ./dist && mkdir -p ./dist",
-    "test": "wdio run ./wdio.conf.ts"
+    "test": "wdio run ./wdio.conf.ts && pnpm test:multiremote && pnpm test:standalone",
+    "test:multiremote": "wdio run ./wdio.multiremote.conf.ts",
+    "test:standalone": "tsx ./e2e-standalone/api.spec.ts"
   },
   "dependencies": {
     "wdio-electron-service": "file:../"
@@ -21,11 +23,12 @@
     "@wdio/globals": "^8.27.2",
     "@wdio/local-runner": "^8.27.2",
     "@wdio/mocha-framework": "^8.27.2",
-    "electron": "^29.0.1",
+    "electron": "^29.3.1",
     "global-jsdom": "^24.0.0",
     "jsdom": "^24.0.0",
     "ts-loader": "^9.4.4",
     "ts-node": "^10.9.1",
+    "tsx": "^4.8.2",
     "typescript": "^5.3.2",
     "webdriverio": "^8.27.2"
   },