WDIO Obsidian Service

https://jesse-r-s-hines.github.io/wdio-obsidian-service
Admin
WDIO Obsidian Service is a WebdriverIO service for end-to-end testing of Obsidian plugins, enabling...
Tokens:27,385
Snippets:166
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Setup Vault API

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Sets up a vault for Obsidian, allowing for plugin and theme installation, and optional vault copying.

```APIDOC
## POST /setupVault

### Description
Sets up a vault for Obsidian, installing plugins and themes and optionally copying the vault to a temporary directory first.

### Method
POST

### Endpoint
/setupVault

### Parameters
#### Request Body
- **vault** (string) - Required - Path to the vault to open in Obsidian.
- **copy** (boolean) - Optional - Whether to copy the vault to a tmpdir first. Default false.
- **plugins** (PluginEntry[]) - Optional - List of plugins to install in the vault.
- **themes** (ThemeEntry[]) - Optional - List of themes to install in the vault.

### Request Example
```json
{
  "vault": "/path/to/my/vault",
  "copy": true,
  "plugins": [
    { "id": "obsidian-dataview" },
    { "id": "obsidian-kanban", "version": "1.2.0" }
  ],
  "themes": [
    { "name": "Minimal", "version": "3.0.0" }
  ]
}
```

### Response
#### Success Response (200)
- **string** - Path to the copied vault (or just the path to the vault if copy is false).
```

--------------------------------

### Install Obsidian

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Installs Obsidian using provided parameters like app version, installer version, and optionally app path.

```APIDOC
## POST /install

### Description
Installs Obsidian with the specified configuration.

### Method
POST

### Endpoint
/install

### Parameters
#### Request Body
- **appVersion** (string) - Required - Obsidian app version.
- **installerVersion** (string) - Required - Obsidian installer version string.
- **appPath** (string) - Optional - Path to the asar file to install. Will download if omitted.
- **vault** (string) - Optional - Path to the vault to open in Obsidian.
- **localStorage** (Record<string, string>) - Optional - Items to add to localStorage. `$vaultId` in the keys will be replaced with the vaultId.
- **chromePreferences** (Record<string, any>) - Optional - Chrome preferences to add to the Preferences file.

### Request Example
```json
{
  "appVersion": "1.0.0",
  "installerVersion": "1.0.0",
  "appPath": "/path/to/obsidian.asar",
  "vault": "/path/to/vault",
  "localStorage": {
    "$vaultId": "someValue"
  },
  "chromePreferences": {
    "window": {
      "width": 1024,
      "height": 768
    }
  }
}
```

### Response
#### Success Response (200)
- **string** - A string indicating the success of the installation, likely a confirmation message or path.
```

--------------------------------

### Launch Obsidian via JavaScript API with obsidian-launcher

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/README

This JavaScript example demonstrates how to use the ObsidianLauncher class to programmatically download and launch Obsidian. It allows specifying the application version, vault path, plugins to install (local or community), and whether to open a copy of the vault.

```javascript
import ObsidianLauncher from "obsidian-launcher"  
const launcher = new ObsidianLauncher();  
const {proc} = await launcher.launch({  
    appVersion: "1.8.10",  
    vault: "path/to/my/vault",  
    copy: true, // open a copy of the vault in Obsidian  
    plugins: [  
        "path/to/my/plugin", // install a local plugin  
        {id: "dataview"}, // install a community plugin  
    ],  
})
```

--------------------------------

### Get Obsidian Installer Information

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Fetches detailed information about the Obsidian installer for a specified installer version and optionally a target platform and architecture. It returns an object including the download URL for the installer.

```typescript
async function getInstallerDetails(launcher) {
  const installerInfo = await launcher.getInstallerInfo('latest', {
    platform: 'darwin',
    arch: 'x64'
  });
  console.log('Installer Info:', installerInfo);
}
```

--------------------------------

### installPlugins

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Installs a list of specified plugins into an Obsidian vault. Requires the path to the vault and the list of plugins to install.

```APIDOC
## POST /installPlugins

### Description
Installs plugins into an Obsidian vault.

### Method
POST

### Endpoint
/installPlugins

### Parameters
#### Request Body
- **vault** (string) - Required - Path to the vault to install the plugins in.
- **plugins** (Array<PluginEntry>) - Required - List plugins to install.
  - **PluginEntry** (object)
    - **repo** (string) - Optional - GitHub repository in the format "org/repo".
    - **id** (string) - Optional - Community plugin ID.
    - **path** (string) - Optional - Local path to the plugin.

### Request Example
```json
{
  "vault": "/path/to/my/vault",
  "plugins": [
    { "id": "plugin-a" },
    { "repo": "org/repo-b" }
  ]
}
```

### Response
#### Success Response (200)
- (void) - Indicates successful installation.

#### Response Example
(No response body on success)
```

--------------------------------

### Setup Local Development for WDIO Obsidian Service

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/CONTRIBUTING

Installs dependencies, builds the project, and runs tests. May require a second 'pnpm install' on Windows after build. Ensure code changes are rebuilt before re-running tests.

```shell
pnpm install
pnpm run build
pnpm run test
```

