Skip to content

Developer Testing and Examples

Vivek Sarin edited this page Nov 18, 2026 · 4 revisions

Testing and examples

FlowMotion uses Vitest for unit tests and WebdriverIO for end-to-end tests inside Obsidian desktop. Example files support visual checks.

Running the tests

npm test

This runs vitest run once and exits. Tests live in test/; the runner reports the current test count.

Run the type checker as well. It is a separate step, and the tests do not check types:

npm run typecheck

Test files

File What it covers
test/core.test.ts The YAML parser (examples, malformed input, unknown references, cycles, limits) and the scheduler (order, determinism, parallel branches, branch selection)
test/text.test.ts The text format: Mermaid flowchart and sequence syntax, PlantUML, %% @ directives, line numbers in errors, and the linter
test/kinds.test.ts Activity, state, class, ER, and mind map diagrams, and the static rendering of every kind
test/static.test.ts Text and YAML features: shapes, line styles, nested subgraphs, classDef and style precedence, unsafe colours, and layout
test/story.test.ts The hindsight storyboard: beats, captions, rows, the static and animated output, and the header and footer options
test/schema.test.ts The editor lint (misspelled keys, enum values, references, YAML syntax, storyboards) and completion
test/render.test.ts Layout without overlap, packets inside the view box, id namespacing for several diagrams, escaping, and declarative animation for SVG export
test/drawio.test.ts Importing draw.io files (plain, compressed, and SVG), the editor glue, and the overlay on a draw.io SVG
test/runtime.test.ts Mounting and destroying a diagram with standard DOM APIs
test/plugin-load.test.ts Plugin load/unload and opening settings with the test Obsidian API
test/settings.test.ts Settings definitions, add-on toggles, unavailable-file notices, failed status checks, and numeric speed persistence
test/release.test.ts Release-tag, manifest, version-map, and required-artifact validation

The draw.io tests use two fixtures in test/fixtures/: devops.drawio (an mxfile document) and devops-saved.drawio.svg (the same drawing saved as an SVG).

End-to-end tests in Obsidian

Run either command from the repository root:

make test-e2e
npm run test:e2e

These are equivalent. Each builds the plugin, then runs wdio.conf.mts with wdio-obsidian-service and Mocha. The service downloads Obsidian and ChromeDriver as needed into the ignored .obsidian-cache/ directory. Initial setup needs network access.

The current app-version matrix is 1.4.5, 1.15.1, and latest, with up to two concurrent workers. Each entry requests installer version latest; the launcher resolves that request for the chosen app version. A pinned version and latest can resolve to the same release. The 1.4.5 entry exercises the oldest stable release tested by this suite; the manifest minimum remains 1.4.0.

Spec What it covers
e2e/specs/smoke.e2e.ts Loading the plugin and rendering a note's flowmotion block as SVG
e2e/specs/settings.e2e.ts Settings layout, defaults, toggles, dropdowns, add-on status/notices, saving to disk, restart persistence, and retrying partially written JSON

Tests use copies of e2e/vaults/simple, not your personal vault. Settings tests download and delete the draw.io add-on, so they need a network connection. A separate test mounts Monaco in Obsidian using browser files copied from its npm package. The tests do not exercise the full draw.io editor.

For a settings-only run on the latest app, build first and use the committed single-worker configuration:

npm run build
npx wdio run wdio.single.mts

For a targeted spec across the version matrix:

npm run test:e2e -- --spec ./e2e/specs/settings.e2e.ts

Platform setup

  • macOS: the shared configuration puts /usr/bin first in the test process's PATH. DMG extraction needs Apple's xattr -cr, not Python's command of the same name.
  • Linux: the GitHub workflow installs Xvfb and desktop libraries, then runs xvfb-run -a npm run test:e2e. See Releases and CI.
  • Windows: the service supports desktop Obsidian, but the project's CI runs on Linux.

Maintaining the settings tests

  • Newer Obsidian versions can open Settings in a separate window. Switch to that window for controls and back to the main window for executeObsidian.
  • A dropdown can contain a hidden measurement copy. Use select:not(.is-measuring) to select the real control.
  • Compare speed options without relying on their order; legacy Obsidian enumerates numeric option keys differently.
  • WebdriverIO element collections have asynchronous helpers. The current tests use for...of to collect text and attributes.
  • Polling saved JSON retries syntax errors and missing files, but propagates unexpected I/O errors.
  • Import browser and expect from @wdio/globals.

What still needs manual checks

  • Automated desktop coverage is limited to the cases above. Check editor interactions, the full draw.io editor, and other plugin changes in a test vault.
  • The look of the output is not checked by the tests. Check it with the example files, below.
  • Mobile is not supported (the plugin is desktop-only).

Example files

The examples/ folder holds sample inputs:

Files Kind
retain.yaml, retain-poc.yaml, recall.yaml, reflect.yaml YAML diagrams
hindsight-retain.yaml Storyboard
retain.mmd, architecture.mmd, aws.mmd, c4.mmd, class.mmd, er.mmd, gantt.mmd, mindmap.mmd, shapes.mmd, state.mmd Text format (Mermaid style)
activity.puml, component.puml, gantt.puml Text format (PlantUML style)

The YAML and storyboard examples are rendered by npm run examples. See Exporting diagrams. The text examples are not part of that script. Render them with scripts/render-one.ts.

Adding a test

  1. Find the file for the area you changed, from the table above.
  2. Add a test that fails before your change and passes after it.
  3. Run npm test.
  4. If the test needs a new input, put the input in test/fixtures/, not in the test itself.

For Obsidian UI or persistence changes, add or update an E2E case and run npm run test:e2e.

A test for a new diagram kind goes in test/kinds.test.ts. A test for a new field goes in test/schema.test.ts, and in the test file for the parser that reads it.

Checking a change by eye

  1. Run npm run build.
  2. Run npm run examples.
  3. Open out/preview.html in a browser, and play each diagram.
  4. Compare the result with the output from before your change, if you have it.

Related pages

Clone this wiki locally