---
name: plugin-testing
description: Skill for testing Obsidian plugin features in this repository. Use for automated, manual, and integration test workflows specific to Obsidian plugins.
---

# Plugin Testing Skill

> **Note:** Always prefer `bun` over other package managers if possible. Use `bun` for all commands unless you have a specific reason to use another package manager.

Use this skill to guide both automated and manual testing of Obsidian plugin features. Ensure all tests reflect real plugin usage and production-like conditions.

## Key Testing Principles

- Always build the plugin before testing (`bun run build`).
- Use the install script to deploy to a test vault (`bun run obsidian:install <vault>` preferred).
- Helpful scripts for testing:
  - `bun run build` — build before running tests or manual testing
  - `bun run obsidian:install <vault>` — install the built plugin into a test vault
  - `bun run format` — format code before testing if needed
  - `bun run check` — run lint & formatting checks
- Test settings UI for load, save, and persistence.
- Validate localization for all supported languages.
- Confirm plugin lifecycle events (load/unload) work as expected.

## Test File Conventions

- `*.spec.{ts,js,mjs}` — **Unit tests (BDD-style)**: focus on behaviour and small, isolated units. Prefer tests that are fast and hermetic.
- `*.test.{ts,js,mjs}` — **Integration tests (TDD-style)**: focus on integration between components or with the environment; keep them well documented and isolated.

Run unit-only suites with the Vitest CLI:

```shell
bun x vitest run "tests/**/*.spec.{js,ts,mjs}" --coverage
```

And integration-only suites with:

```shell
bun x vitest run "tests/**/*.test.{js,ts,mjs}" --coverage
```

## Test File Structure

- Follow a **one test file per source file** rule: mirrors the source directory tree under `tests/` (for both `*.spec.*` and `*.test.*`). Prefer a single test file per source (either a `*.spec.*` unit test or a `*.test.*` integration test). If a source requires both unit and integration coverage, having both a `*.spec.*` and a `*.test.*` file is acceptable — treat them together as the logical "one test file" for that source and keep their locations aligned for discoverability.
- Keep names aligned with source files for discoverability: `src/path/to/module.js` -> `tests/unit/path/to/module.spec.js`.
- If a test file would become unreasonably large, splitting is allowed but should be a rare exception; include a brief header comment explaining the reason and the mapping across split files.

For the full list and usage of scripts, see the **Scripts (package.json)** section in `AGENTS.md`.

## Example Test Workflow

1. **Build:**
    - Run: `bun run build`
2. **Install:**
    - Run: `bun run obsidian:install <vault directory>`.
3. **Settings UI:**
    - Open plugin settings in Obsidian
    - Change and save settings; reload plugin and verify persistence
4. **Localization:**
    - Switch Obsidian language; verify all UI text updates accordingly
5. **Lifecycle:**
    - Reload or disable/enable the plugin; ensure all managers register/unload cleanly

## References

- See [src/main.ts](../../../src/main.ts) for plugin entry and lifecycle
- For integration, ensure settings and localization are loaded as in production