Skip to content

Validate versioned Obsidian E2E targets #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vrtmrz merged 1 commit into from
Aug 11, 2026
Merged

Validate versioned Obsidian E2E targets #46

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,11 @@ The workspace root pins `@emnapi/core` and `@emnapi/runtime` because npm can oth
When a local Obsidian executable and CLI are available, also run:

```bash
npm run test:e2e:obsidian:local-suite
npm run test:e2e:obsidian:validated
```

The validated suite uses the reviewed Obsidian release catalogue and rejects the unverified-version override. A passing run with `E2E_OBSIDIAN_ALLOW_UNVERIFIED_VERSION=true` is useful for an early regression probe, but it is not release-qualification or supported-version evidence.

## UI automation

Follow [the UI automation guide](packages/obsidian-plugin-kit/docs/ui-automation.md). Scripted responses must remain instance-scoped and must not be enabled through production settings, URI parameters, or other external input.
Expand Down
4 changes: 3 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,11 @@ Real Obsidian E2E remains a local-only suite and is not a default CI gate:

```bash
npm run test:e2e:obsidian:install-appimage
npm run test:e2e:obsidian:local-suite
npm run test:e2e:obsidian:validated
```

The managed Linux workflow defaults to the reviewed Obsidian 1.13.6 assets, verifies their SHA-256 digests, and keeps each version and architecture in a separate directory. `E2E_OBSIDIAN_VERSION` selects another reviewed version. An exact version outside the reviewed catalogue requires `E2E_OBSIDIAN_ALLOW_UNVERIFIED_VERSION=true` and is reported only as an unverified regression probe; it is deliberately rejected by `test:e2e:obsidian:validated`.

## Installation

Install only the packages that a project needs. The commands below use npm's normal compatible version ranges. For the current `0.x` versions, those ranges accept patch releases but not the next minor release. Commit the lockfile for repeatable installations; add `--save-exact` when every dependency upgrade must be reviewed explicitly, including release qualification:
Expand Down
2 changes: 2 additions & 0 deletions docs/proven-in-use.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ The projects use four complementary levels of verification:
3. Consumer tests exercise application policy through narrow injected capabilities rather than reproducing Obsidian or browser behaviour.
4. Real-Obsidian E2E and guided device review cover the rendering, process, Electron, Vault, and mobile boundaries which mocks deliberately do not own.

Repository-owned real-Obsidian runs record the API version observed from the active Vault renderer. Release-qualification runs accept only versions and AppImage digests in the reviewed catalogue. An explicitly enabled run against another exact public release remains an unverified regression probe, even when every scenario passes.

## TagFolder

