# obsidian-test-mocks

[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/mnaoumov)
[![npm version](https://img.shields.io/npm/v/obsidian-test-mocks)](https://www.npmjs.com/package/obsidian-test-mocks)
[![npm downloads](https://img.shields.io/npm/dm/obsidian-test-mocks)](https://www.npmjs.com/package/obsidian-test-mocks)
[![GitHub release](https://img.shields.io/github/v/release/mnaoumov/obsidian-test-mocks)](https://github.com/mnaoumov/obsidian-test-mocks/releases)
[![Coverage: 100%](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/mnaoumov/obsidian-test-mocks)

Comprehensive test mocks for the [Obsidian](https://obsidian.md/) plugin API. Provides in-memory implementations of every class and function in `obsidian.d.ts`, plus prototype extensions Obsidian adds to DOM/JS builtins. The package is tested with **100% code coverage** (lines, branches, functions, and statements) enforced on every build.

## Installation

```bash
npm install --save-dev obsidian-test-mocks
```

Peer dependencies: `obsidian`, plus `@codemirror/state`, `@codemirror/view` and `moment`, which `obsidian` already brings into the tree. They are peers so the mocks share your project's one CodeMirror copy rather than nesting a second one.

## Entry Points

| Import path                                          | Description                                                               |
| ---------------------------------------------------- | ------------------------------------------------------------------------- |
| `obsidian-test-mocks/obsidian`                       | Mocks for every class/function in `obsidian.d.ts`                         |
| `obsidian-test-mocks/setup`                          | Exports `setup()` / `teardown()` for prototype extensions and globals     |
| `obsidian-test-mocks/vitest-setup`                   | One-stop Vitest setup file: calls `setup()` + mocks the `obsidian` module |
| `obsidian-test-mocks/jest-setup`                     | Jest setup file: calls `setup()` for prototype extensions and globals     |
| `obsidian-test-mocks/obsidian-typings/setup`         | **Deprecated no-op.** Bridging is no longer needed                        |
| `obsidian-test-mocks/obsidian-typings/vitest-setup`  | **Deprecated no-op.** Bridging is no longer needed                        |
| `obsidian-test-mocks/obsidian-typings/jest-setup`    | **Deprecated no-op.** Bridging is no longer needed                        |

## Quick start

Add the Vitest setup files — they patch prototypes/globals and mock `obsidian` automatically:

```typescript
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    setupFiles: ['obsidian-test-mocks/vitest-setup']
  }
});
```

Then build a vault in memory and exercise the code under test:

```typescript
import { App } from 'obsidian-test-mocks/obsidian';

const app = App.createConfigured__({
  files: {
    'notes/daily/2024-01-01.md': '# New Year'
  }
});
```

## Documentation

The full documentation — guides plus the complete, searchable **API reference** generated from the
library's TSDoc — is published at
[mnaoumov.dev/obsidian-test-mocks](https://mnaoumov.dev/obsidian-test-mocks/).

- [API reference](https://mnaoumov.dev/obsidian-test-mocks/api/)
- [Getting Started](https://mnaoumov.dev/obsidian-test-mocks/guides/getting-started/)
- [Test Runner Setup](https://mnaoumov.dev/obsidian-test-mocks/guides/test-runner-setup/)
- [Importing the Mocks](https://mnaoumov.dev/obsidian-test-mocks/guides/importing-mocks/)
- [Creating Mock Instances](https://mnaoumov.dev/obsidian-test-mocks/guides/creating-mocks/)
- [Strict Mocks](https://mnaoumov.dev/obsidian-test-mocks/guides/strict-mocks/)
- [Type Bridging](https://mnaoumov.dev/obsidian-test-mocks/guides/type-bridging/)
- [Using with `obsidian-typings`](https://mnaoumov.dev/obsidian-test-mocks/guides/obsidian-typings/)
- [Design Principles](https://mnaoumov.dev/obsidian-test-mocks/guides/design-principles/)

## See also

[My other Obsidian resources](https://mnaoumov.dev/obsidian/)

| Library | Features | How `obsidian-test-mocks` differs |
| --- | --- | --- |
| [`jest-environment-obsidian`](https://github.com/community-archive/jest-environment-obsidian) | Jest environment and preset; shims the `obsidian` module; reimplements Obsidian's prototype extensions; warnings for unsupported usage | Same goal as `jest-environment-obsidian`, which is archived at Obsidian 1.1.16: mocks the whole current `obsidian.d.ts` with in-memory behavior; supports Vitest as well as Jest; omits its warnings |
| [`obsidian-mock`](https://github.com/bobhy/obsidian-mock) | Mock classes for Obsidian's API, imported from `obsidian-mock` in place of `obsidian`; TypeScript types; test utilities | Same goal as `obsidian-mock`, which is not published on npm: published on npm; mocks the `obsidian` module itself through a setup file; adds Obsidian's prototype extensions to DOM and JS builtins |
| [`obsidian-test-kit`](https://github.com/chhoumann/obsidian-test-kit) | Vitest stub aliased as `obsidian`; jsdom polyfills for DOM helpers, `moment`, globals and animations; `@testing-library/jest-dom` matchers; stub loads in a `node` environment | Same goal as `obsidian-test-kit`: mocks every `obsidian.d.ts` member, with an in-memory vault, metadata cache and workspace; supports Jest as well as Vitest; omits its matchers and its DOM-free `node` stub |

Last searched for similar libraries on 2026-11-04.

## Changelog

All notable changes to this project will be documented in the [CHANGELOG](./CHANGELOG.md).

## Support

<!-- markdownlint-disable MD033 -->

<a href="https://www.buymeacoffee.com/mnaoumov" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="60" width="217"></a>

<!-- markdownlint-enable MD033 -->

### Filing an issue (for AI agents and humans)

Open issues through the [issue forms](https://github.com/mnaoumov/obsidian-test-mocks/issues/new/choose), not as blank issues.

Filing from the CLI or the API (`gh issue create --body`, or an AI agent filing for you) skips the form, and `gh issue create --template` cannot load an issue form. In that case, open the matching form in [`.github/ISSUE_TEMPLATE/`](https://github.com/mnaoumov/obsidian-test-mocks/tree/HEAD/.github/ISSUE_TEMPLATE), copy every field as a `### <label>` heading in the form's order, and fill in each one. Always state the version you used and your operating system.

## License

© [Michael Naumov](https://github.com/mnaoumov/)