--------------------------------

### Install wdio-obsidian-service

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/README

Install the wdio-obsidian-service and its dependencies using npm. This command installs the service, a reporter, and mocha with its types.

```bash
npm install --save-dev wdio-obsidian-service wdio-obsidian-reporter mocha @types/mocha
```

--------------------------------

### installThemes

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Installs a list of specified themes into an Obsidian vault. Requires the path to the vault and the list of themes to install.

```APIDOC
## POST /installThemes

### Description
Installs themes into an Obsidian vault.

### Method
POST

### Endpoint
/installThemes

### Parameters
#### Request Body
- **vault** (string) - Required - Path to the vault to install the themes in.
- **themes** (Array<ThemeEntry>) - Required - List of themes to install.
  - **ThemeEntry** (object)
    - **repo** (string) - Optional - GitHub repository in the format "org/repo".
    - **name** (string) - Optional - Community theme name.
    - **path** (string) - Optional - Local path to the theme.

### Request Example
```json
{
  "vault": "/path/to/my/vault",
  "themes": [
    { "name": "theme-x" },
    { "repo": "org/repo-y" }
  ]
}
```

### Response
#### Success Response (200)
- (void) - Indicates successful installation.

#### Response Example
(No response body on success)
```

--------------------------------

### Launch Obsidian via CLI with obsidian-launcher

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/README

This command downloads and launches a specific version of Obsidian (1.8.10 in this example) with a sandboxed configuration. It's useful for testing without affecting your system's Obsidian installation and can be used to compare different Obsidian versions.

```bash
npx obsidian-launcher watch --version 1.8.10 --copy --plugin . test/vault
```

--------------------------------

### ObsidianLauncher Class

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

The ObsidianLauncher class is a helper that manages downloading and installing Obsidian versions, plugins, and themes, and launching Obsidian with sandboxed configuration directories.

```APIDOC
## Class ObsidianLauncher

### Description
Helper class that handles downloading and installing Obsidian versions, plugins, and themes and launching Obsidian with sandboxed configuration directories.

### Constructors

#### constructor
```typescript
new ObsidianLauncher(
  opts?: {
    cacheDir?: string;
    versionsUrl?: string;
    communityPluginsUrl?: string;
    communityThemesUrl?: string;
    cacheDuration?: number;
    interactive?: boolean;
  }
): ObsidianLauncher
```

Construct an ObsidianLauncher.

##### Parameters

*   `opts`: {
    `cacheDir`?: string;
    `versionsUrl`?: string;
    `communityPluginsUrl`?: string;
    `communityThemesUrl`?: string;
    `cacheDuration`?: number;
    `interactive`?: boolean;
  } = {}
    *   `Optional` **cacheDir**: string
        Path to the cache directory. Defaults to "OBSIDIAN_CACHE" env var or ".obsidian-cache".
    *   `Optional` **versionsUrl**: string
        Custom `obsidian-versions.json` url. Can be a file URL.
    *   `Optional` **communityPluginsUrl**: string
        Custom `community-plugins.json` url. Can be a file URL.
    *   `Optional` **communityThemesUrl**: string
        Custom `community-css-themes.json` url. Can be a file URL.
    *   `Optional` **cacheDuration**: number
        If the cached version list is older than this (in ms), refetch it. Defaults to 30 minutes.
    *   `Optional` **interactive**: boolean
        If it can prompt the user for input (e.g. for Obsidian credentials). Default false.

#### Returns ObsidianLauncher
```

--------------------------------

### Launch Obsidian API

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Downloads and launches Obsidian with a sandboxed config directory and a specific vault open. Optionally installs plugins and themes first.

```APIDOC
## POST /launch

### Description
Downloads and launches Obsidian with a sandboxed config dir and a specifc vault open. Optionally install plugins and themes first.

### Method
POST

### Endpoint
/launch

### Parameters
#### Request Body
- **appVersion** (string) - Optional - Obsidian app version. Default "latest".
- **installerVersion** (string) - Optional - Obsidian installer version. Default "latest".
- **copy** (boolean) - Optional - Whether to copy the vault to a tmpdir first. Default false.
- **vault** (string) - Optional - Path to the vault to open in Obsidian.
- **plugins** (PluginEntry[]) - Optional - List of plugins to install in the vault.
- **themes** (ThemeEntry[]) - Optional - List of themes to install in the vault.
- **args** (string[]) - Optional - CLI args to pass to Obsidian.
- **localStorage** (Record<string, string>) - Optional - Items to add to localStorage. `$vaultId` in the keys will be replaced with the vaultId.
- **spawnOptions** (SpawnOptions) - Optional - Options to pass to `spawn`.

### Request Example
```json
{
  "appVersion": "latest",
  "vault": "/path/to/my/vault",
  "plugins": [
    { "id": "obsidian-dataview" }
  ],
  "args": ["--no-sandbox"],
  "localStorage": {
    "theme": "dark"
  }
}
```

### Response
#### Success Response (200)
- **proc** (ChildProcess) - The launched child process.
- **configDir** (string) - The created temporary configuration directory.
- **vault** (string) - Optional - The path to the vault that was opened.
```

