Obsidian Playwright Template

This is a template for UI testing in Obsidian plugins.

Features:

• Runs Playwright tests, each on separate temporary vaults, using a separate Obsidian installation that won't interfere with any of your own vaults on the same machine.
• Github Actions workflow to run tests in CI.
• Hot plugin reloading on test vaults
• Playwright code generation support

Setup

1. Set up Playwright

First, clone this repo into a new folder.

If you're developing a new plugin, you can use this repo (which is based on the Obsidian Sample Plugin) as a starting point.

To set up on an existing plugin:

• copy the following files and folders into your plugin's project folder:
  • e2e-tests/
  • scripts/
  • playwright.config.ts
  • .github/workflows/ci.yml (if you want to run tests in CI)
• Copy all scripts beginning with e2e from package.json
• Install dependencies: npm i --save-dev @electron/asar@4.0.1 @playwright/test@1.58.0 concurrently@9.2.1 cross-env@10.1.0 obsidian-typings@5.13.0 wait-on@9.0.5
• Update configurations:
  • tsconfig.json: Add "node", "obsidian-typings" to types and add "e2e-tests/**/*.ts", "playwright.config.ts" to include
  • ESLint: add this to the flat config

    {
      // permit node imports in tests
      files: ['**/*.test.ts', '**/*.spec.ts', 'e2e-tests/**'],
      languageOptions: {
        globals: {
          ...globals.node,
        },
      },
      rules: {
        'import/no-nodejs-modules': 'off',
      },
    }
    

• Remove sample tests (sample.spec.ts) or exclude them in Playwright config

2. Set up the test vault for your plugin

• In e2e-tests\setup\test-vault\.obsidian\community-plugins.json, replace the sample plugin ID with your plugin's ID from manifest.json.
• Tweak the json configuration files as desired.
• Add any notes or other files that you wish to use in tests directly into e2e-tests\setup\test-vault\.

3. First-time setup (per machine):

Run scripts/setup-obsidian.sh (Linux/Mac) or setup-obsidian.ps1 (Windows)

4. Set up CI

Ensure Github Actions is enabled for your plugin's repository.

Usage

[!NOTE] Linux users may need to use Xvfb for Playwright, especially the inspector (which is used for codegen).

For example, xvfb-run --auto-servernum npm run e2e

(Optional) Verify test vaults can be created: npm run e2e:setup

Run tests: npm run e2e. Results will be output to e2e-tests/test-results.

Writing tests

This is largely the same as writing Playwright tests for a browser app, with some caveats:

• You may need to use window.waitForTimeout() to wait for Obsidian to finish processing a command, especially when tests run in CI.
• Obsidian context menus seem to be invisible to Playwright on Mac. (If you have a fix for this, please contact me!)
• Playwright's codegen command (npx playwright codegen) doesn't work; use the e2e:codegen script instead.

Helper functions for some common Obsidian actions can be found in e2e-tests/helpers.ts.

See:

• Writing tests | Playwright
• Generating tests | Playwright
• For examples: tests on one of my plugins

Hot reloading on test vaults

Run e2e:codegen. This will run ESBuild in watch mode and launch Obsidian on a fresh copy of the test vault.

[!NOTE] Changes that happen in this copy (such as editing notes or changing hotkeys and other settings) will not affect the original test vault.

To see subsequent code changes, run Reload app without saving after the build completes.

Acknowledgements

Thanks to qawatake for providing the example setup that this is based on!