wdio-obsidian-service 1.3.3 → 2.0.0

package/README.md

@@ -1,37 +1,35 @@
-[![NPM](https://img.shields.io/npm/v/wdio-obsidian-service)](https://www.npmjs.com/package/wdio-obsidian-service)
-# WDIO Obsidian Service
-
-`wdio-obsidian-service` lets you test [Obsidian](https://obsidian.md) plugins end-to-end using
-[WebdriverIO](https://webdriver.io). The service can:
-- Download and install Obsidian
-- Test your plugin on different Obsidian app versions and installer/electron versions
-- Download Chromedriver matching the Obsidian electron version
-- Sandbox Obsidian so tests don't interfere with your system Obsidian installation or each other
-- Run tests in parallel
-- Open and switch between test vaults during your tests
-- Provide helper functions for common testing tasks
-- Run tests in GitHub CI
+# WDIO Obsidian Service [![NPM](https://img.shields.io/npm/v/wdio-obsidian-service)](https://www.npmjs.com/package/wdio-obsidian-service)
+
+Test your [Obsidian](https://obsidian.md) plugins end-to-end using [WebdriverIO](https://webdriver.io)!
+
+WDIO Obsidian Service can:
+- 📥 Download and test multiple versions of Obsidian
+- 💻📱 Run tests on Windows, macOS, Linux, and Android
+- 📦 Sandbox Obsidian so tests don't interfere with your system or each other
+- 📂 Open and switch between vaults
+- 🛠️ Provide helper functions for common testing tasks
+- 🤖 Run tests in GitHub CI
 
 ## Installation and Setup
-If you want to get going quickly, you can use the
-[wdio-obsidian-service sample plugin](https://github.com/jesse-r-s-hines/wdio-obsidian-service-sample-plugin) which has
-all the setup you need to build and end-to-end test Obsidian plugins, including GitHub CI workflows.
+
+If you want to get going quickly, you can use the [wdio-obsidian-service sample plugin](https://github.com/jesse-r-s-hines/wdio-obsidian-service-sample-plugin) as a template which has everything already set up to run end-to-end tests, including GitHub CI workflows.
 
 See also: [WebdriverIO | Getting Started](https://webdriver.io/docs/gettingstarted).
 
-To set up wdio-obsidian-service manually, run the WebdriverIO Starter Toolkit:
+To set up `wdio-obsidian-service` run the WebdriverIO Starter Toolkit:
 ```bash
 npm init wdio@latest .
 ```
 Leave all options as default (including `E2E Testing - of Web or Mobile Applications`).
-Delete the generated `pageobjects` dir for now, or replace it with a stub for later.
+
+Delete the generated `test/pageobjects` dir for now, or replace it with a stub for later.
 
 Then install `wdio-obsidian-service` and other deps:
 ```bash
 npm install --save-dev wdio-obsidian-service wdio-obsidian-reporter mocha @types/mocha
 ```
 
-And add this to `tsconfig.json`:
+Add this to `tsconfig.json`:
 ```json
 {
   "compilerOptions": {
@@ -45,17 +43,14 @@ And add this to `tsconfig.json`:
 }
 ```
 
-Set up your `wdio.conf.ts` like so:
+Rename `wdio.conf.ts` to `wdio.conf.mts` and set it up like so:
 ```ts
 import * as path from "path"
 
 export const config: WebdriverIO.Config = {
     runner: 'local',
-
-    specs: [
-        './test/specs/**/*.e2e.ts'
-    ],
-
+    framework: 'mocha',
+    specs: ['./test/specs/**/*.e2e.ts'],
     // How many instances of Obsidian should be launched in parallel
     maxInstances: 4,
 
@@ -74,26 +69,24 @@ export const config: WebdriverIO.Config = {
         },
     }],
 
-    framework: 'mocha',
     services: ["obsidian"],
     // You can use any wdio reporter, but they show the Chromium version
     // instead of the Obsidian version. obsidian reporter just wraps
     // spec reporter to show the Obsidian version.
     reporters: ['obsidian'],
 
+    // wdio-obsidian-service will download Obsidian versions into this directory
+    cacheDir: path.resolve(".obsidian-cache"),
     mochaOpts: {
         ui: 'bdd',
         timeout: 60000,
         // You can set mocha settings like "retry" and "bail"
     },
-
-    cacheDir: path.resolve(".obsidian-cache"),
-
     logLevel: "warn",
 }
 ```
 
-And create a file `test/specs/test.e2e.ts` with something like:
+And create a test file `test/specs/test.e2e.ts`:
 ```ts
 import { browser } from '@wdio/globals'
 
@@ -101,7 +94,7 @@ describe('Test my plugin', function() {
     before(async function() {
         // You can create test vaults and open them with reloadObsidian
         // Alternatively if all your tests use the same vault, you can
-        // set the default vault in the wdio.conf.ts.
+        // set the default vault in the wdio.conf.mts.
         await browser.reloadObsidian({vault: "./test/vaults/simple"});
     })
     it('test command open-sample-modal-simple', async () => {
@@ -115,8 +108,14 @@ describe('Test my plugin', function() {
 })
 ```
 
-`wdio-obsidian-service` has a few helper functions that can be useful in your wdio conf, such as `obsidianBetaAvailable`
-which checks if there's a current Obsidian beta and you have the credentials to download it. E.g. to test on your `minAppVersion`, `latest`, and `latest-beta` if it's available, use:
+Now you can run your tests with
+```bash
+wdio run ./wdio.conf.mts
+```
+
+Add that command to your `package.json` scripts and you are good to go!
+
+`wdio-obsidian-service` has a few helper functions that can be useful in your `wdio.conf.mts`, such as `obsidianBetaAvailable` which checks if there's a current Obsidian beta and you have the credentials to download it. E.g. to test on your plugin on Obsidian `latest`, `latest-beta`, and your `minAppVersion` use:
 ```ts
 import { obsidianBetaAvailable } from "wdio-obsidian-service";
 const cacheDir = path.resolve(".obsidian-cache");
@@ -146,46 +145,19 @@ export const config: WebdriverIO.Config = {
 ```
 Note, to use top-level await you'll need to rename `wdio.conf.ts` to `wdio.conf.mts` so it's loaded as an ESM module.
 
-You can see the [sample plugin](https://github.com/jesse-r-s-hines/wdio-obsidian-service-sample-plugin) for more
-examples of how to write your wdio conf and e2e tests.
-
-### Platform Support
-`wdio-obsidian-service` works on Windows, Linux, and MacOS.
-
-On Windows, you'll need to install [7zip](https://www.7-zip.org) and add it to the PATH so the service can extract the
-Obsidian installer. Windows firewall will sometimes complain about NodeJS, you can just cancel the popup it makes.
-
-Currently `wdio-obsidian-service` only works for Obsidian Desktop. Testing Obsidian Mobile may be added in the future
-using WDIO + Appium.
-
-### Test Frameworks
-WebdriverIO can run tests using [Mocha](https://mochajs.org), [Jasmine](https://jasmine.github.io), and
-[Cucumber](https://cucumber.io/). Mocha is the easiest to set up and is used in all the wdio-obsidian-service examples.
-Mocha can also run your unit tests, typically with the addition of an assertion library like
-[Chai](https://www.chaijs.com). You can't run WebdriverIO using [Jest](https://jestjs.io), but if you already have Jest
-unit tests (or just prefer Jest) you can easily continue using Jest for your unit tests and Mocha just for your e2e
-tests. The built-in WebdriverIO [expect](https://webdriver.io/docs/api/expect-webdriverio) is very similar to Jest
-matchers, so should be familiar to use.
+See the [sample plugin](https://github.com/jesse-r-s-hines/wdio-obsidian-service-sample-plugin) for more examples of how to write your `wdio.conf.mts` and e2e tests.
 
 ## Usage
 
 ### Obsidian App vs Installer Versions
-Obsidian is distributed in two parts, the "installer" which is the executable containing Electron, and the "app" which
-is a bundle of JavaScript containing the Obsidian code. Obsidian's self-update system only updates the app JS bundle,
-and not the base installer/Electron version. This makes Obsidian's auto-update fast as it only needs to download a few
-MiB of JS instead of all of Electron. But, it means different users with the same Obsidian app version may be running on
-different versions of Electron, which can cause subtle differences in plugin behavior.
 
-You can check your current Obsidian app and installer versions in the General settings tab.
-
-You can specify both `appVersion` and `installerVersion` in your `wdio.conf.mts` capabilities section.
+Obsidian Desktop is distributed in two parts, the "installer" which is the executable containing Electron, and the "app" which is a bundle of JavaScript containing the Obsidian code. Obsidian's self-update system only updates the app JS bundle, and not the base installer/Electron version. This makes Obsidian's auto-update fast as it only needs to download a few MiB of JS instead of all of Electron. But, it means different users with the same Obsidian app version may be running on different versions of Electron, which can cause subtle differences in plugin behavior. You can specify both `appVersion` and `installerVersion` in your `wdio.conf.mts` capabilities section.
 
 To set the app version use `browserVersion` or `'wdio:obsidianOptions'.appVersion`. It can be set to one of:
 - a specific version string like "1.7.7"
 - "latest": run the latest non-beta Obsidian version
 - "latest-beta": run the latest beta Obsidian version (or latest is there is no current beta)
-    - To download Obsidian beta versions you'll need to have an Obsidian account with Catalyst and set the 
-      `OBSIDIAN_USERNAME` and `OBSIDIAN_PASSWORD` environment variables. 2FA needs to be disabled.
+    - To download Obsidian beta versions you'll need have an Obsidian Insiders account and either set the `OBSIDIAN_EMAIL` and `OBSIDIAN_PASSWORD` env vars (`.env` is supported) or pre-download the Obsidian beta with  `npx obsidian-launcher download -v latest-beta`.
 - "earliest": run the `minAppVersion` set in your plugin's `manifest.json`
 
 To set the installer version use `'wdio:obsidianOptions'.installerVersion`. It can be set to one of:
@@ -193,18 +165,13 @@ To set the installer version use `'wdio:obsidianOptions'.installerVersion`. It c
 - "latest": run the latest Obsidian installer compatible with `appVersion`
 - "earliest": run the oldest Obsidian installer compatible with `appVersion`
 
-You can see more configuration options for the capabilities
-[here](https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/ObsidianCapabilityOptions.html).
+You can see more configuration options for the capabilities [here](https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/ObsidianCapabilityOptions.html).
 
 ### Opening and Switching between Vaults
-If all your tests use the same vault, you can set the vault in the `wdio:obsidianOptions` capabilities section. If you
-need to switch between vaults during your test you can use the `reloadObsidian` or `resetVault` functions. These can
-also be useful for reseting state between tests to avoid tests affecting each other (such as in Mocha `before` and
-`beforeEach` hooks).
-
-`browser.reloadObsidian` completely reboots Obsidian with a fresh copy of the vault. This will clear all state, but is
-quite slow so avoid calling it too often.
-E.g.
+
+If all your tests use the same vault, you can set the vault in the `wdio:obsidianOptions` capabilities section. If you need to switch between vaults during your test you can use the `reloadObsidian` or `resetVault` functions. These can also be useful for resetting state between tests (such as in Mocha `before` and `beforeEach` hooks). 
+
+`browser.reloadObsidian` reboots Obsidian with a fresh copy of the vault. This will clear all state, but is quite slow. E.g.
 ```ts
 it("test the thing", async function() {
     await browser.reloadObsidian({vault: "test/vaults/simple"});
@@ -212,9 +179,7 @@ it("test the thing", async function() {
 })
 ```
 
-`obsidianPage.resetVault` is a faster alternative to `reloadObsidian`. It resets vault files to their original state in
-place without rebooting Obsidian. It only resets vault files, not Obsidian configuration etc, but in many cases that's
-all you need. You'll often want to put this in a `beforeEach`.
+`obsidianPage.resetVault` is a faster alternative to `reloadObsidian`. It updates the vault by modifying files in place without reloading Obsidian. It only updates vault files, not Obsidian configuration etc, but in many cases that's all you need. You'll often want to put this in a `beforeEach`.
 ```ts
 import { obsidianPage } from 'wdio-obsidian-service';
 it("test the thing", async function() {
@@ -226,15 +191,112 @@ it("test the thing", async function() {
 })
 ```
 
+## Platform Support
+
+`wdio-obsidian-service` can test Obsidian desktop on Windows, MacOS, and Linux.
+
+There are two approaches to testing Obsidian mobile. You can emulate the mobile UI in desktop app, which is easy to set up but an imperfect emulation of mobile. Or you can run tests on the real mobile app using an Android Virtual Device (avd). `wdio-obsidian-service` supports both options.
+
+Testing on iOS is currently not supported.
+
+### Mobile Emulation
+
+Testing your plugin with "mobile emulation" is very easy to set up. Just add a capability like this in your `wdio.conf.mts`:
+```js
+// ...
+capabilities: [{
+    browserName: "obsidian",
+    browserVersion: "latest",
+    'wdio:obsidianOptions': {
+        emulateMobile: true,
+    },
+    'goog:chromeOptions': {
+        mobileEmulation: {
+            // can also set deviceName: "iPad" etc. instead of hard-coding size
+            deviceMetrics: { width: 390, height: 844 },
+        },
+    },
+}],
+```
+
+This will use Obsidian's [app.emulateMobile](https://docs.obsidian.md/Plugins/Getting+started/Mobile+development#Emulate+mobile+device+on+desktop) to test the mobile UI on the Electron desktop app. Note that the real Obsidian mobile app runs on [Capacitor.js ](https://capacitorjs.com) instead of Electron, so there are various platform differences that can't be properly emulated this way. E.g. Capacitor doesn't have access to node and Electron APIs, and has more limited access to the operating system. But if your plugin isn't directly interacting with the operating system or any advanced Electron APIs using mobile emulation will likely be sufficient.
+
+
+### Android
+
+You can also test on the real mobile app using [Appium](https://appium.io) and [Android Studio](https://developer.android.com/studio). This is a bit more work to set up, but is a more accurate test.
+
+To set this up, install Appium and the Appium Android driver:
+```bash
+npm install --save-dev appium appium-uiautomator2-driver @wdio/appium-service
+```
+
+Then follow these instructions: [Appium - Set up Android automation requirements](https://appium.io/docs/en/2.19/quickstart/uiauto2-driver/#set-up-android-automation-requirements)
+
+You can skip the `appium driver install ...` bit as you already installed the driver via npm above.
+
+Then use the Android Studio "Virtual Device Manager" to create a Android Virtual Device and name it `obsidian_test`.
+
+Then set up a new `wdio.mobile.conf.mts` file like so:
+```ts
+import * as path from "path"
+
+export const config: WebdriverIO.Config = {
+    runner: 'local',
+    framework: 'mocha',
+    specs: ['./test/specs/**/*.e2e.ts'],
+
+    maxInstances: 1, // can't do android tests in parallel :(
+
+    capabilities: [{
+        browserName: "obsidian",
+        browserVersion: "latest",
+        platformName: 'Android',
+        'appium:automationName': 'UiAutomator2',
+        'appium:avd': "obsidian_test",
+        'appium:enforceAppInstall': true,
+        'wdio:obsidianOptions': {
+            plugins: ["."],
+            vault: "test/vaults/simple",
+        },
+    }],
+
+    services: ["obsidian"],
+    reporters: ['obsidian'],
+
+    cacheDir: path.resolve(".obsidian-cache"),
+    mochaOpts: {
+        ui: 'bdd',
+        timeout: 60000,
+    },
+    logLevel: "warn",
+}
+```
+and run
+```bash
+wdio run ./wdio.mobile.conf.mts
+```
+
+This will spin up the Android Virtual Device, install Obsidian in it, and run your tests on it.
+
+See also: The [sample plugin](https://github.com/jesse-r-s-hines/wdio-obsidian-service-sample-plugin) for an example `wdio.mobile.conf.mts` file, [Appium](https://appium.github.io/appium.io/docs/en/writing-running-appium/caps) and [Appium UiAutomator2](https://github.com/appium/appium-uiautomator2-driver?tab=readme-ov-file#capabilities) for more capability options you can use
+
+## Test Frameworks
+
+WebdriverIO can run tests using [Mocha](https://mochajs.org), [Jasmine](https://jasmine.github.io), and [Cucumber](https://cucumber.io/). Mocha is the easiest to set up and is used in all the `wdio-obsidian-service` examples. Mocha can also run your unit tests, typically with the addition of an assertion library like [Chai](https://www.chaijs.com). You can't run WebdriverIO using [Jest](https://jestjs.io), but if you already have Jest unit tests (or just prefer Jest) you can easily continue using Jest for your unit tests and Mocha just for your e2e tests. The built-in WebdriverIO [expect](https://webdriver.io/docs/api/expect-webdriverio) is very similar to Jest matchers, so should be familiar to use.
+
 ### API Docs
-API docs, including all configuration options and helper functions, are available
-[here](https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/README.html).
+
+API docs, including all configuration options and helper functions, are available [here](https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/README.html).
+
+Some key bits:
+- See [ObsidianCapabilityOptions](https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/ObsidianCapabilityOptions.html) for all the options you can pass to `wdio:obsidianOptions` in your wdio.conf.mts
+- See [ObsidianBrowserCommands](https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/ObsidianBrowserCommands.html) and [ObsidianPage](https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/ObsidianPage.html) for various useful helper functions
+
+And of course, see also [WDIO's documentation](https://webdriver.io/docs/gettingstarted) and the [many browser commands it provides](https://webdriver.io/docs/api/browser).
 
 ### GitHub CI Workflows
-The sample plugin has workflows set up to release and test your plugin, which you can see
-[here](https://github.com/jesse-r-s-hines/wdio-obsidian-service-sample-plugin#github-workflows).
+The sample plugin has workflows set up to release and test your plugin, which you can see [here](https://github.com/jesse-r-s-hines/wdio-obsidian-service-sample-plugin#github-workflows).
 
 ### obsidian-launcher CLI
-`wdio-obsidian-service` depends on `obsidian-launcher` so the `obsidian-launcher` CLI is also available, with some 
-commands for launching different Obsidian versions. CLI docs available
-[here](https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/README.html#cli).
+`wdio-obsidian-service` depends on [obsidian-launcher](../../packages/obsidian-launcher/README.md) so the `obsidian-launcher` CLI is also available, with some commands for launching different Obsidian versions. CLI docs available [here](https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/README.html#cli).