--------------------------------

### Install Appium and Android Driver for wdio-obsidian-service

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/README

Installs the required npm packages for using Appium with the wdio-obsidian-service. This includes Appium itself, the Appium Android driver, and the Appium service for WebdriverIO.

```bash
npm install --save-dev appium appium-uiautomator2-driver @wdio/appium-service
```

--------------------------------

### downloadInstaller

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Downloads the Obsidian installer for a specified version and platform. It supports downloading for the host's default platform and architecture or for a custom platform and architecture.

```APIDOC
## POST /downloadInstaller

### Description
Downloads the Obsidian installer for the given version and platform/arch (defaults to host platform/arch). Returns the file path.

### Method
POST

### Endpoint
/downloadInstaller

### Parameters
#### Request Body
- **installerVersion** (string) - Required - Obsidian installer version to download
- **opts** (object) - Optional - Options for platform and architecture
  - **platform** (Platform) - Optional - Platform/os of the installer to download (defaults to host platform)
  - **arch** (Architecture) - Optional - Architecture of the installer to download (defaults to host architecture)

### Request Example
```json
{
  "installerVersion": "1.0.0",
  "opts": {
    "platform": "win32",
    "arch": "x64"
  }
}
```

### Response
#### Success Response (200)
- **filePath** (string) - The file path to the downloaded installer.

#### Response Example
```json
{
  "filePath": "/path/to/installer.exe"
}
```
```

--------------------------------

### setupConfigDir

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Sets up a configuration directory for Obsidian, which can be used with the `--user-data-dir` flag. It allows customization of app version, installer version, app path, vault path, local storage, and Chrome preferences.

```APIDOC
## POST /setupConfigDir

### Description
Sets up the config dir to use for the `--user-data-dir` in obsidian. Returns the path to the created config dir.

### Method
POST

### Endpoint
/setupConfigDir

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for setting up the config directory.
  - **appVersion** (string) - Required - The version of the Obsidian application.
  - **installerVersion** (string) - Required - The version of the Obsidian installer.
  - **appPath** (string) - Optional - The path to the Obsidian application executable.
  - **vault** (string) - Optional - The path to the Obsidian vault to be used.
  - **localStorage** (Record<string, string>) - Optional - Key-value pairs for local storage settings.
  - **chromePreferences** (Record<string, any>) - Optional - Custom Chrome preferences.

### Request Example
```json
{
  "params": {
    "appVersion": "1.5.3",
    "installerVersion": "1.0.0",
    "appPath": "/Applications/Obsidian.app",
    "vault": "/Users/user/vaults/main",
    "localStorage": {
      "setting1": "value1"
    },
    "chromePreferences": {
      "profile": {
        "default_content_settings": {
          "images": 2
        }
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **configDirPath** (string) - The path to the created configuration directory.

#### Response Example
```json
{
  "configDirPath": "/tmp/obsidian-config-xxxxxx"
}
```
```

--------------------------------

### Configure Obsidian Capability Options in wdio.conf.mts

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/ObsidianCapabilityOptions

Demonstrates how to set up the Obsidian capability options within the wdio.conf.mts file. This includes specifying the browser name, version, and custom Obsidian options like installer version and plugins. This setup is crucial for initializing the Obsidian service in WebdriverIO tests.

```typescript
// ...  
capsabilities: [{
    browserName: "obsidian",
    browserVersion: "latest",
    'wdio:obsidianOptions': {
        installerVersion: 'earliest',
        plugins: ["."],
    },
}],
Copy
```

--------------------------------

### getObsidianInstallerVersion

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/ObsidianBrowserCommands

Fetches the version of the Obsidian installer. This can be useful for understanding the installation context.

```APIDOC
## GET /getObsidianInstallerVersion

### Description
Returns the Obsidian installer version this test is running under.

### Method
GET

### Endpoint
/getObsidianInstallerVersion

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **installerVersion** (string) - The version string of the Obsidian installer.

#### Response Example
```json
{
  "installerVersion": "1.0.0"
}
```
```

--------------------------------

### Configure Obsidian App and Installer Versions in wdio.conf.mts

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/README

Demonstrates how to set specific app and installer versions for Obsidian in the WebdriverIO configuration file. This allows for precise control over the testing environment, ensuring compatibility and reproducible results.

```javascript
// Example wdio.conf.mts configuration
capabilities: [
  {
    browserName: "obsidian",
    // Specify app version, e.g., "1.7.7", "latest", "latest-beta", or "earliest"
    browserVersion: "latest", 
    // Specify installer version, e.g., "1.7.7", "latest", or "earliest"
    'wdio:obsidianOptions': {
      appVersion: "1.7.7",
      installerVersion: "latest"
    }
  }
]
```

--------------------------------

### Get Obsidian installer version (TypeScript)

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/ObsidianBrowserCommands

Retrieves the version string of the Obsidian installer associated with the current application instance.

```typescript
browser.getObsidianInstallerVersion(): string
Copy

```

--------------------------------

### Resolve Obsidian App and Installer Versions

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Converts abstract version specifiers (like 'latest', 'latest-beta', 'earliest') into concrete application and installer version strings. It ensures compatibility between the app and its installer, returning a tuple of [appVersion, installerVersion].

```typescript
async function resolveVersions(launcher) {
  const [appVer, installerVer] = await launcher.resolveVersion('latest', 'earliest');
  console.log(`Resolved versions: App=${appVer}, Installer=${installerVer}`);
}
```

--------------------------------

### Run wdio-obsidian-service Tests on Android

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/README

Command to execute the WebdriverIO tests using the configured mobile configuration file. This command will launch the Android Virtual Device, install Obsidian, and run the defined end-to-end tests.

```bash
wdio run ./wdio.mobile.conf.mts
```

--------------------------------

### Configure Mobile Emulation in Capabilities

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/README

Provides an example of how to enable mobile emulation for testing Obsidian on mobile devices. This is configured within the `wdio.conf.mts` capabilities, specifying `emulateMobile` and `goog:chromeOptions` for device metrics.

```javascript
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 },
      },
    },
  }
]
```

--------------------------------

### Get Available Community Themes

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Fetches information about all community themes for Obsidian. This method returns a promise that resolves to an array of ObsidianCommunityTheme objects, each containing details about a theme.

```typescript
async function getObsidianThemes(launcher) {
  const themes = await launcher.getCommunityThemes();
  console.log('Available Community Themes:', themes);
}
```

--------------------------------

### Obsidian Version Information API

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/ObsidianVersionInfo

This section describes the structure of ObsidianVersionInfo, which contains metadata about a specific Obsidian version. It includes version details, compatibility information, download URLs, and installer specifics.

```APIDOC
## Type Alias: ObsidianVersionInfo

