An Obsidian plugin that lets users define, manage, execute, and document end-to-end tests directly inside their vault — combining Use Cases, Gherkin specifications, test suites, Playwright execution, evidence, and CI/CD into a single Markdown-native, local-first workflow.
Status: V1 released (1.0.0) — distributed via GitHub releases + BRAT (see Installation). The product direction is captured in the PRD. Implemented: EPIC-001/002 (Foundation & Initialization) — the layered plugin skeleton, settings service + UI, and the Initialization Wizard; EPIC-003 (Test Runner) — generating, installing, validating, and repairing the self-contained
.testrunnerproject; EPIC-004 (Use Case Management) — Use Case creation, indexing, explorer, and detail view; EPIC-005 (Specification Management) — Gherkin Feature generation, validation, missing-step detection, and step-definition generation; EPIC-006 (Test Suite Management) — tag-expression suites with a live suite explorer; EPIC-007 (Test Execution) — streaming runs with cancel/re-run in the Test Console; EPIC-008 (Reporting & Evidence) — report import, Evidence notes, and the Evidence Explorer over the partitioned run history; EPIC-009 (Dashboard) — KPI roll-up, quick actions, and recent runs; and EPIC-010 (CI/CD) — GitHub Actions workflow generation and CI-readiness checks.Beyond V1: the generated
.testrunnernow runs playwright-bdd (bddgen+@playwright/test) instead of cucumber-js (ADR-0021), and a PRD hierarchy (Domain → PRD → Use Case, ADR-0026) sits above Use Cases — a PRDs explorer, a dashboard roadmap, and a PRD Builder, with each Use Case linked to a parent PRD.
The plugin is distributed via GitHub releases and installed with BRAT (Beta Reviewer's Auto-update Tool). Submission to the Obsidian community marketplace is deliberately deferred — this repository is the source of truth.
- Install BRAT from the Obsidian community plugin store and enable it.
- In BRAT: Add beta plugin → enter
Luis85/specorator-testrunner— BRAT installs the latest release. - Enable Specorator Testrunner under Settings → Community plugins.
BRAT checks for new releases (on startup; configurable in BRAT's settings) and
updates the plugin automatically. The plugin is desktop-only (it spawns Node
child processes to run tests; see
What this plugin does on your machine).
Requires Obsidian 1.13+, and Node.js and npm available on your PATH for the
test runner.
The Test Hub is designed so a non-technical user can run the whole requirements-to-evidence loop without the command palette. Power users keep every command, but each one is also reachable through a view:
- Dashboard (home/hub). Lands on a quick-action bar (New Use Case / New Test Suite, Run all / Run demo, Generate documentation, and Open the explorers), an active-environment badge with a one-click switcher, KPI tiles, and recent runs that link straight to their Evidence note. Before the vault is initialized it shows a single prominent Initialize Test Hub call to action. The dashboard's PRDs & roadmap section surfaces the root product vision, its sub-PRDs, and per-PRD Use Case counts, with New PRD and a jump into the PRDs explorer.
- PRDs. A PRDs explorer (the Test Hub's Plan section) renders the Domain → PRD → Use Case tree; the PRD Builder (New PRD) walks through domains, research, vision, scope in/out, and assigning Use Cases. Each Use Case links to a parent PRD via its Parent PRD field in the create/edit modals.
- Use Case detail. Opening a Use Case shows its Feature Specifications with per-Feature Open / Run / Validate / Detect missing steps / Generate step definitions actions (results render inline), a Generate Feature button, and Run Use Case — the full spec-to-run authoring workflow in one place.
- Test Console. A toolbar with Cancel run (enabled only while a run is active), Re-run, and Clear, plus a live elapsed timer and the run's scope, over the streaming output.
- Guided Tour. A right-sidebar checklist that teaches the full loop by doing: each step explains why it matters, offers the real action button and copy-paste snippets, and completes by itself (via domain events) when the user performs the action — ending with a self-authored greeting test run green. Reachable via Open guided tour, the wizard's success screen, and a dashboard call to action.
- Settings. A System under test section to add/remove environments and edit their base URL and credential variables (validation errors shown inline), plus Validate environment, Repair installation, Generate CI workflow, and Check CI readiness with inline result checklists.
Story Maps are an upstream-design overlay alongside PRDs (see Vault layout). The fast path from a blank map to a working board:
- Create a map with New Story Map (the Test Hub's Plan section → New Story Map). Creation auto-seeds the reserved root PRD-000 if no PRD resolves yet, so it completes from a fresh vault.
- The board opens for the new map — the board is the primary working surface (the explorer row's title click reopens it).
- Add cards with the per-cell + card affordance (revealed on cell hover); hover an existing card to edit its attributes, cycle its color, set its planning status, or remove it.
- Arrange by dragging cards and headers to move and reorder, and double-click any header or card to rename it inline.
- Promote a card to a Use Case from the card editor: it creates the UC, anchors it to the map's product, and sets the card's reference in one step.
- The managed Markdown tables stay in sync with the note's frontmatter; after
hand-editing the
cards/productfrontmatter, run Refresh tables on the explorer row to regenerate them.
Enable teams to transform requirements into executable specifications and continuously verify software quality without leaving Obsidian:
Requirements → Specification → Automation → Execution → Evidence → CI
The plugin acts as a Business-Driven Development (BDD) workbench where product owners, business analysts, QA engineers, developers, and delivery managers collaborate on Markdown artifacts that are git-friendly and CI-ready.
| ID | Principle | Description |
|---|---|---|
| P1 | Markdown First | All business artifacts are Markdown. |
| P2 | Local First | Everything runs locally. |
| P3 | Git Friendly | All artifacts are version controllable. |
| P4 | CI Ready | Generated assets execute without Obsidian. |
| P5 | Zero Configuration | Users can get started immediately. |
Obsidian Plugin
│
├── Dashboard
├── Use Case Management
├── Specification Management
├── Test Suite Management
├── Runner Management
├── Report Viewer
└── Documentation
│
▼
.testrunner
├── Playwright
├── playwright-bdd
├── TypeScript
├── Reports
├── Screenshots
└── Traces
The Obsidian plugin authors and orchestrates. The .testrunner folder in the
vault holds a self-contained Node project that runs Playwright with playwright-bdd
(bddgen + @playwright/test) and can also be executed standalone from CI.
To run end-to-end tests locally, this plugin does a few things beyond editing Markdown. They are disclosed here in line with Obsidian's Developer Policies:
- Spawns external processes. The plugin invokes
npm,npx, andnode(withshell: false, never through a shell) to install dependencies, install the browser, validate the environment, and run your tests. These executables must already be available on your system. - Downloads software over the network. Installing the runner downloads npm
packages (Playwright, playwright-bdd,
@playwright/test, and their dependencies) and a Chromium browser viaplaywright install. This is the only network activity and it happens only when you trigger an install/repair; the plugin itself does not phone home. - Writes files outside the Obsidian vault index. It creates and maintains a
.testrunner/project folder (the self-contained Node test project) and, when you generate CI, a.github/workflows/file. These live inside your vault directory but are dot-folders that Obsidian does not index. Everything written is local and version-controllable; nothing leaves your machine except the package/browser downloads above.
Vault
├── Test Hub
│ ├── Dashboard.md
│ ├── Getting Started.md
│ ├── User Manual.md
│ └── Troubleshooting.md
├── PRDs
│ └── PRD-000-product-vision
├── Story Maps
├── Domains
├── Use Cases
├── Specifications
│ └── features
├── Test Suites
├── Test Evidence
└── .testrunner
PRDs form a hierarchy above Use Cases: the root product vision (PRD-000)
decomposes into feature-scoped sub-PRDs, each owning the Use Cases that detail
its solution. Open the Test Hub's Plan section to navigate the PRD tree, and
use New PRD to launch the builder. See
docs/adr/0026-prd-hierarchy-artifact-model.md for the model.
Story Maps (Story Maps/) are an upstream-design overlay alongside PRDs,
not inside the tree: a vault-local, single-user user-story map (audience →
backbone activities → steps → release slices) over rich cards that reference Use
Cases by id. Open the Test Hub's Plan section and use
New Story Map to launch the builder; add cards via a map's Cards
action. See docs/adr/0027-story-map-prd-sibling-overlay.md and
docs/adr/0028-story-map-rich-model.md.
.
├── manifest.json # Obsidian plugin manifest
├── versions.json # Plugin version → minAppVersion map
├── package.json # Plugin build + typecheck scripts
├── tsconfig.json # TypeScript config (strict)
├── vitest.config.ts # Vitest config (coverage gates per NFR-002)
├── eslint.config.mjs # ESLint flat config (incl. layer-boundary rules)
├── esbuild.config.mjs # esbuild bundler config
├── styles.css # Plugin styles
├── src/
│ ├── main.ts # Plugin entry point / composition root
│ ├── domain/ # Entities, value objects, policies, events, settings
│ ├── application/ # Services, ports, generated-content templates
│ ├── infrastructure/ # Obsidian, Node fs, child-process, runner adapters
│ ├── presentation/ # Views, modals, settings tab, commands
│ └── shared/ # Result, errors, EventBus, logging, utils
├── tests/ # Vitest unit + integration suite (incl. __stubs__)
├── scripts/ # test-build.mjs, e2e-smoke.mjs (+ entry)
├── CONTEXT.md # Glossary (per grill-with-docs skill)
├── docs/
│ ├── Specorator Testrunner.md # Product Requirements (source of truth)
│ ├── architecture/
│ │ ├── Solution Design.md # Architecture of record
│ │ ├── Building Block View.md # Arc42 §5 building blocks
│ │ ├── Runtime View.md # Arc42 §6 runtime scenarios
│ │ ├── Technical Interface Specification.md # TypeScript contracts
│ │ └── Event Catalog.md # V1 domain event catalog
│ ├── adr/
│ │ └── 0001-*.md … 0020-*.md # Architectural decision records
│ ├── use-cases/
│ │ └── UC-001.md … UC-037.md # One note per use case (UC-025+ proposed for V2)
│ ├── issues/
│ │ ├── EPIC-001.md … EPIC-020.md # Epics (20; EPIC-013+ proposed for V2)
│ │ ├── FEAT-001.md … FEAT-032.md # Features (32; FEAT-029+ proposed for V2)
│ │ └── US-001.md … US-089.md # User stories (89; US-051+ proposed for V2)
│ ├── proposals/ # V2 research & proposal (epic/story/UC source)
│ ├── reviews/ # Consolidated review & improvement plans
│ ├── tech-debt/ # Tech-debt register (TD-NNN)
│ └── superpowers/ # Plans + specs from skill-driven sessions
├── .claude/skills/
│ ├── grill-with-docs/ # Stress-test plans against docs / glossary (mattpocock/skills)
│ ├── improve-codebase-architecture/ # Find deepening opportunities (mattpocock/skills)
│ ├── brainstorming/ # Superpowers methodology (14 skills)
│ ├── test-driven-development/
│ ├── systematic-debugging/
│ ├── writing-plans/
│ ├── executing-plans/
│ ├── subagent-driven-development/
│ ├── dispatching-parallel-agents/
│ ├── verification-before-completion/
│ ├── using-superpowers/
│ ├── writing-skills/
│ ├── requesting-code-review/
│ ├── receiving-code-review/
│ ├── finishing-a-development-branch/
│ ├── using-git-worktrees/
│ └── NOTICE-superpowers.txt # Upstream attribution + MIT license
└── .github/workflows/
├── ci.yml # Lint, format, typecheck, build, coverage
├── e2e-smoke.yml # E2E smoke over the real runner (on demand
│ # + auto-run on runner-template changes)
└── release.yml # Tag-triggered release with plugin assets
- Specorator Testrunner — Product Requirements (source of truth for scope).
- CONTEXT.md — Project glossary (used by the
grill-with-docsskill). - Solution Design — architecture, domain model, V1 architectural decisions.
- Building Block View — Arc42 §5 building blocks (views, services, adapters, runner internals).
- Runtime View — Arc42 §6 runtime scenarios with Mermaid sequence diagrams.
- Technical Interface Specification — TypeScript contracts: shared types, domain, repositories, services, ports, frontmatter schemas, runner + CI templates.
- Event Catalog — V1 domain events, envelope, EventBus contract.
Use cases live as individual notes under docs/use-cases/UC-NNN.md. Backlog items live under docs/issues/{EPIC,FEAT,US}-NNN.md. Architectural decision records live under docs/adr/NNNN-*.md. Per-domain indexes will return via Obsidian Bases once the plugin lands.
Requires Node 20+.
npm install # install dependencies
npm run dev # esbuild watch mode
npm run build # production bundle (main.js)
npm run typecheck # tsc --noEmit (src, tests, and scripts)
npm run lint # eslint (incl. layer-boundary import rules)
npm run format # prettier --write
npm run format:check # prettier --check
npm run test # vitest unit + integration suite
npm run test:watch # vitest watch mode
npm run test:coverage # vitest with v8 coverage (NFR-002: ≥ 80%)
npm run test-build # install the built plugin into a scratch vaultCI (.github/workflows/ci.yml) runs lint, format check, typecheck, build,
and the coverage-gated test suite on every push and pull request.
MIT