Testing

Crosswalker has three separate test surfaces. Know which you’re working on before picking commands.

#	Surface	Framework	When to run
1	Plugin unit tests	Jest + ts-jest	Every plugin code change
2	Plugin E2E tests	WebdriverIO + wdio-obsidian-service	Before release, after core logic changes
3	Docs E2E tests	Playwright	Every docs change (content, theme, plugins), before deploy

1. Plugin unit tests (Jest)

Unit tests use Jest with ts-jest and a minimal Obsidian API mock at tests/__mocks__/obsidian.ts. Fully headless — no Obsidian runtime required.

bun run test          # One-shot
bun run test:watch    # Watch mode

What’s tested

• CSV parser — parsing, column analysis, edge cases, streaming
• Settings data — defaults, validation
• Config manager — fingerprinting, matching (planned)
• Generation engine — output structure (planned)

Writing a unit test

Tests live in tests/ alongside the code they test:

import { parseCSV } from '../src/import/parsers/csv-parser';

describe('parseCSV', () => {
  it('parses simple CSV', async () => {
    const result = await parseCSV('Name,ID\nAlice,1');
    expect(result.rows).toHaveLength(1);
    expect(result.columns[0].name).toBe('Name');
  });
});

Lint (part of the plugin unit-test surface)

Required for community plugin submission:

bun run lint            # Check
bun run lint:fix        # Auto-fix what can be fixed

Uses eslint-plugin-obsidianmd to enforce things like sentence case for UI text, no manual createEl('h3') for settings headings, no plugin name in heading text, etc. See the contributing page for the full rule list.

2. Plugin E2E tests (WebdriverIO)

E2E tests use WebdriverIO with wdio-obsidian-service to drive a real Obsidian instance via Chrome DevTools Protocol. Tests can exercise the import wizard, navigate multi-step flows, and verify generated vault structure.

bun run e2e              # Requires Obsidian installed locally

Not run in CI currently (on the roadmap). Verifies:

• Plugin loads correctly into a fresh test vault
• Import wizard opens and all four steps render
• File generation produces expected folder structure and frontmatter
• Settings UI persists changes across reloads

See wdio.conf.mts for the config and test/e2e/ for specs.

3. Docs E2E tests (Playwright)

The docs site has a Playwright suite in docs/tests/ that runs against a built + previewed site. Catches rendering regressions, 404s, console errors, and verifies the UX/theme decisions.

Test suites