### Description
Metadata about a specific Obsidian version, including the min/max compatible installer versions, download urls, and the internal Electron version.

### Properties

*   **version** (string) - Required - The version string of the Obsidian release.
*   **minInstallerVersion** (string) - Optional - The minimum compatible installer version.
*   **maxInstallerVersion** (string) - Optional - The maximum compatible installer version.
*   **isBeta** (boolean) - Required - Indicates if this is a beta release.
*   **gitHubRelease** (string) - Optional - URL to the GitHub release page.
*   **downloads** (object) - Required - Contains direct download URLs for various platforms.
    *   **asar** (string) - Optional - Download URL for the .asar archive.
    *   **appImage** (string) - Optional - Download URL for the AppImage (x64).
    *   **appImageArm** (string) - Optional - Download URL for the AppImage (ARM).
    *   **tar** (string) - Optional - Download URL for the .tar archive (x64).
    *   **tarArm** (string) - Optional - Download URL for the .tar archive (ARM).
    *   **dmg** (string) - Optional - Download URL for the macOS .dmg installer.
    *   **exe** (string) - Optional - Download URL for the Windows .exe installer.
    *   **apk** (string) - Optional - Download URL for the Android .apk package.
*   **installers** (object) - Required - Contains detailed installer information for various platforms.
    *   **appImage** (ObsidianInstallerInfo) - Optional - Installer details for AppImage (x64).
    *   **appImageArm** (ObsidianInstallerInfo) - Optional - Installer details for AppImage (ARM).
    *   **tar** (ObsidianInstallerInfo) - Optional - Installer details for .tar archive (x64).
    *   **tarArm** (ObsidianInstallerInfo) - Optional - Installer details for .tar archive (ARM).
    *   **dmg** (ObsidianInstallerInfo) - Optional - Installer details for macOS .dmg.
    *   **exe** (ObsidianInstallerInfo) - Optional - Installer details for Windows .exe.
*   **electronVersion** (string) - Optional - The internal Electron version. Deprecated, use installers instead.
*   **chromeVersion** (string) - Optional - The internal Chrome version. Deprecated, use installers instead.

### Request Example
```json
{
  "version": "1.0.0",
  "minInstallerVersion": "1.0.0",
  "maxInstallerVersion": "1.5.0",
  "isBeta": false,
  "gitHubRelease": "https://github.com/obsidianmd/obsidian-releases/releases/tag/v1.0.0",
  "downloads": {
    "asar": "https://github.com/obsidianmd/obsidian-releases/releases/download/v1.0.0/Obsidian-1.0.0.asar",
    "appImage": "https://github.com/obsidianmd/obsidian-releases/releases/download/v1.0.0/Obsidian-1.0.0.AppImage",
    "dmg": "https://github.com/obsidianmd/obsidian-releases/releases/download/v1.0.0/Obsidian-1.0.0.dmg",
    "exe": "https://github.com/obsidianmd/obsidian-releases/releases/download/v1.0.0/Obsidian-1.0.0-Setup.exe"
  },
  "installers": {
    "appImage": {
      "url": "https://github.com/obsidianmd/obsidian-releases/releases/download/v1.0.0/Obsidian-1.0.0.AppImage",
      "sha256": "a1b2c3d4e5f6..."
    },
    "dmg": {
      "url": "https://github.com/obsidianmd/obsidian-releases/releases/download/v1.0.0/Obsidian-1.0.0.dmg",
      "sha256": "f6e5d4c3b2a1..."
    }
  },
  "electronVersion": "10.1.5",
  "chromeVersion": "87.0.4280.141"
}
```

