Repository navigation
Developer Testing and Examples
FlowMotion uses Vitest for unit tests and WebdriverIO for end-to-end tests inside Obsidian desktop. Example files support visual checks.
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
| 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).
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
-
macOS: the shared configuration puts
/usr/binfirst in the test process'sPATH. DMG extraction needs Apple'sxattr -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.
- 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...ofto collect text and attributes. - Polling saved JSON retries syntax errors and missing files, but propagates unexpected I/O errors.
- Import
browserandexpectfrom@wdio/globals.
- 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).
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.
- Find the file for the area you changed, from the table above.
- Add a test that fails before your change and passes after it.
- Run
npm test. - 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.
- Run
npm run build. - Run
npm run examples. - Open
out/preview.htmlin a browser, and play each diagram. - Compare the result with the output from before your change, if you have it.
© 2026 @vrsarin. FlowMotion documentation.