Writing Unit Tests

Writing unit tests in Trilium

Trilium is a pnpm monorepo tested with Vitest (v8 coverage). This skill captures the patterns that actually work here, plus the footguns that waste time. Read the per-layer reference file for the area you're touching.

First principle: prefer extracting pure logic

The dominant, lowest-risk pattern across this repo is extract the decision/transform logic out of a component/widget/route into a top-level export function that takes plain inputs and returns a plain value, then test that function. Rendering and side effects stay thin; the logic gets covered cheaply. apps/client/src/widgets/ribbon/FormattingToolbar.tsx (getFormattingToolbarState, tested in FormattingToolbar.spec.ts) is the canonical example. Reach for rendering/integration only when the behavior is the DOM/HTTP.

Also follow CLAUDE.md: write concise tests (group related assertions in one it, don't make one test per trivial passthrough), and when you add pure business logic, extract + unit-test it.

Which technique? (decision tree)

Specialized harnesses (owned by sibling skills)

Some layers have a purpose-built spec harness documented in the skill that owns the feature — route there instead of re-deriving it:

Running tests

Run the narrowest thing that covers the change, and never the full suite. pnpm test:all, test:parallel, test:sequential and pnpm coverage take minutes and are CI's job — reach for one only if the user asks. Never run ESLint either (pnpm dev:linter-check/-fix, npx eslint): it currently dies out-of-memory, so a run costs minutes and tells you nothing. Typecheck with pnpm typecheck (never a raw tsc -p/tsc -b, which misses the project references) — cheaper than a suite, but not instant, so run it once a change is finished rather than after every edit.

• Filtered (preferred): pnpm --filter <pkg> test <path-or-pattern> — the trailing argument is a substring filter over spec paths, so pnpm --filter server test special_notes runs every match.
• Whole package: pnpm --filter <pkg> test (e.g. @triliumnext/client, @triliumnext/server, @triliumnext/commons).
• Single file (server): pnpm --filter server test spec/etapi/search.spec.ts
• Single file (client): pnpm --filter @triliumnext/client exec vitest run src/widgets/react/Button.spec.tsx
• Coverage: append --coverage.
• Server tests run sequentially (shared DB, pool: "forks", fork isolation is per file). Client/package tests run in parallel.

Windows/sandbox note: any pnpm --filter … invocation — exec vitest and the package's own test script alike — can trigger a pnpm auto-install that hits EPERM/Access is denied on a node_modules directory VS Code holds open (it rolls back, but the run is lost). If so, run the hoisted binary directly (it lives in the repo-root node_modules): CI=true node node_modules/vitest/vitest.mjs run <spec> --root apps/client, or node_modules/.bin/vitest.CMD run <spec> --root apps/<app>.

Coverage config rules (Vitest 4)

Each project's test config (vite.config.* / vitest.config.*) measures coverage honestly via:

coverage: {
    provider: "v8" as const,
    include: ["src/**/*.{ts,tsx}"],            // makes UNTESTED files count too
    exclude: ["**/*.{test,spec}.{ts,mts,cts,tsx,js,jsx}", "**/*.d.ts"],
    reporter: ["text", "lcov"]
}

• Do NOT use all: true — it was removed in Vitest 4 and is a type error; include already pulls in untested files.
• If a config sets Vite root: "src" (e.g. apps/standalone), coverage include globs resolve relative to src, so use ["**/*.{ts,tsx}"], not ["src/**/…"].
• Files outside the project root need coverage.allowExternal: true. v8 defaults it to false, which silently drops every out-of-root file — so an include glob alone (e.g. ../../packages/trilium-core/src/**) is ignored and contributes nothing. trilium-core has no runner of its own; its coverage is measured through apps/server and apps/standalone, and both must set allowExternal: true plus a core glob in coverage.include whose ../ depth matches that suite's root: ../../packages/trilium-core/src/** for server (root apps/server), ../../../packages/trilium-core/src/** for standalone (root apps/standalone/src). Without allowExternal core never reaches the lcov or Codecov. The lcov writes these as ../…/packages/… paths; codecov.yml's fixes: entries strip the ../ so they map onto the repo tree.
• For provably-unreachable defensive branches, mark them with /* v8 ignore next */ / /* v8 ignore start */…/* v8 ignore stop */ and a one-line reason — don't delete the guard or write a fake test. /* v8 ignore next */ does not reliably suppress a branch sitting on a } else if (…) { line — use the start/stop form there. Better still, check whether the arm is dead because the code can be simplified: a trailing else if (name) { … } return [] where name is provably truthy collapses to a direct return, removing the branch honestly instead of hiding it. Project style is a plain /* v8 ignore next -- reason */ — no @preserve.
• Checking one file's coverage: the v8 text reporter crashes (PARSE_ERROR while remapping unrelated uncovered core files) on single-spec --coverage runs. Produce lcov/json/json-summary instead and parse it with the analyzing-coverage skill's coverage.mjs (… summary for pct/aggregate, … gaps --filter <file> for the uncovered line list). The full-suite text report (run over a directory) is fine. Don't hand-roll a coverage parser — that script already handles all three formats and the Windows footguns.