### Response Example
```json
{
  "version": "1.0.0",
  "minInstallerVersion": "1.0.0",
  "maxInstallerVersion": "1.5.0",
  "isBeta": false,
  "gitHubRelease": "https://github.com/obsidianmd/obsidian-releases/releases/tag/v1.0.0",
  "downloads": {
    "asar": "https://github.com/obsidianmd/obsidian-releases/releases/download/v1.0.0/Obsidian-1.0.0.asar",
    "appImage": "https://github.com/obsidianmd/obsidian-releases/releases/download/v1.0.0/Obsidian-1.0.0.AppImage",
    "dmg": "https://github.com/obsidianmd/obsidian-releases/releases/download/v1.0.0/Obsidian-1.0.0.dmg",
    "exe": "https://github.com/obsidianmd/obsidian-releases/releases/download/v1.0.0/Obsidian-1.0.0-Setup.exe"
  },
  "installers": {
    "appImage": {
      "url": "https://github.com/obsidianmd/obsidian-releases/releases/download/v1.0.0/Obsidian-1.0.0.AppImage",
      "sha256": "a1b2c3d4e5f6..."
    },
    "dmg": {
      "url": "https://github.com/obsidianmd/obsidian-releases/releases/download/v1.0.0/Obsidian-1.0.0.dmg",
      "sha256": "f6e5d4c3b2a1..."
    }
  },
  "electronVersion": "10.1.5",
  "chromeVersion": "87.0.4280.141"
}
```
```

--------------------------------

### Define ObsidianInstallerInfo Type Alias

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/ObsidianInstallerInfo

Defines the structure for metadata related to an Obsidian desktop installer. It includes the file's digest, Electron and Chrome versions, and supported platforms. This type is used to standardize how installer information is represented.

```typescript
type ObsidianInstallerInfo = {
  digest: string;
  electron: string;
  chrome: string;
  platforms: string[];
}
```

--------------------------------

### Create a basic e2e test file

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/README

Write an end-to-end test file using WebdriverIO and mocha. This example demonstrates how to reload Obsidian with a specific vault, execute an Obsidian command, and assert the result.

```typescript
import { browser } from '@wdio/globals'

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.mts.
        await browser.reloadObsidian({vault: "./test/vaults/simple"});
    })
    it('test command open-sample-modal-simple', async () => {
        await browser.executeObsidianCommand(
            "sample-plugin:open-sample-modal-simple",
        );
        const modalEl = browser.$(".modal-container .modal-content");
        await expect(modalEl).toExist();
        await expect(modalEl).toHaveText("Woah!");
    })
})

```

--------------------------------

### Get Available Obsidian Versions

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Fetches detailed information about all available versions of Obsidian. This method returns a promise that resolves to an array of ObsidianVersionInfo objects, each containing details about a specific Obsidian release.

```typescript
async function getObsidianVersions(launcher) {
  const versions = await launcher.getVersions();
  console.log('Available Obsidian Versions:', versions);
}
```

--------------------------------

### Get Available Community Plugins

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Retrieves information about all community plugins available for Obsidian. The method returns a promise that resolves to an array of ObsidianCommunityPlugin objects, each representing a plugin with its metadata.

```typescript
async function getObsidianPlugins(launcher) {
  const plugins = await launcher.getCommunityPlugins();
  console.log('Available Community Plugins:', plugins);
}
```

--------------------------------

### Parse Obsidian Version String

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Parses a string containing multiple Obsidian versions, potentially with specified installer versions, into a structured array of [appVersion, installerVersion] tuples. This is useful for processing lists of versions provided in a human-readable format.

```typescript
async function parseObsidianVersions(launcher) {
  const parsed = await launcher.parseVersions('1.8.10/1.7.7 latest latest-beta/earliest');
  console.log('Parsed Versions:', parsed);
}
```

--------------------------------

### Pass arguments to Obsidian executable using obsidian-launcher CLI

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/README

This example shows how to pass arguments directly to the Obsidian executable when launching it via the `obsidian-launcher` CLI. The `--` separator is used to distinguish launcher arguments from Obsidian executable arguments, such as enabling remote debugging.

```bash
npx obsidian-launcher launch ./vault -- --remote-debugging-port=9222
```

--------------------------------

### Start WDIO Obsidian Session (TypeScript)

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/startWdioSession

Initiates a standalone WDIO session connected to an Obsidian instance. This function is suitable for scripting purposes. It requires WebdriverIOConfig, including Obsidian-specific capabilities, and can optionally accept service options. The return value is a Promise that resolves to a WDIO Browser instance.

```typescript
import { startWdioSession } from "wdio-obsidian-service";
import type { WebdriverIOConfig } from "@wdio/types";

// Example usage:
const browser = await startWdioSession({
    capabilities: {
        browserName: "obsidian",
        browserVersion: "latest",
        'wdio:obsidianOptions': {
            installerVersion: "latest",
            vault: "./test/vaults/basic",
        },
    },
});