[TagFolder](https://github.com/vrtmrz/obsidian-tagfolder) uses the Obsidian UI and Vault adapters at its plug-in composition root. Its [new-note workflow](https://github.com/vrtmrz/obsidian-tagfolder/blob/main/new-note-workflow.ts) narrows those adapters to the selection, text, and frontmatter methods required by that operation. The corresponding [App-free tests](https://github.com/vrtmrz/obsidian-tagfolder/blob/main/tests/new-note-workflow.test.ts) script template selection, inspect Vault transcripts, inject write failures, and verify rollback without constructing an Obsidian `App`.
Expand Down
5 changes: 3 additions & 2 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@
"release:prepare:harness": "npm run check:harness && npm run build:harness && node scripts/prepare-harness-release.mjs",
"verify:packed-consumer": "node scripts/verify-packed-consumer.mjs",
"verify:workspace": "npm run check:workspace && npm run test:workspace && npm run build:workspace && npm run build:harness && npm run pack:workspace && npm run verify:packed-consumer",
"test:e2e:obsidian:install-appimage": "tsx test/e2e-obsidian/scripts/install-appimage.ts",
"test:e2e:obsidian:install-appimage": "npm run build --workspace @vrtmrz/obsidian-test-session && tsx test/e2e-obsidian/scripts/install-appimage.ts",
"test:e2e:obsidian:smoke": "npm run build:harness && tsx test/e2e-obsidian/scripts/smoke.ts",
"test:e2e:obsidian:session-lifecycle": "npm run build --workspace @vrtmrz/obsidian-test-session && tsx test/e2e-obsidian/scripts/session-lifecycle.ts",
"test:e2e:obsidian:profile-restart": "npm run build:harness && tsx test/e2e-obsidian/scripts/profile-restart.ts",
Expand All @@ -50,7 +50,8 @@
"test:e2e:obsidian:contracts": "npm run build:harness && tsx test/e2e-obsidian/scripts/contracts.ts",
"test:e2e:obsidian:progress": "npm run build:harness && tsx test/e2e-obsidian/scripts/progress.ts",
"test:e2e:obsidian:mobile": "npm run build:harness && tsx test/e2e-obsidian/scripts/mobile.ts",
"test:e2e:obsidian:local-suite": "tsx test/e2e-obsidian/scripts/local-suite.ts"
"test:e2e:obsidian:local-suite": "npm run build --workspace @vrtmrz/obsidian-test-session && tsx test/e2e-obsidian/scripts/local-suite.ts",
"test:e2e:obsidian:validated": "npm run build --workspace @vrtmrz/obsidian-test-session && tsx test/e2e-obsidian/scripts/local-suite.ts --validated"
},
"devDependencies": {
"@emnapi/core": "1.11.2",
Expand Down
5 changes: 4 additions & 1 deletion packages/obsidian-test-session/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,8 @@ import {

Executable discovery is implemented for Linux, macOS, and Windows. This project exercises complete real-Obsidian sessions on Linux and macOS; Windows discovery exists but the end-to-end workflow remains unverified. Automated AppImage download and optional `xvfb-run` wrapping are Linux-specific.

Managed Linux sessions default to the reviewed Obsidian 1.13.6 AppImage. The package keeps an immutable catalogue of reviewed asset names and SHA-256 digests, installs each version and architecture separately, and never downloads during executable discovery or session start-up. An exact version outside that catalogue is rejected unless the caller deliberately enables an unverified regression probe. A passing unverified probe does not establish supported-version status.

On macOS, isolated sessions use a socket-safe root below `/tmp` and Chromium's test-only mock keychain so the CLI socket and system keychain dialogue do not block start-up. See the usage guide before replacing the complete default launch arguments.

Set `OBSIDIAN_BINARY` and `OBSIDIAN_CLI` when the executables are outside the built-in discovery paths. Importing the package has no side effects. AppImage download, Vault creation, artefact installation, process launch, and cleanup occur only through explicit calls.
Expand Down Expand Up @@ -62,6 +64,7 @@ try {
pluginId: "example-plugin",
artifactRoot: "dist/example-plugin",
pluginData: { mode: "automation" },
versionPolicy: { expectedVersion: "1.13.6" },
localStorageEntries: {
"example-plugin-device-schema": "3",
},
Expand All @@ -82,7 +85,7 @@ try {
}
```

The high-level session installs `main.js`, `manifest.json`, and optional `styles.css`, writes `pluginData` as `data.json` when supplied, launches an isolated Obsidian profile, opens the exact Vault, and waits for renderer readiness. Instance-scoped lifecycle callbacks can run before and after launch, immediately before the selected plug-in starts, after it loads, and after readiness.
The high-level session installs `main.js`, `manifest.json`, and optional `styles.css`, writes `pluginData` as `data.json` when supplied, launches an isolated Obsidian profile, opens the exact Vault, and waits for renderer readiness. An optional `versionPolicy` compares the expected version with the active renderer and labels the observed version as validated or unverified. Instance-scoped lifecycle callbacks can run before and after launch, immediately before the selected plug-in starts, after it loads, and after readiness.

Supplying `localStorageEntries` or `lifecycle.beforePluginStart` selects controlled start-up by default. The selected plug-in is then excluded from Obsidian's start-up list; work required before its first load completes, and the session enables it, saves its enabled state, and loads it exactly once. Sessions without work that must precede the plug-in's first load retain natural Obsidian loading by default; set `pluginStartup` explicitly when the distinction is part of the scenario. A failed bootstrap stops the launched process. After a successful start, the caller owns `session.app.stop()` and `vault.dispose()`.

Expand Down
Loading