Spec	Tests	Covers
smoke.spec.ts	10	Homepage load, Nova top nav, sidebar, search, content pages (installation, features, agent-context, blog, architecture)
deployment.spec.ts	4	HTTP 200, no console errors, no failed asset requests, meta tags present
ux-fixes.spec.ts	20	Content width clamp at multiple breakpoints, narrower sidebar width, lastUpdated footer, PageTitle override (volatility badges + h1#_top accessibility anchor), smoke tests for new pages, regression checks

Running the docs tests

From docs/:

cd docs

bun run test:local       # Run all tests — auto-builds + previews + runs Chromium
bun run test:deploy      # Deployment-only subset (faster)
bun run test:e2e         # Headed mode — watch the browser
bun run test:e2e:ui      # Playwright UI mode — interactive debugging

Or via the orchestrator from the repo root:

bun run serve            # Interactive menu → option 8

Testing against the live site

Point Playwright at the production deployment instead of local preview:

cd docs
TEST_URL=https://cybersader.github.io bun run test:deploy

Prerequisites (first time only)

cd docs
bun install
bun x playwright install chromium    # Download the test browser
bun run build                          # Preview server serves from dist/

Configuration

• Config file: docs/playwright.config.ts
• Base path: /crosswalker (matches base in astro.config.mjs). All page.goto() calls must prefix this
• Preview server: auto-starts bun run preview on port 4321
• Browser: Chromium only (sufficient for docs coverage)
• Screenshots on failure: automatically captured to docs/test-results/

Writing a new Playwright test

import { test, expect } from '@playwright/test';

const BASE = '/crosswalker';

test('my new page loads', async ({ page }) => {
  await page.goto(`${BASE}/my-section/my-page/`);
  await expect(page.locator('h1')).toContainText('My Page');
});

Common pitfalls:

Issue	Fix
404 on all pages	Forgot bun run build — preview serves from dist/
Chromium not found	bun x playwright install chromium
Tailwind classes missing	Check docs/src/styles/global.css has @source directives
Base path 404s	Prefix every page.goto() with ${BASE}/
Page renders but elements missing	Check the browser console in headed mode — MDX compilation errors show up as console warnings

When to add tests here

Add to ux-fixes.spec.ts (or a new spec) when you:

• Add a new Starlight component override (like the PageTitle one)
• Change global CSS that affects layout (content width, sidebar width, figure sizing)
• Add a new page that should be part of the smoke suite
• Fix a visual regression — add a test that would have caught it

Manual testing

For things that can’t be automated (mostly plugin UI edge cases):

1. bun run serve:plugin (watch mode)
2. bun run fixtures — regenerate test fixtures into test-vault/Frameworks/NIST-mini/ (see Fixtures below)
3. Open test-vault/ in Obsidian
4. Test the import wizard with the regenerated sample data, or with custom data in test-vault/Crosswalker Test Data/
5. Check crosswalker-debug.log for detailed logs (enable in settings)
6. Use the Hot Reload plugin for faster iteration — no need to toggle the plugin on/off for each rebuild

Manual test documents live in test-vault/Crosswalker Test Docs/ for workflows that need guided human verification.

Fixtures

Test fixtures are generated by a TS script in tools/. Source CSVs are committed; the script reads a CSV and emits Tier 1 markdown notes into the test vault. This gives reproducible, version-controlled test data without committing the generated markdown.

Why a generator (not just committed markdown)

Three options were considered:

1. Commit pre-generated markdown — fragile when the Tier 1 schema evolves
2. Build a fixtures-generating Obsidian plugin — over-engineered (test infrastructure shouldn’t itself need to be a plugin in a vault)
3. TS generator script in tools/ — what we landed on

Option 3 keeps fixtures deterministic (committed CSV + versioned script → identical markdown across machines), regenerable (rerun the script when the schema changes), and out of node_modules-style “infrastructure repo” sprawl.

Layout

tools/
├── generate-fixtures.ts           # CLI — bun run fixtures
├── fixtures/
│   ├── synthetic/                 # Hand-authored sample CSVs (committed)
│   │   └── nist-mini.csv          # 8 controls (AC + AU families)
│   └── seeds/                     # (Future) deterministic seeds for parameterized generation
└── README.md                      # Usage + future shape

test-vault/
└── Frameworks/
    └── NIST-mini/                 # ← generator output target

Usage

# Default: regenerate the canonical NIST-mini fixture into test-vault/
bun run fixtures

# Custom run with explicit args
bun tools/generate-fixtures.ts \
  --source tools/fixtures/synthetic/your-csv.csv \
  --target test-vault/Frameworks/Custom \
  --ontology your-slug \
  --clean

Each row becomes one <id>.md file. Frontmatter conforms to spec/tier1.schema.json — curie, title, aliases, tags, domain-specific fields, plus a full _crosswalker provenance block.

Future: marketplace-driven fixtures

Once the community marketplace pattern lands, the generator gains a --from-bundle <id> mode that pulls a published Tier 1 bundle and drops it into the target vault. That makes published bundles a real fixture source — your tests run against the same bytes a user would download.

What the generator does NOT do (yet)

• Doesn’t implement the full Ch 22 recipe grammar (folder/heading/tag/wikilink mechanism composition). That’s the v0.1 render() engine — separate work
• Doesn’t generate crosswalk edges between frameworks. Add a second source CSV + second bun run fixtures invocation when you need that
• Doesn’t produce junction notes (evidence links). Add hand-authored junction notes to test-vault/ when needed

What to run before a PR

Matrix by change surface:

You changed	Minimum tests
Plugin TypeScript code	bun run test + bun run lint
Plugin UI (settings tab, modals)	Above + manual test in Obsidian against fresh fixtures (bun run fixtures)
Plugin core logic (parser, generation)	Above + bun run e2e if you can run it locally
tools/generate-fixtures.ts or tools/fixtures/synthetic/*.csv	bun run fixtures succeeds + spot-check generated markdown opens cleanly in Obsidian + _crosswalker block validates against spec/tier1.schema.json
spec/tier1.schema.json or spec/recipe.schema.json	bun run fixtures (the generated frontmatter must still validate) + bump $id if breaking
docs/ content (.mdx)	cd docs && bun run test:local
docs/ theme / CSS / components	Above + visually verify in bun run serve:docs at multiple viewport widths
Both plugin and docs	All of the above

CI

• Docs deploy: .github/workflows/deploy-docs.yml runs on push to main, builds docs and publishes to GitHub Pages
• Plugin release: manual via bun run version + tagged release

E2E tests (both plugin WebdriverIO and docs Playwright) are not currently run in CI — on the roadmap. Run them locally before PRs that touch areas they cover.