await browser.executeObsidian(({app}) => {
    // Perform Obsidian-specific operations, like extracting file metadata or editing the vault.
});

await browser?.deleteSession();
```

--------------------------------

### Get Specific Obsidian Version Info

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Retrieves detailed information for a specific Obsidian application version. The method takes an appVersion string and returns a promise resolving to an ObsidianVersionInfo object containing comprehensive details about that version.

```typescript
async function getVersionDetails(launcher) {
  const versionInfo = await launcher.getVersionInfo('1.5.3');
  console.log('Version Info:', versionInfo);
}
```

--------------------------------

### Download Obsidian Beta Versions

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/README

Shows how to download specific beta versions of the Obsidian application using npx. This is necessary for testing with the latest beta releases and requires either environment variables for authentication or pre-downloading.

```bash
# Download the latest beta Obsidian app version
npx obsidian-launcher download app -v latest-beta
```

--------------------------------

### downloadThemes

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Downloads a list of Obsidian themes to the cache. Supports themes from GitHub repositories, community theme names, and local paths, returning download information.

```APIDOC
## POST /downloadThemes

### Description
Downloads a list of themes to the cache and returns a list of DownloadedThemeEntry with the downloaded paths. Also adds the `name` property to the plugins based on the manifest. You can download themes from GitHub using `{repo: "org/repo"}` and community themes using `{name: 'theme-name'}`. Local themes will just be passed through.

### Method
POST

### Endpoint
/downloadThemes

### Parameters
#### Request Body
- **themes** (Array<ThemeEntry>) - Required - List of themes to download.
  - **ThemeEntry** (object)
    - **repo** (string) - Optional - GitHub repository in the format "org/repo".
    - **name** (string) - Optional - Community theme name.
    - **path** (string) - Optional - Local path to the theme.

### Request Example
```json
{
  "themes": [
    { "repo": "obsidianmd/obsidian-sample-theme" },
    { "name": "theme-a" },
    { "path": "/local/path/to/theme" }
  ]
}
```

### Response
#### Success Response (200)
- **themes** (Array<DownloadedThemeEntry>) - List of downloaded themes with their paths and names.
  - **DownloadedThemeEntry** (object)
    - **name** (string) - The name of the theme.
    - **path** (string) - The file path to the downloaded theme.

#### Response Example
```json
{
  "themes": [
    { "name": "obsidianmd-obsidian-sample-theme", "path": "/cache/themes/sample-theme" },
    { "name": "theme-a", "path": "/cache/themes/theme-a" },
    { "name": "local-theme", "path": "/local/path/to/theme" }
  ]
}
```
```

--------------------------------

### Run wdio tests

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/README

Execute your WebdriverIO tests using the 'wdio run' command with your configuration file. This command initiates the testing process based on the settings in wdio.conf.mts.

```bash
wdio run ./wdio.conf.mts
```

--------------------------------

### Launch Obsidian with Custom Vault, Plugins, and Theme

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/ObsidianBrowserCommands

Launches an Obsidian instance with specified vault, plugins, and theme settings. If parameters are omitted, it uses the current configuration.

```APIDOC
## POST /websites/jesse-r-s-hines_github_io_wdio-obsidian-service

### Description
Launches an Obsidian instance with optional custom vault, plugins, and theme.

### Method
POST

### Endpoint
/websites/jesse-r-s-hines_github_io_wdio-obsidian-service

### Parameters
#### Request Body
- **vault** (string) - Optional - Path to the vault to open. The vault will be copied, so any changes made in your tests won't be persisted to the original. If omitted, it will reboot Obsidian with the current vault without creating a new copy of the vault.
- **plugins** (string[]) - Optional - List of plugin ids to enable. If omitted it will keep the current plugin list. Note, all the plugins must be defined in your wdio.conf.mts capabilities. You can also use the enablePlugin and disablePlugin commands to change plugins without relaunching Obsidian.
- **theme** (string) - Optional - Name of the theme to enable. If omitted it will keep the current theme. Pass "default" to switch back to the default theme. Like with plugins, the theme must be defined in wdio.conf.mts.

### Request Example
```json
{
  "vault": "/path/to/my/vault",
  "plugins": ["plugin-id-1", "plugin-id-2"],
  "theme": "my-custom-theme"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### ObsidianVersionInfo Type Alias Definition

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/ObsidianVersionInfo

Defines the structure for ObsidianVersionInfo, a type alias that holds metadata about a specific Obsidian version. This includes installer version compatibility, download URLs, and internal Electron version details. It also outlines the nested structures for downloads and installers.

```typescript
type ObsidianVersionInfo = {
  version: string;
  minInstallerVersion?: string;
  maxInstallerVersion?: string;
  isBeta: boolean;
  gitHubRelease?: string;
  downloads: {
    asar?: string;
    appImage?: string;
    appImageArm?: string;
    tar?: string;
    tarArm?: string;
    dmg?: string;
    exe?: string;
    apk?: string;
  };
  installers: {
    appImage?: ObsidianInstallerInfo;
    appImageArm?: ObsidianInstallerInfo;
    tar?: ObsidianInstallerInfo;
    tarArm?: ObsidianInstallerInfo;
    dmg?: ObsidianInstallerInfo;
    exe?: ObsidianInstallerInfo;
  };
  electronVersion?: string;
  chromeVersion?: string;
}
```

--------------------------------

### Resolve Obsidian Versions (TypeScript)

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/resolveObsidianVersions

Resolves Obsidian app and installer version strings to absolute versions. It takes the app version, installer version, and an optional cache directory as input and returns a promise resolving to a tuple of strings representing the absolute versions. This function is deprecated.

```typescript
resolveObsidianVersions: (
  appVersion: string,
  installerVersion: string,
  cacheDir?: string,
) => Promise<[string, string]>
```

--------------------------------

### Get Obsidian application version (TypeScript)

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/ObsidianBrowserCommands

Retrieves the version string of the currently running Obsidian application instance during the test session.

```typescript
browser.getObsidianVersion(): string
Copy

