A Jest environment to facilitate unit testing for Obsidian plugins.
npm install jest-environment-obsidian!Obsidian Version Supported: v1.1.16
A Jest environment to facilitate unit testing for Obsidian plugins.
> Notice:
> This project is a work-in-progress.
>
> Obsidian's API is fairly large, and it will take time to implement all of it in a test-friendly way. If some function doesn't work, please open an issue or pull request.
This package is available on the npm registry. You can install it using npm or yarn.
``bash`
npm install --save-dev jest-environment-obsidian
These are the minimum requirements that we test for. You may have luck with earlier versions of the required software, but we won't be able to provide support for it.
- NodeJS >= 15.0.0Jest
- >= 29.0.0
There are two ways to use jest-environment-obsidian in your project: for all unit tests, or for specific unit test files. If you're not sure about what you want to do, you can see our examples for inspiration.
If you want to use jest-environment-obsidian for all your unit tests, you can use jest-environment-obsidian as a preset. This will add the required setup files and module resolver.
`js`
module.exports = {
// ...
preset: 'jest-environment-obsidian',
};
If you want to provide your own configuration on top of jest-environment-obsidian's preset, we recommend using the extend function provided in our preset:
`js`
const { extend } = require('jest-environment-obsidian/jest-preset');
module.exports = extend({
setupFiles: ['...'],
});
If you only want to test a specific files under the jest-environment-obsidian environment, you can add a multi-line pragma comment at the top your unit test file:
`js`
/**
* @jest-environment jest-environment-obsidian
*/
Obsidian adds custom functions and properties to existing DOM and ECMAScript types. These have been reimplemented under jest-environment-obsidian and are available within unit tests.
The Obsidian module is automatically shimmed for you. While it's still good practice to isolate code, as long as you use jest-environment-obsidian, having import {...} from "obsidian" in source files no longer prevents unit tests from running.
As a way to help with test-driven-development and identify why certain unit tests may be failing, jest-environment-obsidian creates and prints warning messages after running tests.
Individual warnings can be disabled by adding a @obsidian-jest-ignore node-must-be-within-document pragma comment in a file. Multiple comments can be added to disable different warnings.
The test environment can be configured globally with the testEnvironmentOptions option inside your Jest config, or on a per-file basis using one of the supported doc block pragmas.
Configures how strictly the test environment tries to conform to Obsidian's implementation of its API.
When set to strict, certain functions and behaviours will work as though they were running within the real Obsidian environment. As a consequence, more boilerplate code will be needed for certain unit tests to pass.
Pragma: @obsidian-conformance "lax"
Options: , "strict" "lax"
Default:
Configures the reported apiVersion inside the obsidian module.
Pragma: @obsidian-version string
Options: 1.1.16
Default:
Disables printing of specific warning messages.
Pragma: @obsidian-jest-ignore []
Options: A string array of warning IDs, or a single string ID if within a pragma comment.
Default:
Changes how jest-environment-obsidian handles missing exports from shimmed modules.
By default, a warning will be emitted to let you know that your tests may behave unexpectedly.
Options: "warning", "error", "undef" "warning"`
Default:
Want to help out? Check out the contributing guide!