Run npm run test:unit -- --coverage for the current test-file/test-pass
counts and coverage percentages. Coverage is enforced via Vitest thresholds in
vitest.config.mjs (currently lines 55, branches 45, functions 50) and
should be treated as a ratcheted floor, not just a report — see the Coverage
Gate section in CONTRIBUTING.md for the ratchet rules.
This project relies heavily on Test-Driven Development (TDD) to maintain stability, especially when integrating with Obsidian's DOM and managing complex background parsing.
We follow the standard TDD cycle:
- Red: Write a failing test first. If fixing a bug, write a test that reproduces the bug.
- Green: Write the minimum amount of code necessary to make the test pass.
- Refactor: Clean up and optimize the implementation, secure in the knowledge that your tests will catch regressions.
Our tests live in the test_files/unit/ directory. Historically, tests were kept in a flat directory structure. Moving forward, all tests should be organized into folders mirroring the src/ directory.
test_files/unit/services/: For core business logic (e.g., parsers, state managers, background sync).test_files/unit/views/: For UI tests and DOM interaction logic (e.g., dashboard, podcast-player, reader-view).test_files/unit/utils/: For standalone helper functions (e.g., date formatting, validation).test_files/unit/components/: For reusable isolated UI components and Obsidian modals.
Note: Grouping tests by feature or module makes it much easier to maintain the suite and understand coverage.
A test that pins current behavior before a refactor, bugs included, is named *.characterization.test.ts and lives in the same folder as the module's other tests. Mark each pinned bug with // BUG: pinned, see #<issue>. CI keeps these files read-only on refactor/* pull requests; see Characterization tests in the architecture guardrails.
- Feed Parser (
test_files/unit/services/feed-parser.test.ts): Validates RSS/Atom/JSON parsing, encoding detection, and URL conversion. - Article Saver (
test_files/unit/services/article-saver.test.ts): Validates markdown generation, template variables, and vault persistence. - OPML Manager (
test_files/unit/services/opml-manager.test.ts): Validates import/export and folder merging. - Highlight Service (
test_files/unit/services/highlight-service.test.ts): Validates regex generation and DOM-based highlighting. - Apple Podcasts Service (
test_files/unit/services/apple-podcasts-service.test.ts): Validates URL resolution, cache behavior, guard rails, and error handling for Apple Podcasts lookup. - Web Viewer Integration (
test_files/unit/services/web-viewer-integration.test.ts): Validates Web Viewer plugin integration, DOM injection, save flows, and helper behavior.
- Dashboard View (
test_files/unit/views/dashboard-lifecycle.test.ts): Validates main view orchestration, pagination, and multi-filter persistence. - Discover View (
test_files/unit/views/discover-view.test.ts): Validates feed categorization and filter state persistence.
- Sidebar (
test_files/unit/components/sidebar-core.test.ts): Validates sidebar rendering, toolbar actions, and tag filters. - Modals: Extensive coverage for feed management, OPML import, and settings modals in
test_files/unit/modals/.
Because this is an open-source project, contributors come with varying levels of familiarity with the codebase. To make tests as readable as possible:
-
Use descriptive
describeblocks: Group related functionality.describe("FeedParser - OPML Import", () => { ... })
-
Write clear
itstatements explaining behavior, not implementation:- ❌
it("calls the save function when btn is clicked") - ✅
it("persists the new feed to settings when the user submits the form")
- ❌
-
Comment complex setups: If your test requires a lot of setup (mocking Obsidian APIs, polyfills, or complex settings objects), add a one-line comment explaining why the setup is necessary.
// Polyfill the MediaElement API so the Podcast Player can simulate playback installMediaElementPolyfills();
Many of our tests go beyond strict unit testing (testing a pure function) and test the integration of our components with the DOM.
We use jsdom alongside custom polyfills (test_files/unit/test-dom-polyfills.ts) to simulate the Obsidian environment. This yields high confidence without the massive overhead of end-to-end (E2E) browser tests.
- Always clean up the DOM between tests with
document.body.empty(). - Mock file system and external network calls (e.g., using
vi.spyOn(obsidian, "requestUrl")).
- Mocking Obsidian APIs: Use the stubs in
test_files/stubs/obsidian.ts. If a required API is missing, expand the stub. - Environment: Ensure
environment: 'jsdom'is set in the test file or config if testing DOM-reliant code. - Fixtures: Keep large XML/JSON fixtures in dedicated
fixtures/files (e.g.,test_files/unit/fixtures/). - Cleanup: Always use
document.body.empty()orvi.clearAllMocks()inafterEachto ensure test independence. - Descriptive Naming: Write clear
itstatements explaining behavior, not implementation (e.g.,it("persists the new feed...")notit("calls the save function...")).
- Run all tests:
npm run test:unit - Watch mode:
npx vitest - Coverage report:
npm run test:unit -- --coverage - Tests affected by a change:
npx vitest related --run <changed files>
vitest related runs every test file whose imports reach the files you name,
including What's New notes and repository scripts. A change to a widely
imported utility can select most of the suite.
The pre-commit hook runs only the tests related to the staged files; the pre-push hook and CI run the whole suite. See Git Hooks in CONTRIBUTING.md.