```

--------------------------------

### ObsidianLauncher Methods

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Methods available on the ObsidianLauncher class.

```APIDOC
## Methods

### getVersions

  * getVersions(): Promise<ObsidianVersionInfo[]>

Get information about all available Obsidian versions.

#### Returns Promise<ObsidianVersionInfo[]>

### getCommunityPlugins

  * getCommunityPlugins(): Promise<ObsidianCommunityPlugin[]>

Get information about all available community plugins.

#### Returns Promise<ObsidianCommunityPlugin[]>

### getCommunityThemes

  * getCommunityThemes(): Promise<ObsidianCommunityTheme[]>

Get information about all available community themes.

#### Returns Promise<ObsidianCommunityTheme[]>

### resolveVersion

  * resolveVersion(
    appVersion: string,
    installerVersion?: string,
  ): Promise<[string, string]>

Resolves Obsidian app and installer version strings to absolute versions.

#### Parameters

*   **appVersion**: string
specific version or one of
  *   "latest": Get the current latest non-beta Obsidian version
  *   "latest-beta": Get the current latest beta Obsidian version (or latest if there is no current beta)
  *   "earliest": Get the `minAppVersion` set in your `manifest.json`
*   **installerVersion**: string = "latest"
specific version or one of
  *   "latest": Get the latest Obsidian installer compatible with `appVersion`
  *   "earliest": Get the oldest Obsidian installer compatible with `appVersion`
See also: Obsidian App vs Installer Versions

#### Returns Promise<[string, string]>
[appVersion, installerVersion] with any "latest" etc. resolved to specific versions.

### getVersionInfo

  * getVersionInfo(appVersion: string): Promise<ObsidianVersionInfo>

Gets details about an Obsidian version.

#### Parameters

*   **appVersion**: string
Obsidian app version

#### Returns Promise<ObsidianVersionInfo>

### parseVersions

  * parseVersions(versions: string): Promise<[string, string][]>

Parses a string of Obsidian versions into [appVersion, installerVersion] tuples.
`versions` should be a space separated list of Obsidian app versions. You can optionally specify the installer version by using "appVersion/installerVersion" e.g. `"1.7.7/1.8.10"`.
Example:
```javascript
launcher.parseVersions("1.8.10/1.7.7 latest latest-beta/earliest")
```

See also: Obsidian App vs Installer Versions

#### Parameters

*   **versions**: string
string to parse

#### Returns Promise<[string, string][]>
[appVersion, installerVersion][] resolved to specific versions.

### getInstallerInfo

  * getInstallerInfo(
    installerVersion: string,
    opts?: { platform?: Platform; arch?: Architecture },
  ): Promise<ObsidianInstallerInfo & { url: string }>

Gets details about the Obsidian installer for the given platform.

#### Parameters

*   **installerVersion**: string
*   `Optional` **opts**: {
    `platform`?: Platform;
    `arch`?: Architecture;
  }

#### Returns Promise<ObsidianInstallerInfo & { url: string }>
```

--------------------------------

### downloadPlugins

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Downloads a list of Obsidian plugins to the cache. It supports downloading from GitHub repositories, community plugin IDs, and local paths, returning download information including paths and plugin IDs.

```APIDOC
## POST /downloadPlugins

### Description
Downloads a list of plugins to the cache and returns a list of DownloadedPluginEntry with the downloaded paths. Also adds the `id` property to the plugins based on the manifest. You can download plugins from GitHub using `{repo: "org/repo"}` and community plugins using `{id: 'plugin-id'}`. Local plugins will just be passed through.

### Method
POST

### Endpoint
/downloadPlugins

### Parameters
#### Request Body
- **plugins** (Array<PluginEntry>) - Required - List of plugins to download.
  - **PluginEntry** (object)
    - **repo** (string) - Optional - GitHub repository in the format "org/repo".
    - **id** (string) - Optional - Community plugin ID.
    - **path** (string) - Optional - Local path to the plugin.

### Request Example
```json
{
  "plugins": [
    { "repo": "obsidianmd/obsidian-sample-plugin" },
    { "id": "another-plugin" },
    { "path": "/local/path/to/plugin" }
  ]
}
```

### Response
#### Success Response (200)
- **plugins** (Array<DownloadedPluginEntry>) - List of downloaded plugins with their paths and IDs.
  - **DownloadedPluginEntry** (object)
    - **id** (string) - The unique identifier of the plugin.
    - **path** (string) - The file path to the downloaded plugin.

#### Response Example
```json
{
  "plugins": [
    { "id": "obsidianmd-obsidian-sample-plugin", "path": "/cache/plugins/sample-plugin" },
    { "id": "another-plugin", "path": "/cache/plugins/another-plugin" },
    { "id": "local-plugin", "path": "/local/path/to/plugin" }
  ]
}
```
```

--------------------------------

### Construct ObsidianLauncher Instance

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Initializes the ObsidianLauncher class. This constructor can accept an optional configuration object to customize behaviors such as the cache directory, remote URLS for version/plugin/theme lists, cache duration, and interactivity.

```typescript
import ObsidianLauncher from '@wdio/obsidian-service';

const launcher = new ObsidianLauncher({
  cacheDir: './my-obsidian-cache',
  versionsUrl: 'https://example.com/obsidian-versions.json',
  communityPluginsUrl: 'https://example.com/community-plugins.json',
  communityThemesUrl: 'https://example.com/community-themes.json',
  cacheDuration: 60 * 60 * 1000, // 1 hour
  interactive: true
});
```

--------------------------------

### Configure wdio.conf.mts for wdio-obsidian-service

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/README

Set up your wdio.conf.mts file to use the obsidian service and reporter. This configuration specifies the runner, framework, capabilities, and other essential settings for testing Obsidian plugins.

```typescript
import * as path from "path"

export const config: WebdriverIO.Config = {
    runner: 'local',
    framework: 'mocha',
    specs: ['./test/specs/**/*.e2e.ts'],
    // How many instances of Obsidian should be launched in parallel
    maxInstances: 4,

    capabilities: [{
        browserName: 'obsidian',
        // obsidian app version to download
        browserVersion: "latest",
        'wdio:obsidianOptions': {
            // obsidian installer version
            // (see "Obsidian App vs Installer Versions" below)
            installerVersion: "earliest",
            plugins: [""],
            // If you need to switch between multiple vaults, you can omit
            // this and use reloadObsidian to open vaults during the tests
            vault: "test/vaults/simple",
        },
    }],

    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"
    },
    logLevel: "warn",
}
```

--------------------------------

### Get Obsidian Config Directory (TypeScript)

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/ObsidianPage

Returns the path to the Obsidian configuration directory, typically '.obsidian'. This is an asynchronous operation returning a Promise that resolves to a string.

```typescript
getConfigDir(): Promise<string>;
```

--------------------------------

### downloadApp

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/default

Downloads the Obsidian application (asar archive) for a specific version. Supports downloading beta versions using environment variables for authentication.

```APIDOC
## POST /downloadApp

### Description
Downloads the Obsidian asar for the given version. Returns the file path. To download Obsidian beta versions you'll need to have an Obsidian Insiders account and either set the `OBSIDIAN_EMAIL` and `OBSIDIAN_PASSWORD` env vars (`.env` file is supported) or pre-download the Obsidian beta with `npx obsidian-launcher download app -v latest-beta`.

### Method
POST

### Endpoint
/downloadApp

### Parameters
#### Request Body
- **appVersion** (string) - Required - Obsidian version to download

### Request Example
```json
{
  "appVersion": "1.5.3"
}
```

### Response
#### Success Response (200)
- **filePath** (string) - The file path to the downloaded Obsidian asar.

#### Response Example
```json
{
  "filePath": "/path/to/obsidian.asar"
}
```
```

--------------------------------

### Dynamically configure capabilities with beta support

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/README

Conditionally include the latest beta version of Obsidian in your test capabilities if it's available and you have the credentials. This allows testing against the latest beta release.

```typescript
import { obsidianBetaAvailable } from "wdio-obsidian-service";
const cacheDir = path.resolve(".obsidian-cache");

const versions: [string, string][] = [
    ["earliest", "earliest"],
    ["latest", "latest"],
];
if (await obsidianBetaAvailable(cacheDir)) {
    versions.push(["latest-beta", "latest"]);
}

export const config: WebdriverIO.Config = {
    cacheDir: cacheDir,

    capabilities: versions.map(([appVersion, installerVersion]) => ({
        browserName: 'obsidian',
        browserVersion: appVersion,
        'wdio:obsidianOptions': {
            installerVersion: installerVersion,
            plugins: [""],
        },
    })),

    // ...
}

```

--------------------------------

### Get Obsidian page object with helpers (TypeScript)

Source: https://jesse-r-s-hines.github.io/wdio-obsidian-service/wdio-obsidian-service/ObsidianBrowserCommands

Returns an ObsidianPage object that contains convenience helper functions for interacting with the Obsidian application. Alternatively, the `obsidianPage` object can be imported directly.

```typescript
import { obsidianPage } from "wdio-obsidian-service"
Copy

```

```typescript
browser.getObsidianPage(): ObsidianPage
Copy

```
Tokens:
Raw