obsidian-plugin-dev-kit 0.0.0-stage → 0.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +223 -2
- package/bin/opdk.js +34 -0
- package/dist/build/args.d.ts +10 -0
- package/dist/build/args.js +45 -0
- package/dist/build/bundle-check.d.ts +17 -0
- package/dist/build/bundle-check.js +42 -0
- package/dist/build/bundle-file.d.ts +4 -0
- package/dist/build/bundle-file.js +29 -0
- package/dist/build/commands.d.ts +5 -0
- package/dist/build/commands.js +109 -0
- package/dist/build/config.d.ts +3 -0
- package/dist/build/config.js +103 -0
- package/dist/build/css-imports.d.ts +23 -0
- package/dist/build/css-imports.js +50 -0
- package/dist/build/css-step.d.ts +10 -0
- package/dist/build/css-step.js +27 -0
- package/dist/build/css.d.ts +24 -0
- package/dist/build/css.js +47 -0
- package/dist/build/options.d.ts +55 -0
- package/dist/build/options.js +70 -0
- package/dist/build/release.d.ts +5 -0
- package/dist/build/release.js +34 -0
- package/dist/build/report.d.ts +7 -0
- package/dist/build/report.js +16 -0
- package/dist/build/vault.d.ts +26 -0
- package/dist/build/vault.js +290 -0
- package/dist/build-info.json +1 -0
- package/dist/cli/argv.d.ts +14 -0
- package/dist/cli/argv.js +18 -0
- package/dist/cli/commands.d.ts +3 -0
- package/dist/cli/commands.js +7 -0
- package/dist/cli/main.d.ts +2 -0
- package/dist/cli/main.js +23 -0
- package/dist/cli/process-reporter.d.ts +5 -0
- package/dist/cli/process-reporter.js +15 -0
- package/dist/cli/registry.d.ts +4 -0
- package/dist/cli/registry.js +15 -0
- package/dist/cli/reporter.d.ts +53 -0
- package/dist/cli/reporter.js +100 -0
- package/dist/cli/run.d.ts +9 -0
- package/dist/cli/run.js +61 -0
- package/dist/cli/types.d.ts +27 -0
- package/dist/cli/types.js +1 -0
- package/dist/cli/version.d.ts +13 -0
- package/dist/cli/version.js +61 -0
- package/dist/config/define-config.d.ts +3 -0
- package/dist/config/define-config.js +4 -0
- package/dist/config/load-config.d.ts +6 -0
- package/dist/config/load-config.js +70 -0
- package/dist/config/manifest.d.ts +3 -0
- package/dist/config/manifest.js +72 -0
- package/dist/config/types.d.ts +146 -0
- package/dist/config/types.js +23 -0
- package/dist/demo/args.d.ts +4 -0
- package/dist/demo/args.js +13 -0
- package/dist/demo/checks.d.ts +56 -0
- package/dist/demo/checks.js +124 -0
- package/dist/demo/commands.d.ts +3 -0
- package/dist/demo/commands.js +65 -0
- package/dist/demo/config.d.ts +57 -0
- package/dist/demo/config.js +337 -0
- package/dist/demo/ffmpeg-run.d.ts +18 -0
- package/dist/demo/ffmpeg-run.js +59 -0
- package/dist/demo/ffmpeg.d.ts +63 -0
- package/dist/demo/ffmpeg.js +111 -0
- package/dist/demo/films.d.ts +46 -0
- package/dist/demo/films.js +134 -0
- package/dist/demo/phone-layout.d.ts +38 -0
- package/dist/demo/phone-layout.js +98 -0
- package/dist/demo/phone-render.d.ts +28 -0
- package/dist/demo/phone-render.js +124 -0
- package/dist/demo/published.d.ts +16 -0
- package/dist/demo/published.js +72 -0
- package/dist/demo/run.d.ts +31 -0
- package/dist/demo/run.js +397 -0
- package/dist/demo/stills.d.ts +21 -0
- package/dist/demo/stills.js +62 -0
- package/dist/e2e/artifacts.d.ts +27 -0
- package/dist/e2e/artifacts.js +90 -0
- package/dist/e2e/cleanup.d.ts +54 -0
- package/dist/e2e/cleanup.js +109 -0
- package/dist/e2e/config.d.ts +9 -0
- package/dist/e2e/config.js +42 -0
- package/dist/e2e/create-test.d.ts +37 -0
- package/dist/e2e/create-test.js +109 -0
- package/dist/e2e/demo/clip.d.ts +21 -0
- package/dist/e2e/demo/clip.js +44 -0
- package/dist/e2e/demo/create-demo.d.ts +42 -0
- package/dist/e2e/demo/create-demo.js +439 -0
- package/dist/e2e/demo/manifest.d.ts +76 -0
- package/dist/e2e/demo/manifest.js +168 -0
- package/dist/e2e/demo/names.d.ts +18 -0
- package/dist/e2e/demo/names.js +44 -0
- package/dist/e2e/demo/options.d.ts +22 -0
- package/dist/e2e/demo/options.js +59 -0
- package/dist/e2e/demo/ownership.d.ts +27 -0
- package/dist/e2e/demo/ownership.js +65 -0
- package/dist/e2e/demo/page-scripts.d.ts +82 -0
- package/dist/e2e/demo/page-scripts.js +250 -0
- package/dist/e2e/demo/png.d.ts +8 -0
- package/dist/e2e/demo/png.js +23 -0
- package/dist/e2e/demo/presets.d.ts +43 -0
- package/dist/e2e/demo/presets.js +20 -0
- package/dist/e2e/demo/privacy.d.ts +18 -0
- package/dist/e2e/demo/privacy.js +30 -0
- package/dist/e2e/demo/still-options.d.ts +22 -0
- package/dist/e2e/demo/still-options.js +68 -0
- package/dist/e2e/demo/types.d.ts +184 -0
- package/dist/e2e/demo/types.js +1 -0
- package/dist/e2e/electron-binary.d.ts +15 -0
- package/dist/e2e/electron-binary.js +30 -0
- package/dist/e2e/fixtures.d.ts +62 -0
- package/dist/e2e/fixtures.js +68 -0
- package/dist/e2e/gate.d.ts +4 -0
- package/dist/e2e/gate.js +8 -0
- package/dist/e2e/global-setup.d.ts +11 -0
- package/dist/e2e/global-setup.js +17 -0
- package/dist/e2e/helpers/commands.d.ts +14 -0
- package/dist/e2e/helpers/commands.js +56 -0
- package/dist/e2e/helpers/create-helpers.d.ts +24 -0
- package/dist/e2e/helpers/create-helpers.js +582 -0
- package/dist/e2e/helpers/device-metrics.d.ts +21 -0
- package/dist/e2e/helpers/device-metrics.js +25 -0
- package/dist/e2e/helpers/ime.d.ts +13 -0
- package/dist/e2e/helpers/ime.js +19 -0
- package/dist/e2e/helpers/layout-page-scripts.d.ts +103 -0
- package/dist/e2e/helpers/layout-page-scripts.js +224 -0
- package/dist/e2e/helpers/layout.d.ts +83 -0
- package/dist/e2e/helpers/layout.js +148 -0
- package/dist/e2e/helpers/mobile.d.ts +31 -0
- package/dist/e2e/helpers/mobile.js +26 -0
- package/dist/e2e/helpers/page-scripts.d.ts +194 -0
- package/dist/e2e/helpers/page-scripts.js +467 -0
- package/dist/e2e/helpers/settings.d.ts +8 -0
- package/dist/e2e/helpers/settings.js +16 -0
- package/dist/e2e/helpers/settle.d.ts +28 -0
- package/dist/e2e/helpers/settle.js +33 -0
- package/dist/e2e/helpers/types.d.ts +193 -0
- package/dist/e2e/helpers/types.js +1 -0
- package/dist/e2e/helpers/view-mode.d.ts +23 -0
- package/dist/e2e/helpers/view-mode.js +35 -0
- package/dist/e2e/index.d.ts +14 -0
- package/dist/e2e/index.js +4 -0
- package/dist/e2e/internals.d.ts +155 -0
- package/dist/e2e/internals.js +8 -0
- package/dist/e2e/obsidian-path.d.ts +17 -0
- package/dist/e2e/obsidian-path.js +31 -0
- package/dist/e2e/options.d.ts +123 -0
- package/dist/e2e/options.js +244 -0
- package/dist/e2e/page-scripts.d.ts +45 -0
- package/dist/e2e/page-scripts.js +53 -0
- package/dist/e2e/peers.d.ts +9 -0
- package/dist/e2e/peers.js +19 -0
- package/dist/e2e/plugins.d.ts +32 -0
- package/dist/e2e/plugins.js +119 -0
- package/dist/e2e/process-tree.d.ts +33 -0
- package/dist/e2e/process-tree.js +133 -0
- package/dist/e2e/readiness.d.ts +23 -0
- package/dist/e2e/readiness.js +63 -0
- package/dist/e2e/seed.d.ts +34 -0
- package/dist/e2e/seed.js +122 -0
- package/dist/e2e/session.d.ts +71 -0
- package/dist/e2e/session.js +266 -0
- package/dist/e2e/vault.d.ts +52 -0
- package/dist/e2e/vault.js +146 -0
- package/dist/e2e/version.d.ts +25 -0
- package/dist/e2e/version.js +40 -0
- package/dist/eslint/index.d.ts +2 -0
- package/dist/eslint/index.js +1 -0
- package/dist/eslint/obsidian-plugin.d.ts +49 -0
- package/dist/eslint/obsidian-plugin.js +115 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +1 -0
- package/dist/kit/args.d.ts +7 -0
- package/dist/kit/args.js +21 -0
- package/dist/kit/commands.d.ts +3 -0
- package/dist/kit/commands.js +52 -0
- package/dist/kit/files.d.ts +3 -0
- package/dist/kit/files.js +24 -0
- package/dist/kit/pins.d.ts +89 -0
- package/dist/kit/pins.js +178 -0
- package/dist/kit/remote.d.ts +13 -0
- package/dist/kit/remote.js +33 -0
- package/dist/kit/runners.d.ts +11 -0
- package/dist/kit/runners.js +53 -0
- package/dist/kit/terminal-text.d.ts +6 -0
- package/dist/kit/terminal-text.js +20 -0
- package/dist/kit/upgrade.d.ts +26 -0
- package/dist/kit/upgrade.js +162 -0
- package/dist/peers/resolve.d.ts +8 -0
- package/dist/peers/resolve.js +28 -0
- package/dist/peers/versions.d.ts +30 -0
- package/dist/peers/versions.js +32 -0
- package/dist/release/api-check.d.ts +27 -0
- package/dist/release/api-check.js +119 -0
- package/dist/release/args.d.ts +40 -0
- package/dist/release/args.js +120 -0
- package/dist/release/assets.d.ts +21 -0
- package/dist/release/assets.js +35 -0
- package/dist/release/build-check.d.ts +43 -0
- package/dist/release/build-check.js +184 -0
- package/dist/release/build-script.d.ts +12 -0
- package/dist/release/build-script.js +30 -0
- package/dist/release/build-tagged.d.ts +26 -0
- package/dist/release/build-tagged.js +52 -0
- package/dist/release/bump.d.ts +24 -0
- package/dist/release/bump.js +58 -0
- package/dist/release/changelog.d.ts +25 -0
- package/dist/release/changelog.js +148 -0
- package/dist/release/check.d.ts +38 -0
- package/dist/release/check.js +150 -0
- package/dist/release/commands.d.ts +3 -0
- package/dist/release/commands.js +154 -0
- package/dist/release/committed-tree.d.ts +63 -0
- package/dist/release/committed-tree.js +118 -0
- package/dist/release/config.d.ts +3 -0
- package/dist/release/config.js +28 -0
- package/dist/release/gh-access.d.ts +14 -0
- package/dist/release/gh-access.js +45 -0
- package/dist/release/gh.d.ts +10 -0
- package/dist/release/gh.js +33 -0
- package/dist/release/git.d.ts +49 -0
- package/dist/release/git.js +111 -0
- package/dist/release/interrupt.d.ts +30 -0
- package/dist/release/interrupt.js +60 -0
- package/dist/release/json.d.ts +33 -0
- package/dist/release/json.js +81 -0
- package/dist/release/kit-check.d.ts +8 -0
- package/dist/release/kit-check.js +51 -0
- package/dist/release/manifest-rules.d.ts +23 -0
- package/dist/release/manifest-rules.js +255 -0
- package/dist/release/preflight.d.ts +10 -0
- package/dist/release/preflight.js +65 -0
- package/dist/release/problems.d.ts +24 -0
- package/dist/release/problems.js +11 -0
- package/dist/release/project-files.d.ts +14 -0
- package/dist/release/project-files.js +16 -0
- package/dist/release/publish-command.d.ts +21 -0
- package/dist/release/publish-command.js +83 -0
- package/dist/release/publish-git.d.ts +37 -0
- package/dist/release/publish-git.js +108 -0
- package/dist/release/publish-state.d.ts +29 -0
- package/dist/release/publish-state.js +70 -0
- package/dist/release/publish-verify.d.ts +41 -0
- package/dist/release/publish-verify.js +112 -0
- package/dist/release/publish-wait.d.ts +25 -0
- package/dist/release/publish-wait.js +56 -0
- package/dist/release/publish.d.ts +35 -0
- package/dist/release/publish.js +181 -0
- package/dist/release/release-assets.d.ts +39 -0
- package/dist/release/release-assets.js +68 -0
- package/dist/release/release.d.ts +37 -0
- package/dist/release/release.js +179 -0
- package/dist/release/remote.d.ts +12 -0
- package/dist/release/remote.js +15 -0
- package/dist/release/reproducible.d.ts +16 -0
- package/dist/release/reproducible.js +34 -0
- package/dist/release/run-tests.d.ts +5 -0
- package/dist/release/run-tests.js +17 -0
- package/dist/release/semver.d.ts +8 -0
- package/dist/release/semver.js +60 -0
- package/dist/release/version-rules.d.ts +28 -0
- package/dist/release/version-rules.js +63 -0
- package/dist/release/versions-json.d.ts +15 -0
- package/dist/release/versions-json.js +88 -0
- package/dist/release/workflow-run.d.ts +44 -0
- package/dist/release/workflow-run.js +71 -0
- package/dist/scanner/code-checks.d.ts +41 -0
- package/dist/scanner/code-checks.js +82 -0
- package/dist/scanner/commands.d.ts +3 -0
- package/dist/scanner/commands.js +43 -0
- package/dist/scanner/config.d.ts +7 -0
- package/dist/scanner/config.js +25 -0
- package/dist/scanner/css-check.d.ts +26 -0
- package/dist/scanner/css-check.js +63 -0
- package/dist/scanner/eslint-nesting.d.ts +16 -0
- package/dist/scanner/eslint-nesting.js +45 -0
- package/dist/scanner/findings.d.ts +23 -0
- package/dist/scanner/findings.js +21 -0
- package/dist/scanner/git-files.d.ts +16 -0
- package/dist/scanner/git-files.js +73 -0
- package/dist/scanner/lint.d.ts +47 -0
- package/dist/scanner/lint.js +163 -0
- package/dist/scanner/meta-checks.d.ts +8 -0
- package/dist/scanner/meta-checks.js +22 -0
- package/dist/scanner/outside-project.d.ts +19 -0
- package/dist/scanner/outside-project.js +20 -0
- package/dist/scanner/run.d.ts +19 -0
- package/dist/scanner/run.js +78 -0
- package/dist/scanner/scanner-config.d.ts +114 -0
- package/dist/scanner/scanner-config.js +207 -0
- package/dist/scanner/typescript-gate.d.ts +30 -0
- package/dist/scanner/typescript-gate.js +73 -0
- package/dist/vitest/build-config.d.ts +17 -0
- package/dist/vitest/build-config.js +106 -0
- package/dist/vitest/define-unit-config.d.ts +27 -0
- package/dist/vitest/define-unit-config.js +45 -0
- package/dist/vitest/dom/elements.d.ts +87 -0
- package/dist/vitest/dom/elements.js +291 -0
- package/dist/vitest/dom/index.d.ts +1 -0
- package/dist/vitest/dom/index.js +1 -0
- package/dist/vitest/dom/install.d.ts +8 -0
- package/dist/vitest/dom/install.js +261 -0
- package/dist/vitest/dom/setup.d.ts +1 -0
- package/dist/vitest/dom/setup.js +3 -0
- package/dist/vitest/index.d.ts +3 -0
- package/dist/vitest/index.js +2 -0
- package/dist/vitest/options.d.ts +92 -0
- package/dist/vitest/options.js +136 -0
- package/dist/vitest/peers.d.ts +10 -0
- package/dist/vitest/peers.js +51 -0
- package/dist/vitest/workspace-root.d.ts +7 -0
- package/dist/vitest/workspace-root.js +39 -0
- package/docs/build.md +232 -0
- package/docs/ci.md +182 -0
- package/docs/demo.md +364 -0
- package/docs/e2e.md +563 -0
- package/docs/release.md +374 -0
- package/docs/scanner.md +204 -0
- package/docs/unit.md +291 -0
- package/package.json +100 -4
- package/plugins/opdk/skills/audit/SKILL.md +81 -0
- package/plugins/opdk/skills/build/SKILL.md +79 -0
- package/plugins/opdk/skills/demo/SKILL.md +102 -0
- package/plugins/opdk/skills/e2e/SKILL.md +132 -0
- package/plugins/opdk/skills/release/SKILL.md +84 -0
- package/plugins/opdk/skills/scanner/SKILL.md +60 -0
- package/plugins/opdk/skills/unit/SKILL.md +90 -0
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: demo
|
|
3
|
+
description: Make a demo film, GIF, MP4, poster or README and listing screenshot of an Obsidian plugin that uses obsidian-plugin-dev-kit (opdk) with `opdk demo` and the `demo` fixture (`demo.film`, `film.shot`, `demo.still`, `demo.caption`, `demo.cleanUi`, `demo.themes`). Use it to film a feature, record a phone layout, capture themed stills, fix `opdk demo` messages ("no films", "refused", "forbidden selector", "loop does not close", "not found on PATH", "libx264"), or to replace a plugin's own capture scripts. Not for ordinary Playwright tests (e2e).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# opdk demo module
|
|
7
|
+
|
|
8
|
+
A film is a list of stills: each `film.shot()` freezes the Obsidian window and takes a picture at 2x, with a hold in seconds and an optional caption. `opdk demo` encodes the film to `<name>.mp4`, `<name>.gif` and `<name>-poster.png`. No audio, no intro or outro cards. Run commands from the plugin root. Full docs: `node_modules/obsidian-plugin-dev-kit/docs/demo.md`
|
|
9
|
+
|
|
10
|
+
Safety: specs run in a temp copy of the seed vault. When you run anything that writes into a vault (`opdk build --vault`), use `env -u VAULT_PLUGIN`. Never film a vault that is not the plugin's own seed vault.
|
|
11
|
+
|
|
12
|
+
## Plan a film
|
|
13
|
+
|
|
14
|
+
1. Write down 2 to 4 steps, each one a state of the app (open a note, type, run a command, open settings). One idea per step.
|
|
15
|
+
2. Rehearse the selectors and commands in a plain e2e spec first (`obsidian.*` helpers, see the e2e skill) and assert each state. A film spec should have no surprises left.
|
|
16
|
+
3. Choose the kind: `phone` (inside `obsidian.mobile()`, with `captions` for the `phone-captions` layout) or `desktop` (with `demo.caption()` bars, or no captions).
|
|
17
|
+
4. Pace: 2 to 4 seconds per step, a longer hold on the first and the last frame. For typing, shoot every few characters with a hold of 0.4 to 0.6 s and finish with a longer one; 25 to 40 ms per character (`typeSlowly` default is 40). A caption stays under about 60 characters; a line break (`"Tap a day\nSee its value"`) makes a heading and a text in the phone layout.
|
|
18
|
+
5. End where you began (same note, same text, same focus) so the GIF loops without a jump. Hide the caption (`demo.caption(null)`) and the cursor before the last shot so it matches the first; a tour that cannot return to its start gets `loop: "off"`.
|
|
19
|
+
6. A frame that shows network content (a page that loads data at run time) differs between takes. Replace the plugin's fetching function with `obsidian.replace()` and a fixture so the film is stable.
|
|
20
|
+
|
|
21
|
+
## Privacy rules
|
|
22
|
+
|
|
23
|
+
- Seed vault inside the plugin folder, made for the film. Never `OPDK_E2E_VAULT` pointing at a real vault. The fixture refuses both (`film "<name>" refused: ...`) unless the call passes `allowForeignVault: true`; do not pass it for a real vault.
|
|
24
|
+
- Put every selector that could show private data (an API key field, an account name, a path) in `demo.forbiddenSelectors`; a shot fails when one is visible.
|
|
25
|
+
- `demo.freezeTime("2026-03-14T09:26:00")` so no frame shows today's date. File dates in the explorer are not frozen.
|
|
26
|
+
- `.opdk/` goes in `.gitignore`: it holds raw frames.
|
|
27
|
+
|
|
28
|
+
## Destinations and sizes
|
|
29
|
+
|
|
30
|
+
- README GIF: GitHub shows a README at about 1000 px, and 900 is the kit's own choice, under 2 MB (`gif: { width: 900 }`; the default is the frame width up to 1000 px, 128 colours, 10 fps at most). The size check warns above 2 MB and fails above 10 MB.
|
|
31
|
+
- Stills for other places (`demo.still(name, { preset })`): `readme` 1000 x 640, `listing-desktop` 1200 x 800, `listing-phone` 900 x 1600, `social` 1200 x 630. `opdk demo` copies every `<outDir>/stills/<name>.png` to the output folder as `<name>.png`, only when the bytes changed (`demo.stills: false` turns it off, `demo.stills: { output }` picks a folder); `opdk demo hero` selects the still `hero` as well as a film of that name. A still that only feeds another tool (a listing composer) is `demo.still(name, { publish: false })`: it stays in `<outDir>/stills` and is not copied. A still for its own folder (directory listing pictures) is `demo.still(name, { out: "listing" })` with `demo.outputs: { listing: "docs/listing" }` in `opdk.config.mjs`; do not copy them with a plugin script. `out` with `publish: false` fails, and an `out` missing from `demo.outputs` fails that still and lists the folders there are.
|
|
32
|
+
- Frames are shot at scale 2 (a 1200 x 800 window gives 2400 x 1600, a phone gives 780 x 1688). The MP4 and poster keep the frame size, the GIF is smaller.
|
|
33
|
+
|
|
34
|
+
## The recording API
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
import { expect, onlyWhen, test } from "./fixtures.js";
|
|
38
|
+
|
|
39
|
+
onlyWhen("OPDK_E2E_FILM");
|
|
40
|
+
|
|
41
|
+
test("tour: open a note, type, run a command", async ({ obsidian, demo, win }) => {
|
|
42
|
+
await demo.freezeTime("2026-03-14T09:26:00");
|
|
43
|
+
await obsidian.mobile();
|
|
44
|
+
await obsidian.openFile("Welcome.md", { mode: "source" });
|
|
45
|
+
await demo.cleanUi();
|
|
46
|
+
await obsidian.clearNotices();
|
|
47
|
+
const film = demo.film({ name: "tour", kind: "phone", captions: ["Open a note", "Type\nKey by key", "Run a command"] });
|
|
48
|
+
await film.shot({ hold: 1.8, caption: 0 });
|
|
49
|
+
const editor = win.locator(".cm-content[contenteditable=true]").first();
|
|
50
|
+
await demo.tap(editor);
|
|
51
|
+
await demo.typeSlowly("# Typed by the kit", { delayMs: 40 });
|
|
52
|
+
await expect(editor).toContainText("Typed by the kit");
|
|
53
|
+
await film.shot({ hold: 1.6, caption: 1 });
|
|
54
|
+
await obsidian.runCommand("my-plugin:insert-date");
|
|
55
|
+
await film.shot({ hold: 1.6, caption: 2 });
|
|
56
|
+
});
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
- `demo.film({ kind, name?, fps?, captions?, clip?, padding?, scale?, cursor?, forbiddenSelectors?, allowForeignVault? })`; the folder is emptied at the start, so a retake replaces the frames. `film.shot({ hold, caption?, clip?, padding?, settle? })`: assert the state first, a shot does not wait for the app. `settle: true` (also in `demo.still()`, default `false`) waits for the page to stop changing before the freeze: use it instead of a `waitForTimeout` (a pause longer than `quietMs` before the render looks settled, so assert on the element or raise `quietMs`).
|
|
60
|
+
- `demo.tap(target, { whilePressed? })` on a phone, `demo.moveAndClick(target)` on the desktop; `demo.typeSlowly(text)` types into the focused element (fails when nothing editable has focus), `demo.typeSlowly(target, text)` clicks the target first. `demo.caption(text | null)` is a bar drawn into the frames; `captions` in `film()` is the list the phone layout draws beside the phone. `demo.hideCursor()`. The cursor arrow follows every Playwright mouse action (`click()`, `check()`, `selectOption()`), not only `moveAndClick()`; `cursor: false` in `demo.film()` or `demo.still()` keeps it out of that film's frames or that still (it does not carry over to the next picture).
|
|
61
|
+
- `demo.beat(seconds)` is seconds (not milliseconds, throws above 60) and is for pacing a Playwright video of a test; the kit films stills only, so use `hold`.
|
|
62
|
+
- `demo.cleanUi(options?)` (each call sets the five hidden parts: ribbon, statusBar, tabHeaders, viewHeader, inlineTitle; it also folds both sidebars, `sidebars: false` keeps them), `demo.freezeTime(date)`, `demo.themes(["light", "dark"], scene)` (names get `-light` and `-dark`).
|
|
63
|
+
- Fixture option: `createObsidianTest({ demo: { outDir, scale, forbiddenSelectors } })`.
|
|
64
|
+
|
|
65
|
+
## Encode
|
|
66
|
+
|
|
67
|
+
`opdk.config.mjs`, `demo` section (all optional): `outDir` (`.opdk/demo`), `output` (`docs/screens`), `gif`, `mp4`, `poster`, `stills` (`true`, `false` or `{ output }`), `outputs` (`{ listing: "docs/listing" }`, named folders for stills with `out`), `layout` (`"plain"` or `"phone-captions"`), `budget`, `loop`, `phone`, and `films.<name>` with the same film keys. Then:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
OPDK_E2E_FILM=1 npx playwright test film # records
|
|
71
|
+
npx opdk demo [names...] # encodes every complete film, copies the stills
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
`opdk demo` needs ffmpeg for films (on `PATH` or `OPDK_FFMPEG`). The phone layout also needs `electron` and `@playwright/test`, as the e2e tests do; in CI add ffmpeg, a virtual display (`xvfb-run -a`) and `OPDK_COMPOSE_NO_SANDBOX=1`.
|
|
75
|
+
|
|
76
|
+
## Reading failures
|
|
77
|
+
|
|
78
|
+
- `no films in <dir>/films`: the specs did not run or wrote elsewhere. Run the gated spec, or set `demo.outDir`.
|
|
79
|
+
- `no film named "x" in ...` (`no film or still named` when stills exist) `in <outDir>`: the message lists the films and stills there; fix the name. With `stills: false` it adds `demo.stills is false, so stills are not selectable` when the name is a still on disk.
|
|
80
|
+
- `<name>: skipped, <reason>` or `not encoded`: the recording test did not pass, so the film is incomplete. Fix the test, record again.
|
|
81
|
+
- `film "x" refused: OPDK_E2E_VAULT points this run at ...`: unset `OPDK_E2E_VAULT`. `... the seed vault ... lies outside the plugin folder`: move the seed vault into the plugin folder. Do not reach for `allowForeignVault` to make it pass.
|
|
82
|
+
- `film "x", frame N refused: an element matching the forbidden selector`: close or hide the element before the shot.
|
|
83
|
+
- `OPDK_FFMPEG=... cannot run` or `ffmpeg was not found on PATH`: install ffmpeg (`brew install ffmpeg`), or point `OPDK_FFMPEG` at it. `has no libx264 encoder`: install a full ffmpeg or set `mp4: false`.
|
|
84
|
+
- `ffmpeg exited with code 0 but reported errors`: a frame could not be decoded; the film fails, record it again.
|
|
85
|
+
- `gif is N MB, over the 10.0 MB limit`: lower `gif.width`, `colors` or `fps`, or shorten the film; the file stays in the output folder.
|
|
86
|
+
- `! loop does not close: the last frame differs from the first in a W x H px area at (x, y)`: end the scene where it began (hide the caption and the cursor in the last frame), or set `loop: "off"` for a tour. Pixels within 8 of 255 per channel already count as equal.
|
|
87
|
+
- `! frame 0003.png (0.05 s) is held for less than one GIF frame`: hold it at least 0.1 s, or raise `gif.fps`.
|
|
88
|
+
- `! the dark film "x-dark" is missing`: record both themes, or encode with the pair's name.
|
|
89
|
+
- `! media published by an earlier run of this command belongs to films or stills that no longer exist: ...`: files `opdk demo` itself wrote (recorded in `<outDir>/published.json`) for a film or still that was renamed or removed; the command never deletes, so delete them by hand. Unrelated media in the output folder is never listed.
|
|
90
|
+
- `! media published by an earlier run of this command is no longer written by its film or still (an output turned off, or moved): ...`: recorded files of a film or still that still exists and was written without a failure this run but not these files (for example after `mp4: false`, a new `demo.output` or `demo.stills.output`). Delete them by hand.
|
|
91
|
+
- `settle(): the page was not quiet for N ms within M ms (...)`: something keeps changing the DOM, a font or an image in view is slow. Pass `settle` only where the page can be still, call `obsidian.settle({ root })` with a `root` that leaves out a part that never stops changing, or raise `timeouts.helpers.ui`.
|
|
92
|
+
- `layout "phone-captions" ... has none` / `is for phone films`: pass `captions` to `demo.film()`, and use `kind: "phone"`.
|
|
93
|
+
- `... must be a CSS value without "..."`: a `phone` colour or font holds `; { } < > \ /* url(` or quotes; use a plain value.
|
|
94
|
+
|
|
95
|
+
Hint, not an error message: `settle` does not see canvas drawing (charts): before a still of a canvas, poll a pixel or the chart library's ready flag yourself.
|
|
96
|
+
|
|
97
|
+
## Migrating a plugin's own scripts
|
|
98
|
+
|
|
99
|
+
1. Add the kit, `@playwright/test`, `electron` and ffmpeg; add `.opdk/` to `.gitignore`. To move the kit to a new tag use `npm install -D "github:Dimagious/obsidian-plugin-dev-kit#<tag>"`: editing `package.json` and running a plain `npm install` keeps the old lock entry.
|
|
100
|
+
2. Rewrite the film and capture specs on `demo` (films of stills in place of screen recordings and screenshot loops).
|
|
101
|
+
3. Move README and listing pictures from `win.screenshot` to `demo.still(name, { preset, settle: true })` (and their sleeps to `settle`; a pause longer than `quietMs` before the render looks settled, so assert on the element or raise `quietMs`), then GIF numbers to `gif` per film, the poster and output names are `<name>-poster.png` and `docs/screens` (to keep a `film-<name>-poster.png`, name the film `film-<name>`; a phone film with captions beside it uses `layout: "phone-captions"` with the colours in `phone`; voice-over and an outro are not part of the kit).
|
|
102
|
+
4. Delete the old encoder scripts, run the specs and `opdk demo`, compare, and list the differences in the plugin's CHANGELOG. `beat()` takes seconds now.
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: e2e
|
|
3
|
+
description: Set up, write or fix Playwright end-to-end tests for an Obsidian plugin that uses obsidian-plugin-dev-kit (opdk), run in the real Obsidian through Electron. Use it when a spec fails ("Stale build", "Electron binary is not downloaded", "plugin still loading", "Obsidian was not ready", a helper timeout), when a test needs settings, the command palette, the editor, IME input, the mobile layout or a fake plugin client, or when moving a plugin's own e2e fixtures to `obsidian-plugin-dev-kit/e2e`. Not for Vitest unit tests (unit), demo films, GIFs or README stills (demo), build errors (build) or scorecard warnings (scanner).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# opdk e2e module
|
|
7
|
+
|
|
8
|
+
Specs run in the real Obsidian through Electron (`_electron.launch` on Obsidian's `app.asar`). Run commands from the plugin root. The plugin id always comes from `manifest.json`. Full docs: `node_modules/obsidian-plugin-dev-kit/docs/e2e.md`
|
|
9
|
+
|
|
10
|
+
Safety: `VAULT_PLUGIN` (the dev vault of `opdk build --vault`) is removed from Obsidian's environment by the kit. Every test uses a temp vault copy and a temp user-data folder, never the real vault. When you run anything else that writes into a vault, use `env -u VAULT_PLUGIN`.
|
|
11
|
+
|
|
12
|
+
## Set up a plugin
|
|
13
|
+
|
|
14
|
+
1. devDependencies: `@playwright/test` (`^1.62.0`), `electron` (`>=39.0.0`) and the kit pinned to an exact tag. Electron downloads its binary on first use (about 100 MB): run `node node_modules/electron/install.js` once (it only downloads; do not start Electron to fetch it); in CI cache the download (`ELECTRON_CACHE`) and run that command before the tests. Without it the run fails once, before any test, from a global setup that `defineObsidianConfig` registers (a plain Playwright config repeats the failure in every test).
|
|
15
|
+
2. A seed vault (any path, set in `seedVault`), for example `e2e/vault/` with `.obsidian/core-plugins.json` containing `["file-explorer", "command-palette"]` (the palette helpers need it) and a note.
|
|
16
|
+
3. `e2e/fixtures.ts`:
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
import { createObsidianTest } from "obsidian-plugin-dev-kit/e2e";
|
|
20
|
+
|
|
21
|
+
export const { test, expect, onlyWhen } = createObsidianTest({ seedVault: "e2e/vault" });
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
4. `playwright.config.ts`: `import { defineObsidianConfig } from "obsidian-plugin-dev-kit/e2e"; export default defineObsidianConfig();`
|
|
25
|
+
5. Script: `"e2e": "npm run build && playwright test"`. Build first: a `main.js` older than the newest file under `src/` is refused as a stale build (compared by modification time; a test file is one whose name ends in `.test.<ext>` or `.spec.<ext>`; every other file under `src/` counts).
|
|
26
|
+
6. Typecheck the specs with `e2e/tsconfig.json` (the root one usually includes only `src/`, and may lack DOM, which `win.evaluate` callbacks reading `document` need):
|
|
27
|
+
|
|
28
|
+
```json
|
|
29
|
+
{
|
|
30
|
+
"extends": "../tsconfig.json",
|
|
31
|
+
"compilerOptions": { "lib": ["ES2020", "DOM", "DOM.Iterable"], "types": ["node"] },
|
|
32
|
+
"include": ["./**/*.ts", "../playwright.config.ts"]
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
and `"typecheck": "tsc -p tsconfig.json --noEmit && tsc -p e2e/tsconfig.json --noEmit"` in `package.json`.
|
|
37
|
+
7. A spec:
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
import { expect, test } from "./fixtures.js";
|
|
41
|
+
|
|
42
|
+
test("the command writes into the note", async ({ obsidian }) => {
|
|
43
|
+
await obsidian.openFile("Welcome.md", { mode: "source" });
|
|
44
|
+
await obsidian.runCommand("my-plugin:insert-date");
|
|
45
|
+
expect(await obsidian.editor().text()).toMatch(/\d{4}-\d{2}-\d{2}/);
|
|
46
|
+
});
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Fixtures
|
|
50
|
+
|
|
51
|
+
`win` (Playwright `Page` of the Obsidian window), `app` (`ElectronApplication`, `app.evaluate` runs in the main process), `vault` (`path`, `resolve`, `exists`, `read`, `write` on the per-test copy), `obsidian` (the helpers). `vault.write` is plain fs: Obsidian's index (`app.vault.getFileByPath`, the metadata cache) learns of the file only when its watcher fires, so after a write poll for the file first: `await expect.poll(() => obsidian.evaluate((app: App, p: string) => app.vault.getFileByPath(p) !== null, path)).toBe(true)` (`import type { App } from "obsidian"`). Then call `obsidian.waitForMetadataCache()` where the links, tags or frontmatter matter (it only loops over files already indexed, so it does not replace the poll), before acting through the index. Each test gets a fresh Obsidian, vault copy and user-data folder. It starts when the workspace is laid out and every plugin's `onload()` has finished, so a command or tab added after an `await` in `onload()` exists. It does not wait for what the plugin renders after `onload()`: wait for that in the spec (`expect(locator).toBeVisible()`, `expect.poll`, `waitForFunction`), never with a sleep.
|
|
52
|
+
|
|
53
|
+
A test that needs extra notes or `app.json` keys at start sets `test.use({ seed: { files: { "Notes/a.md": "# a" }, config: { propertiesInDocument: "hidden" } } })` (file or `describe`): they are in the vault before Obsidian opens, so no `vault.write` plus `obsidian.reload()`. `files` may point into `.obsidian/` (`.obsidian/templates.json`); plugin settings stay in the `data` option.
|
|
54
|
+
|
|
55
|
+
## Options of `createObsidianTest` (unknown keys fail naming them)
|
|
56
|
+
|
|
57
|
+
`seedVault` (required, env `OPDK_E2E_VAULT`), `plugins` (`[{ dir, staleBuildCheck? }]`, default the plugin in the current directory), `data` (`data.json` per plugin id, replaces a seeded one), `window` (`{ width, height }`), `obsidianPath` (`app.asar`, env `OBSIDIAN_PATH`; required off macOS), `electronArgs` (not `--user-data-dir`), `version` (explicit `x.y.z`, env `OBSIDIAN_VERSION`; fails the test on another version), `timeouts` (`launch` 45000, `ready` 30000, `close` 5000, `trace` 60000, `helpers.{settings 15000, metadataCache 45000, compose 5000, theme 5000, ui 10000}`), `staleBuildCheck` (default true, applies to the plugin in the current directory only; another `plugins` entry is checked only with its own `staleBuildCheck: true`, and an entry's value wins over the top-level one; env `OPDK_E2E_ALLOW_STALE_BUILD=1` turns every check off for one run), `sweepAfterHours` (default 2, `false` disables).
|
|
58
|
+
|
|
59
|
+
## Helpers (`obsidian`)
|
|
60
|
+
|
|
61
|
+
- Settings: `openSettings(tab?)` (plugin id or core tab id; waits for a late-registered tab; returns the settings content locator: use it for lookups inside the tab, and use `win.locator(...)` for `has:` filters across the page and for screenshots of the container; Settings opens in the main window, so those screenshots have another size than from a popout), `closeSettings()`. Settings opens in the main window because the kit sets `settingsPopoutWindow: false` unless the seed vault's `app.json` says otherwise.
|
|
62
|
+
- Commands: `runCommand(id)` (fails with close matches for an unknown id, and when `checkCallback` declined), `openCommandPalette()`, `runCommandFromPalette(name)`, `press("Mod+P")`.
|
|
63
|
+
- Files and editor: `openFile(path, { mode: "source" | "live" | "preview" })` (Obsidian view state `{ mode: "source", source: false }` is `"live"`, `{ mode: "source", source: true }` is `"source"`, `{ mode: "preview" }` is `"preview"`), `readingView(path?)`, `collapseSidebars()` / `expandSidebars()` (fold or unfold both side panels and wait for it; call before `openFile` when the note needs the whole window), `editor().type / text / clear / setCursor / selection`. `text()` and `clear()` throw `There is no active editor` without a note open in source or live mode. `text()` reads `getValue()`, not the DOM.
|
|
64
|
+
- Layout: `checkLayout({ root, overflow?, touchTargets?, focusRing? })` fails with the list of all problems inside `root` (required, must match): horizontal overflow (default on), touch targets under 44 px (default on only after `mobile()`), a Tab stop whose outline or box-shadow (on the element or its `::before`/`::after`; screenshots for range and colour inputs) does not change on focus (default off, it presses Tab; `focusRing: { stayInside: true }` also fails when Tab leaves the root, `focusRing: { ignore }` skips a control, for example `.prompt-input`, Obsidian's palette search field with no ring). Scroll panes are checked for overflow; `overflow: { ignore: "pre" }` leaves out a code block or table that scrolls on purpose. Every check off, or a root that matches nothing, fails. `layoutProblems(options)` returns the list instead. Open and `settle()` the part first. For a human look at the screens of a tour use `demo.still(name, { publish: false })` with a `review-` name prefix.
|
|
65
|
+
- IME: `editor().compose(text, { chunking: "word" | "character" })`. It always commits; leaving a composition uncommitted needs a raw CDP session (`win.context().newCDPSession(win)`).
|
|
66
|
+
- Appearance and state: `setTheme({ mode, theme? })`, `waitForMetadataCache()`, `clearNotices()`, `hideProperties()`, `scrollThrough(selector?)` (stays at the bottom; do not expect it to scroll back), `settle({ quietMs?, root? })` (waits until the DOM has been quiet for 150 ms, fonts are loaded and the images in view are complete; use it in place of a fixed sleep before a picture; its budget is `timeouts.helpers.ui`; a pause longer than `quietMs` before the render looks settled, so assert on the element or raise `quietMs`; canvas drawing, a chart, is not seen at all, so wait for it yourself by polling a pixel or the chart library's ready flag).
|
|
67
|
+
- Reload: `reload()` runs `app:reload` and waits until the new page and every plugin are up; use it instead of waiting for the editor after a reload. Fakes from `replace()` are gone afterwards. `app:reload` reloads without saving: wait until the file is written (`vault.read`) before reloading text you just typed.
|
|
68
|
+
- Mobile: `mobile({ width, height, scale })` (default 390 x 844 at 2), `desktop()`. It reloads the window; another width reloads again. A plugin with `isDesktopOnly: true` does not load on mobile and the wait fails naming it. Screenshot size follows the display (1x or 2x), and `scale` does not change it: use `win.screenshot({ scale: "css" })` for pictures of a fixed size. Instead of `webFrame.setZoomFactor`, set the viewport with `mobile({ width, height, scale })` and cut with a `clip` in CSS pixels (450 x 800 at scale 2 is 900 x 1600 on a 2x display).
|
|
69
|
+
- Page code: `evaluate(fn, arg?)` runs `fn(app, arg)` in the page with `app` = `window.app`; type it with a type-only `import type { App } from "obsidian"` (the kit does not depend on `obsidian`). `fn` is serialised as source text: no closures, no imports, pass values in `arg`; `arg` and the result must be serialisable (return fields, not a `TFile`).
|
|
70
|
+
- Obsidian internals (`app.plugins.enablePlugin`, `app.setting`, `app.commands`, `app.internalPlugins`, `vault.getConfig`): type `app` as `AppWithInternals` from `obsidian-plugin-dev-kit/e2e` (`AppWithInternals<PluginInstance & { settings?: MySettings }>` for your plugin's own members) through `obsidian.evaluate((app: AppWithInternals) => ...)`, with no cast, instead of declaring a copy of the interface in the spec or casting `globalThis` through `unknown`.
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
import type { App } from "obsidian";
|
|
74
|
+
|
|
75
|
+
const count = await obsidian.evaluate((app: App, folder: string) => app.vault.getMarkdownFiles().filter((file) => file.path.startsWith(folder)).length, "Notes/");
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
- Fakes: `replace(pluginId, "path.to.fn", factory, arg?)` returns `{ calls(), restore() }`. The factory runs in the page: it cannot close over test variables or use imports. A variable the factory itself reads fails `replace()` with a message naming it (`the replacement factory threw: X is not defined`). A variable read inside the function it returns fails only when the plugin calls it, inside the plugin's own error handling, so put every value in `arg`. After a window reload `calls()` and `restore()` fail, unless `restore()` ran before it (then `calls()` returns the cached record).
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
const fake = await obsidian.replace("my-plugin", "client.fetch", (delayMs: number) => async (path: string) => {
|
|
82
|
+
await new Promise((resolve) => setTimeout(resolve, delayMs));
|
|
83
|
+
return { path, items: [] };
|
|
84
|
+
}, 250);
|
|
85
|
+
await obsidian.runCommand("my-plugin:sync");
|
|
86
|
+
expect(await fake.calls()).toEqual([["/items"]]);
|
|
87
|
+
await fake.restore();
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The session fixture runs with its own timeout, so Playwright counts its time in a separate slot and the reported test duration covers the test body only; the launch time is in the annotation `obsidian-launch-ms`.
|
|
91
|
+
|
|
92
|
+
Do not add `waitForTimeout` sleeps: every helper waits on state. If a wait is too short for a slow machine, raise the matching `timeouts` entry (the failure message names it) and keep the helper budgets below the 60 s test timeout.
|
|
93
|
+
|
|
94
|
+
## Specs that run only on request
|
|
95
|
+
|
|
96
|
+
`onlyWhen("CAPTURE")` at the top of a spec file skips it unless `CAPTURE=1`, and a skipped file never starts Obsidian. Use it instead of `--grep-invert`.
|
|
97
|
+
|
|
98
|
+
## Failure artifacts
|
|
99
|
+
|
|
100
|
+
`defineObsidianConfig` keeps `trace`, `video` and `screenshot` on failure; the kit applies `use.trace` and `use.video` to the Obsidian window itself (Playwright does not for `_electron`). A red test leaves `test-results/<test>/obsidian-trace.zip` (open with `npx playwright show-trace <path>`) and a `.webm`. Playwright's own `trace.zip` has no Obsidian window. Read the trace before guessing.
|
|
101
|
+
|
|
102
|
+
## Cleanup
|
|
103
|
+
|
|
104
|
+
Teardown runs on pass, failure, timeout and setup errors: trace stopped (bounded by `timeouts.trace`), Obsidian closed (bounded by `timeouts.close`), the process tree ended, folders removed with retries. A folder or process that survives fails the test naming it. `opdk-e2e-*` temp folders older than `sweepAfterHours` are swept when a worker starts. After a run, `ls $TMPDIR | grep opdk-e2e` should print nothing.
|
|
105
|
+
|
|
106
|
+
## Common failures
|
|
107
|
+
|
|
108
|
+
- `Stale build: main.js of "<id>" ... is older than <file>`: run `opdk build` in that plugin's folder. To skip the check for one plugin, set `staleBuildCheck: false` on its `plugins` entry; `OPDK_E2E_ALLOW_STALE_BUILD=1` skips it for all plugins in one run.
|
|
109
|
+
- `npm ci` fails with `Permission denied (publickey)` in CI: the lockfile records the kit as `git+ssh://`. Rewrite the URL for one command with `GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=url.https://github.com/.insteadOf GIT_CONFIG_VALUE_0=ssh://git@github.com/ npm ci`; on a CI runner `git config --global url."https://github.com/".insteadOf ssh://git@github.com/` before `npm ci` does the same. Or write the dependency as `git+https://...`. (A public repository installs without it.)
|
|
110
|
+
- `Electron is installed ... but its binary is not downloaded yet`: `node node_modules/electron/install.js` once (the message prints the real path when Electron is hoisted).
|
|
111
|
+
- `Stopping the Obsidian trace took longer than N ms (timeouts.trace)`: a long traced test; raise `timeouts.trace`.
|
|
112
|
+
- `plugin still loading: <id>`: its `onload()` is slow or stuck (a view that is merely not drawn yet is not this: the spec has to wait for it). `plugin not loaded: <id>`: it never started; check `manifest.json` and `main.js`. Raise `timeouts.ready` only for a slow `onload()`.
|
|
113
|
+
- `The "Trust author and enable plugins" dialog is open`: the kit's trust flag did not apply on this Obsidian version. Report it with the version. Never click the dialog in a spec.
|
|
114
|
+
- `Cannot verify OBSIDIAN_VERSION=...`: the renderer did not answer the version request, so the pinned version could not be checked; the installed version may be right.
|
|
115
|
+
- `Obsidian version mismatch: expected X, but Y is running`: the installed Obsidian is not the one pinned.
|
|
116
|
+
- `Settings did not open in the main window: Obsidian opened it in a second window`: the seed vault's `app.json` sets `settingsPopoutWindow: true`; set it to false or remove the key.
|
|
117
|
+
- `The settings modal did not appear in the main window within N ms. Is a dialog covering the workspace?`: close what covers the workspace, or raise `timeouts.helpers.ui`.
|
|
118
|
+
|
|
119
|
+
## Migrating a plugin with its own harness
|
|
120
|
+
|
|
121
|
+
1. Add `@playwright/test`, `electron` and the kit.
|
|
122
|
+
2. Replace `e2e/fixtures.ts` with `createObsidianTest`. Delete the vault copy, `obsidian.json`, plugin install and `data.json` seeding (and `e2e-setup.sh`), the launch and dialog handling, the version reader, the folder removal.
|
|
123
|
+
3. Replace `playwright.config.ts` with `defineObsidianConfig()` plus only what is the plugin's own (`globalSetup`, other `testDir`).
|
|
124
|
+
4. Swap the plugin's helpers for `obsidian.*`: settings opener, palette and command runner, typing and reading the editor, IME loop, theme and metadata waits, notice removal, lazy-block scroll, the `emulateMobile` block, fake clients (`replace`).
|
|
125
|
+
5. Replace `--grep-invert` and env `test.skip` with `onlyWhen`. A plugin-specific vault variable becomes `OPDK_E2E_VAULT`.
|
|
126
|
+
6. Grep the plugin for callers of the old setup script (`e2e-setup.sh`, a capture script, `package.json` scripts, CI) and replace them with `opdk build`. Delete plugin folders committed or generated in the seed vault (`<seed>/.obsidian/plugins/<id>`; the kit's install overwrites them) and their `.gitignore` line; the seed's `community-plugins.json` is optional.
|
|
127
|
+
7. Expect these differences: `onlyWhen` needs the variable to be exactly `1` (old `test.skip(!process.env.X)` gates took any non-empty value); no sleeps (the fixture waits for `onload()`, not for the first render: a spec that relied on a sleep for a render needs its own wait for what it asserts); no Escape or `setEnable` on the trust dialog; cleanup failures are now failing tests; `editor().text()` throws without an editor (a hand-written helper may have returned `""`); `openFile` does not collapse side splits (use `collapseSidebars()`); an asar-version fallback is dropped; `compose()` always commits.
|
|
128
|
+
8. Run the specs, fix each difference, list the changes in the plugin's CHANGELOG.
|
|
129
|
+
|
|
130
|
+
## Limits today
|
|
131
|
+
|
|
132
|
+
Electron mode only (no CDP yet, so no downloaded Obsidian versions; `version` only checks the installed one, and a plugin whose harness launches over CDP (`E2E_LAUNCH=cdp`) keeps it for that). Verified on macOS with Obsidian 1.14.5; Linux CI later; Windows untested. The Obsidian window opens on screen during a run.
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: release
|
|
3
|
+
description: Check, cut and publish a GitHub release of an Obsidian plugin that uses obsidian-plugin-dev-kit (opdk) with `opdk release check`, `opdk release patch|minor|major|X.Y.Z`, `opdk release publish` and `opdk release notes`, move a plugin to a newer kit release with `opdk kit upgrade`, and set up the plugin's tag workflow that calls the kit's reusable `release.yml`. Use it to bump the version, tag, publish or verify a release, upgrade the kit (package.json tag, lockfile and workflow pins together), fix a failing `kit` step of the release check ("the kit is not pinned to one release"), resume a release that stopped ("no release workflow run started", "attestation does not verify", "origin rejected the push", "notes do not match the CHANGELOG"), read a failing release check, or move a plugin's own version-sync, make-zip and release-audit scripts to the kit. Not for build or bundle errors (build), scorecard warnings (scanner), Playwright specs (e2e) or films and screenshots (demo).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# opdk release module
|
|
7
|
+
|
|
8
|
+
`opdk release` checks a commit, bumps the version in every file, tags it, pushes only the tag, waits for the kit's reusable workflow, verifies its draft release and publishes it, and pushes the branch last. Run commands from the plugin root. The plugin id and version always come from `manifest.json`. Full docs: `node_modules/obsidian-plugin-dev-kit/docs/release.md`
|
|
9
|
+
|
|
10
|
+
## Safety
|
|
11
|
+
|
|
12
|
+
- Pushes are the owner's call. `opdk release patch|minor|major|X.Y.Z` and `opdk release publish` push a tag and a branch and publish a release; do not run them unless the owner asked for that release. `--dry-run` creates no commit or tag, pushes nothing and never calls `gh` (it does fetch from `origin` and ask it for the tag), so it is safe; so is `opdk release check`.
|
|
13
|
+
- Never force-push, and never delete or move a tag, a public release or a branch commit. The kit has no force flag. A bad release is fixed by a new patch version.
|
|
14
|
+
- Never edit a draft release's assets by hand.
|
|
15
|
+
- `opdk kit upgrade` edits `package.json`, the lockfile and the workflow files and runs `npm install`, but never commits or pushes; run it only when the owner asked to move to a kit release, on a clean tree, then show `git diff`. `--dry-run` writes nothing.
|
|
16
|
+
|
|
17
|
+
## Which command
|
|
18
|
+
|
|
19
|
+
- "Can this be released?": `opdk release check` (add `--tag X.Y.Z` to compare the tag; CI sets it from `GITHUB_REF_NAME`). Exit 1 with one `✗` line and a hint per problem; `!` lines are warnings.
|
|
20
|
+
- "Show me what a release would change": `opdk release patch --dry-run` (or `minor`, `major`, `X.Y.Z`). Runs everything but the commit, the tag and the pushes, prints the diff and restores the files; it still fetches from `origin`.
|
|
21
|
+
- "Cut the release": `opdk release patch|minor|major|X.Y.Z`. No `v` prefix, no pre-release version. Needs a clean tree on the default branch, neither behind nor ahead of `origin`, entries under `## [Unreleased]`, and `gh` signed in with write access. It runs the plugin's `npm test` first (`--no-test` skips it; no `test` script is only a warning).
|
|
22
|
+
- "Stop at the tag": add `--no-push`; continue later with `opdk release publish`.
|
|
23
|
+
- "It stopped": `opdk release publish X.Y.Z` (no version means the one in `manifest.json`). Every step checks what is done, so it is safe to repeat.
|
|
24
|
+
- "What goes in the release notes": `opdk release notes [X.Y.Z]` prints the CHANGELOG section.
|
|
25
|
+
- "Move to a newer kit release": `opdk kit upgrade --dry-run`, then `opdk kit upgrade [vX.Y.Z]` (latest release when no tag). See "Upgrading the kit".
|
|
26
|
+
|
|
27
|
+
Flags: `--no-build`, `--no-reproducible`, `--no-api` (check and bump), `--no-test` (bump only), `--tag` (check only), `--dry-run`, `--no-push`, `--timeout <minutes>` (default 20) and `--zip` (bump and publish).
|
|
28
|
+
|
|
29
|
+
## What the check covers
|
|
30
|
+
|
|
31
|
+
`versions` (manifest, package.json, lockfile, tag), `versions.json` (exists, current version maps to `minAppVersion`, never lowered; it and the other JSON files the release rewrites must be in `JSON.stringify` format), `manifest` (the official action's rules), `changelog` (a `## [X.Y.Z]` section with an entry), `kit` (package.json tag, the commit the lockfile resolved and every kit `uses:` line in `.github/workflows` name one release; offline), `build` (production build and the Node-only check), `assets`, `reproducible` (working tree against the committed tree, byte for byte) and `api` (`minAppVersion` against the API the code calls; needs `npm ci`). `opdk scan` is separate.
|
|
32
|
+
|
|
33
|
+
Reading failures:
|
|
34
|
+
|
|
35
|
+
- `reproducible` mismatch or "the committed tree does not build": a build input is untracked or ignored, or the output holds a path of this machine. Commit or fix it. pnpm, Yarn PnP and a repository without commits fall back to two builds of the working tree with a warning. `export-ignore` and Git LFS inputs make the comparison differ.
|
|
36
|
+
- `build` warning that `scripts.build` does not run `opdk build`: make it run `opdk build` (the directory rebuilds with that script, and the push flow compares the assets with an `opdk build` of the tag).
|
|
37
|
+
- `api` reports nothing for a plugin that surely uses new API: a tsconfig `paths` entry may point `obsidian` at a stub, which the rule cannot see through.
|
|
38
|
+
- `versions.json` missing: create it in the multi-line format the kit writes (two-space indent, one entry per line, final newline; `opdk release <bump>` creates it when missing, but `check` fails without it). An existing entry is never rewritten.
|
|
39
|
+
- A changelog problem: entries belong under `## [Unreleased]` before a release; `opdk release <bump>` moves them.
|
|
40
|
+
- `kit: the kit is not pinned to one release`: the output lists each place with the commit it names. Run `opdk kit upgrade <tag from package.json>` (or without a tag for the latest release); a workflow pinned to a tag or branch instead of a full SHA is fixed the same way. A kit installed from npm (a plain version in package.json) is not handled by `opdk kit upgrade`: follow the steps in the failure's hint. A plugin that does not call the kit's workflows is not affected.
|
|
41
|
+
- `ahead of origin` at the start of `opdk release`: the commits have not run CI. Push them through a pull request, wait for green, pull, rerun.
|
|
42
|
+
- `npm test failed`: nothing was changed. Fix the tests; `--no-test` only when they are known to be covered elsewhere.
|
|
43
|
+
|
|
44
|
+
## Upgrading the kit
|
|
45
|
+
|
|
46
|
+
The kit is pinned in `package.json` (`github:Dimagious/obsidian-plugin-dev-kit#vX.Y.Z`), in the lockfile (a commit) and in each kit `uses: ...@<sha> # vX.Y.Z` line of the workflows. `opdk kit upgrade [vX.Y.Z]` moves all three: it finds the latest `vX.Y.Z` tag with `git ls-remote --tags` (no login), rewrites `package.json`, runs `npm install` for that package (a minute: npm builds the kit; on failure `package.json` and the lockfile are put back, nothing else; run `npm ci` if `node_modules` looks off; without a lockfile npm does not run), rewrites the workflow lines with the new commit and `# vX.Y.Z`, runs the `kit` check, and prints the kit's CHANGELOG sections since the old version. Then: read the changelog, commit on a branch, open a pull request. Configure Dependabot to ignore the kit (a lone bump of one pin breaks the `kit` check; the two `ignore` entries are in docs/ci.md), and learn about new kit releases by watching the kit's releases on GitHub. Refuses a dirty tree (`--dry-run` does not). A plugin on v0.1.0 has no `kit` command (`unknown command "kit"`): run `npx -y -p github:Dimagious/obsidian-plugin-dev-kit#v0.3.2 opdk kit upgrade v0.3.2` once. Docs: `node_modules/obsidian-plugin-dev-kit/docs/ci.md`, section "Updating the kit".
|
|
47
|
+
|
|
48
|
+
## The push flow and its stops
|
|
49
|
+
|
|
50
|
+
Order: push the tag only, wait for the plugin's tag workflow (the one that calls the kit's `release.yml`), verify the draft (files, notes equal to the CHANGELOG at the tag, bytes equal to a local `opdk build` of the tag, attestations signed by the kit's `release.yml`), publish it, push the release commit to the default branch.
|
|
51
|
+
|
|
52
|
+
Every stop prints where it stopped, what is on `origin`, and either `Resume with: opdk release publish X.Y.Z` or says to release a new patch version.
|
|
53
|
+
|
|
54
|
+
- No workflow run within 3 minutes: the plugin's tag workflow does not call `Dimagious/obsidian-plugin-dev-kit/.github/workflows/release.yml@<full commit SHA of the kit>` (a copy does not work), or Actions are off. Fix the workflow and resume; the tag is not pushed twice.
|
|
55
|
+
- Workflow failed, cancelled or timed out: read the printed run URL. Release a new patch version, or re-run the failed jobs on GitHub (a failed run can leave a draft: delete it before re-running; `opdk release` stops when it finds two releases for one tag) and resume. After a timeout, wait for the run and resume with a larger `--timeout`.
|
|
56
|
+
- Draft does not match (assets, notes, bytes, attestation): nothing was published. Delete the draft, fix the cause, run `opdk release patch`. Resuming would stop at the same place.
|
|
57
|
+
- Public release but `origin` rejected the branch push: `git pull --no-rebase origin <branch>`, then `git push origin <branch>`, and do not rewrite the release commit. If the message says origin refused the push (a branch protection, a repository rule or a server hook), pulling will not help: get the release commit onto the branch the way the rule allows (a pull request, or an account that may bypass it). Never delete the public release.
|
|
58
|
+
- `gh` errors at the start: nothing was changed; `gh auth login` or `gh auth switch`, or use `--no-push`.
|
|
59
|
+
|
|
60
|
+
## Workflow and config
|
|
61
|
+
|
|
62
|
+
The plugin's tag workflow:
|
|
63
|
+
|
|
64
|
+
```yaml
|
|
65
|
+
name: Release
|
|
66
|
+
on:
|
|
67
|
+
push:
|
|
68
|
+
tags: ['*.*.*']
|
|
69
|
+
permissions:
|
|
70
|
+
contents: write
|
|
71
|
+
id-token: write
|
|
72
|
+
attestations: write
|
|
73
|
+
jobs:
|
|
74
|
+
release:
|
|
75
|
+
uses: Dimagious/obsidian-plugin-dev-kit/.github/workflows/release.yml@<full commit SHA of the kit>
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Inputs: `node-version` (default `"22"`) and `zip` (default `false`; add `--zip` to `opdk release` when on). Call the workflow, never copy it; pin the kit to a full commit SHA.
|
|
79
|
+
|
|
80
|
+
`opdk.config.mjs`, `release` section: `changelog` (default `CHANGELOG.md`, a path inside the plugin) and `defaultBranch` (default: from `origin/HEAD`; run `git remote set-head origin --auto` if it is unset).
|
|
81
|
+
|
|
82
|
+
## Migrating a plugin's scripts
|
|
83
|
+
|
|
84
|
+
Replace `version-sync.cjs` and `assert-versions.cjs` with `opdk release`, delete `make-zip.cjs` and `release-audit.cjs` (no zip by default), replace the plugin's `release.yml` with the caller above, make `scripts.build` run `opdk build`. The kit's workflow runs the release check and the build, not the plugin's tests or lint (`opdk release` itself runs `npm test` before the bump): keep those in branch CI (the kit's reusable `plugin-ci.yml` runs them with the release check, see `node_modules/obsidian-plugin-dev-kit/docs/ci.md`). Plugin-specific steps (generated files, a MAJOR-bump checklist) stay in the plugin and run before `opdk release`, because it needs a clean tree and its release commit holds only the version bump. A generated file that names the plugin version (a generated skill or reference file checked in CI with `--check`) has to be regenerated and committed after `opdk release`, or CI fails. If the plugin has no `versions.json` yet, create it first, multi-line (two-space indent, final newline), not on one line.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: scanner
|
|
3
|
+
description: Lint an Obsidian plugin for the community plugin scorecard with `opdk scan` and fix its findings. Use it for scorecard or scanner warnings (prefer-active-doc, prefer-window-timers, !important, :has, "assembles domain names"), for setting up `eslint.config.mjs` with `obsidianPlugin()`, or for replacing a plugin's scorecard-check.cjs and scanner.eslint.config.mjs. Not for build or bundle errors (build), tagging and publishing a release (release), Playwright specs (e2e) or films and screenshots (demo).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# opdk scanner module
|
|
7
|
+
|
|
8
|
+
Run all commands from the plugin root: `eslint-plugin-obsidianmd` reads `manifest.json` from the current directory. The plugin name always comes from `manifest.json`. Full docs: `node_modules/obsidian-plugin-dev-kit/docs/scanner.md`
|
|
9
|
+
|
|
10
|
+
## Commands
|
|
11
|
+
|
|
12
|
+
- `opdk scan`: no flags. Runs four steps over the files `git ls-files` lists in the plugin folder and exits 1 if any step has a finding (warnings from the scanner's ESLint config count):
|
|
13
|
+
- `lint`: the scanner's own ESLint configuration (mirror of `eslint-plugin-obsidianmd` 0.5.1 `docs/configuration.md`, "Community plugin scanner configuration"). Type information comes from the plugin's TypeScript, which must be 6 or newer: on 5.x or with none installed the scan fails before linting with `npm install -D typescript@6` as the fix (the scanner type-checks with 6, and 5.x hides its `moment(...)` warnings). A file no tsconfig covers prints one advisory `!` line (`outside-tsconfig`) and does not fail: the one scorecard compared does not list such files (an inference, not confirmed). A script that imports `obsidian-plugin-dev-kit` is linted as if the kit had no `dist/`, which is what the scorecard of one plugin suggests the scanner sees (also an inference). Only the test-setup files (`global-setup.*`, `*-global-setup.*`, `test-setup.*`, `setupTests.*`, `*.setup.*`) get the Node-module and other runtime rules the preset exempts them from, inferred from one scorecard; workers and other exempted files stay exempt. The `e2e/` folder is linted too (its `*.spec.*` files are not) with the same runtime rules except `prefer-active-doc` (the one scorecard seen does not list it there; it may never report it), but only the files a `tsconfig.json` covers show findings: an `e2e/tsconfig.json` brings them onto the scorecard, a root `tsconfig.e2e.json` keeps them off, and is the only fix for the `no-unsafe-*` findings caused by imports of the kit, which the scanner cannot resolve (an inference from two scorecards; `e2e-tests/` and `*.e2e.*` stay ignored). The scanner's ignore list leaves out `*.cjs`, `*.mjs`, `*.cts`, `*.mts`, tests, `scripts/`, `docs/`, locale folders and build output here.
|
|
14
|
+
- `css`: every tracked `.css`: `!important`, `:has()`, and features Chrome 142 (Obsidian 1.11.4) lacks or supports partly (doiuse).
|
|
15
|
+
- `code`: script files under `src/` (`.mjs`/`.cjs` included, unlike `lint`), tests excluded: a host assembled from `["a","b"].join(".")` (or `"/"`); `@ts-ignore`/`@ts-expect-error`/`@ts-nocheck` print as `!` and do not fail.
|
|
16
|
+
- `meta`: `manifest.json` description must not start with the plugin name.
|
|
17
|
+
- Findings print as `file:line rule message` under a `✗ <step>` line on stderr. Use the exit code, not the text.
|
|
18
|
+
|
|
19
|
+
## Needs git
|
|
20
|
+
|
|
21
|
+
Not a git repository, or nothing tracked: the command fails and says to `git init` / `git add`. Untracked files are not scanned: stage new files first. Build output is untracked, so it is skipped, as the scanner skips it.
|
|
22
|
+
|
|
23
|
+
## Config
|
|
24
|
+
|
|
25
|
+
There is none: the `scan` section of `opdk.config.mjs` has no keys. `scan.ignore` was removed because a skipped file was still on the public scorecard; a config that has it fails with `"scan.ignore" was removed`. To clear a finding, fix it or stop tracking the file (`git rm --cached`).
|
|
26
|
+
|
|
27
|
+
## `obsidianPlugin()` for the plugin's own lint
|
|
28
|
+
|
|
29
|
+
```js
|
|
30
|
+
// eslint.config.mjs (not .js: see below)
|
|
31
|
+
import { obsidianPlugin } from "obsidian-plugin-dev-kit/eslint";
|
|
32
|
+
export default [...obsidianPlugin({ rootDir: import.meta.dirname, ignores: ["site/**"] })];
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Options: `rootDir` (default `process.cwd()`), `tsconfig` (default `./tsconfig.json`), `ignores` (added to the defaults). It is obsidianmd's `recommended` preset plus `prefer-window-timers` and `settings-tab/prefer-setting-definitions` as errors, a bare `window.<member>` as an error (use `activeWindow`; `window.open` and the timer functions are exempt; a handler parameter named `window`, as in `workspace.on("window-open")`, is reported too, so rename it; the community scanner does not report it, so `opdk scan` does not either; opt out with `"no-restricted-syntax": "off"` in a later block) and strict unused-variable rules. Run `eslint . --max-warnings=0`. Do not enable `@typescript-eslint/no-misused-promises`: the preset swaps in `obsidianmd/no-misused-promises`.
|
|
36
|
+
|
|
37
|
+
## Fixing common findings
|
|
38
|
+
|
|
39
|
+
- `obsidianmd/prefer-active-doc`: `document.x` becomes `activeDocument.x` (`window` is left alone).
|
|
40
|
+
- `obsidianmd/prefer-window-timers`: `setTimeout(...)` and `activeWindow.setTimeout(...)` become `window.setTimeout(...)`; same for `setInterval`, `clearTimeout`, `clearInterval`, `requestAnimationFrame`, `cancelAnimationFrame`. Only `activeWindow.requestAnimationFrame` and `activeWindow.cancelAnimationFrame` are left alone.
|
|
41
|
+
- `no-restricted-syntax` (bare `window`): `window.innerWidth` becomes `activeWindow.innerWidth`; `window.open` and the timer functions stay on `window`.
|
|
42
|
+
- A Node module on mobile: a dynamic `import()` guarded by `Platform.isDesktop`, never a static import. The preset leaves `@typescript-eslint/no-require-imports` off, like upstream.
|
|
43
|
+
- `obsidianmd/prefer-create-el`: `el.createEl("div", {...})` becomes `el.createDiv({...})`.
|
|
44
|
+
- `no-domain-assembly`: write the URL as one string literal.
|
|
45
|
+
- `css-no-important`: raise the selector's specificity. `css-no-has`: put a class on the element from TS. `css-browser-feature/<name>`: check the feature on caniuse for Chrome 142; "partially supported" is reported on the public scorecard too. `@typescript-eslint/no-unsafe-*`: an `any` or unresolved type flows into the value; type it. On `moment(...)` imported from `obsidian` the scan reports call, member access and return, as the scorecard does: it type-checks under TypeScript 6, which forces `esModuleInterop` on (the plugin's own `tsc` on TypeScript 6 reports the same line as TS2349). Cast `moment` to a small typed function (see "Differences from the public scorecard" in docs/scanner.md).
|
|
46
|
+
- `@typescript-eslint/no-unsafe-call` and `no-unsafe-assignment` on a line in `eslint.config.js` or `.ts` that calls `obsidianPlugin()` from the kit: the scanner appears to install without building the kit, so the import is unresolved there (inferred from one scorecard). Rename the file to `eslint.config.mjs`: the scanner ignores `.mjs` files and `obsidianPlugin({ rootDir: import.meta.dirname })` works from it. Do not add a block `eslint-disable` comment: it fails the plugin's own lint (unused directive, `eslint-comments/disable-enable-pair`).
|
|
47
|
+
- `manifest-description-no-name-prefix`: reword the description so it does not begin with the plugin name.
|
|
48
|
+
- The scan does not know which tracked files are plugin code: stylesheets a repository keeps besides the plugin (a docs site, demos) are checked by the same rules, because the scanner reads every tracked `.css`. Fix them, or move them out of the repository.
|
|
49
|
+
|
|
50
|
+
## Migrating a plugin's scripts
|
|
51
|
+
|
|
52
|
+
1. `npm install --save-dev github:Dimagious/obsidian-plugin-dev-kit#v0.3.2` (exact tag). Keep `eslint` as the plugin's own devDependency (peer of the kit, `^9.19.0 || ^10.0.0`) and `typescript` (peer, `>=6.0.0 <6.1.0`; `npm install -D typescript@6`, then fix what `tsc` reports). Add `eslint` explicitly: without an `eslint` devDependency npm installs ESLint 9 on its own, because the plugins nested under obsidianmd peer on `^9`. Then, in order:
|
|
53
|
+
- (a) Remove the plugin's own `eslint-plugin-obsidianmd`, `typescript-eslint`, `@eslint/js` (unused once `obsidianPlugin()` replaces its config), `postcss`, `doiuse`, and `esbuild` if no script calls it directly. The kit pins them.
|
|
54
|
+
- (b) Run `npm install`. On ESLint 10 it may print `ERESOLVE overriding peer dependency` warnings and `npm ls` exits 1. Both come from obsidianmd's own peers, cannot be fixed in the kit, and the install works. `loglevel=error` in the plugin's `.npmrc` quiets them but hides other warnings too.
|
|
55
|
+
- (c) Run `npm explain eslint`, see step 3.
|
|
56
|
+
2. Replace `"scorecard:check": "node scripts/scorecard-check.cjs"` with `"scorecard:check": "opdk scan"`; delete `scripts/scorecard-check.cjs`, and `scripts/scanner.eslint.config.mjs` if present.
|
|
57
|
+
3. Replace the plugin's `eslint.config.js` with an `eslint.config.mjs` that uses `obsidianPlugin(...)` (delete the `.js`) plus its own extra blocks; set `lint` to `eslint . --max-warnings=0`. `DEFAULT_IGNORES` is only what three real plugins all left out (12 paths: `node_modules`, `coverage`, `dist`, `main.js`, `scripts`, `src/**/*.test.ts`, `vitest.config.ts`, `e2e`, `e2e-vault.pristine`, `playwright.config.ts`, `.obsidian-unpacked`, `design`). Pass the rest through `ignores`, taken from the plugin's current `eslint.config.js`. Typical extras are `site/**` and `_site/**` (a docs site), `.preview/**` and `.capture/**` (generated folders), `test-results/**` and `playwright-report/**` (Playwright output), `tools/**`, and `src/test/**` (test stubs; keeping the preset off them avoids hundreds of problems in code that never ships).
|
|
58
|
+
Then (after step 1 (a) and (b)) run `npm explain eslint`. A nested ESLint 9 under eslint-plugin-obsidianmd is fixed by adding `"overrides": { "eslint": "$eslint" }` to `package.json` and running `npm install` again (`npm dedupe` does not help). Removing the plugin's own obsidianmd (step (a)) stays the first step but is not always enough: one plugin still had the nested 9 after it and needed the override, another did not. The alternative is a `js.configs.recommended` block in the plugin's own config, which needs `@eslint/js` kept or added back (`opdk scan` warns about the mismatch too).
|
|
59
|
+
4. Differences to expect: see the "Scanner" entries in the kit's CHANGELOG. In short: the regex checks that an ESLint rule now covers are gone, `site/` stylesheets are scanned, and a plugin with no CSS no longer fails. If your plugin had no ESLint scanner step before, expect it to report findings on the committed tree (see the CHANGELOG for examples).
|
|
60
|
+
5. Run `opdk scan` and fix or consciously ignore each finding before releasing.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: unit
|
|
3
|
+
description: Set up, extend or fix the Vitest unit tests of an Obsidian plugin that uses obsidian-plugin-dev-kit (opdk) with `defineUnitConfig()` from `obsidian-plugin-dev-kit/vitest`. Use it for a `vitest.config.ts`, the coverage gate (thresholds, "Coverage for branches does not meet global threshold", `coverage.include`, lcov for Codecov), choosing which test files run in jsdom, "document is not defined" or "createDiv is not defined" or "installObsidianDom() needs a DOM" failures, the `obsidian` alias or obsidian-test-mocks, Obsidian's DOM helpers in jsdom (`createEl`, `setText`, `addClass`, `activeDocument`), a slow Vitest run that boots jsdom for every file, or moving a plugin's own vitest config and DOM polyfill to the kit. Not for Playwright specs in the real Obsidian (e2e), build or bundle errors (build), scorecard warnings (scanner), demo films (demo) or tagging a release (release).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# opdk unit module
|
|
7
|
+
|
|
8
|
+
`defineUnitConfig()` returns a plain Vitest config: tests in `src/**/*.test.ts`, v8 coverage with the gate 90 lines, functions and statements and 80 branches, an `obsidian` alias, and a split between node and jsdom. Run commands from the plugin root. The `test` script stays `vitest run --coverage`; the kit adds no command. Full docs: `node_modules/obsidian-plugin-dev-kit/docs/unit.md`
|
|
9
|
+
|
|
10
|
+
## Safety
|
|
11
|
+
|
|
12
|
+
- Unit tests never start Obsidian. Do not launch the Obsidian app to check a helper; its behaviour is in `docs/unit.md`, and reading it from `app.asar` is the only way to verify more.
|
|
13
|
+
- `obsidian-plugin-dev-kit/vitest/dom` ports the app helpers a plugin meets: the create family (`createEl`, `createDiv`, `createSpan`, `createSvg`, `createFragment`), `setText`, class and attribute helpers, `detach`, `insertAfter`, `indexOf`, `setChildrenInPlace`, `matchParent`, `toggleVisibility`, delegated `on`/`off`, `trigger`, `fish`/`fishAll`, `sleep`, `nextFrame`. Check `docs/unit.md` before writing a hand polyfill: it lists what is not ported and how a test stubs the missing browser APIs.
|
|
14
|
+
- Do not lower a threshold to make a run pass. `thresholds` below the default throw unless `allowLowerThresholds: true`; set that only when the owner decided so.
|
|
15
|
+
- Do not move a file to `coverage.exclude` to hide a gap without a comment saying why; the gate is a floor, and an excluded file escapes it.
|
|
16
|
+
|
|
17
|
+
## Set up a plugin
|
|
18
|
+
|
|
19
|
+
1. devDependencies: `vitest` and `@vitest/coverage-v8` at the same `^5` version, `vite` (`^6.4 || ^7 || ^8`; a peer of Vitest 5 that npm installs automatically, listed so `package.json` pins it), `jsdom` `^30` when some tests need a DOM, and the kit pinned to an exact tag (the kit declares none of these as peers; `defineUnitConfig()` checks their versions and throws with the install command). Vitest 5 needs Node 22.12 or newer (22.22.2 with jsdom).
|
|
20
|
+
2. `vitest.config.ts`:
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
import { defineUnitConfig } from "obsidian-plugin-dev-kit/vitest";
|
|
24
|
+
|
|
25
|
+
export default defineUnitConfig({
|
|
26
|
+
rootDir: import.meta.dirname,
|
|
27
|
+
obsidian: "./src/test/stubs/obsidian.ts",
|
|
28
|
+
dom: ["src/ui/**/*.test.ts"],
|
|
29
|
+
coverage: { include: ["src/**/*.ts"], exclude: ["src/main.ts", "src/types.ts"] },
|
|
30
|
+
});
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
3. `"test": "vitest run --coverage"` in `package.json`. Coverage is on in the config, so `vitest run --coverage.enabled=false` is the quick run.
|
|
34
|
+
|
|
35
|
+
Options: `coverage.include` (required), `coverage.exclude` (added to `**/*.test.ts`, `src/test/**`, `**/*.d.ts`), `coverage.thresholds` (raise only), `coverage.allowLowerThresholds`, `coverage.extraReporters` (`"lcov"`, `"html"`; `text` and `json-summary` are always on), `obsidian` (stub path, `"obsidian-test-mocks"`, or `{ node: "<stub path>", dom: "obsidian-test-mocks" | "<stub path>" }`), `dom` (globs, or `"all"`), `include` (default `["src/**/*.test.ts"]`), `rootDir` (pass `import.meta.dirname`). An unknown key, or a value of the wrong type, throws and names the option.
|
|
36
|
+
|
|
37
|
+
## Choose the dom globs
|
|
38
|
+
|
|
39
|
+
Tests run in node unless listed in `dom`. To find the files that need a DOM:
|
|
40
|
+
|
|
41
|
+
1. Start with no `dom` and run `npx vitest run --coverage.enabled=false`.
|
|
42
|
+
2. A file that needs the DOM fails with `ReferenceError: document is not defined`, `window is not defined`, `DOMParser is not defined`, or `createDiv is not defined` (or `createEl`, `createSpan`, `createFragment`, `activeDocument`, `activeWindow`). To list the failing files (needs a POSIX shell): `npx vitest run --no-color --coverage.enabled=false 2>&1 | grep -E "^ FAIL " | sed 's/^ FAIL //; s/^|[^|]*| //; s/ \[.*//; s/ >.*//' | sort -u` (it lists every failing file, so read each error first).
|
|
43
|
+
3. Add those files (a directory glob such as `src/ui/**/*.test.ts` when the whole folder is DOM code, single paths otherwise) to `dom`, relative to the folder of `vitest.config.ts`, and run again until green.
|
|
44
|
+
|
|
45
|
+
`dom: "all"` puts every file in jsdom (slow, but one project). Do not list files that pass in node: each jsdom file pays the start-up cost. A `// @vitest-environment jsdom` comment in a node-project file gives jsdom without the Obsidian helpers; list the file in `dom` instead, or call `installObsidianDom()` from `obsidian-plugin-dev-kit/vitest/dom` in it.
|
|
46
|
+
|
|
47
|
+
## Read a failure
|
|
48
|
+
|
|
49
|
+
- `installObsidianDom() needs a DOM and this test runs in the node environment`: the file calls the install in node. List it in `dom`, or add `// @vitest-environment jsdom`.
|
|
50
|
+
- `defineUnitConfig(): "coverage.include" is required`: add the globs of the files the gate counts, for example `["src/**/*.ts"]`. Without them Vitest reports only imported files and an untested file escapes the gate.
|
|
51
|
+
- `threshold "branches: 70" is below the default 80`: raise the coverage. `allowLowerThresholds: true` lowers it on purpose.
|
|
52
|
+
- `Coverage for <metric> (x%) does not meet global threshold (y%)`: add tests for the files in the `text` table. A fully covered file is hidden from the table when Vitest detects an agent; read `coverage/coverage-summary.json`, or add a `["text", { skipFull: false }]` reporter through `mergeConfig` to show them.
|
|
53
|
+
- `obsidian "obsidian-test-mocks" patches the DOM and needs a DOM environment`: mocks mode needs `dom` globs or `"all"`.
|
|
54
|
+
- A node-project test cannot resolve `obsidian` in mocks mode (`Failed to resolve entry for package "obsidian"`): the alias is in the `dom` project only. Use `obsidian: { node: "<stub path>", dom: "obsidian-test-mocks" }`, keep the file free of `obsidian` imports, or list it in `dom`.
|
|
55
|
+
- `defineUnitConfig(): "obsidian.node" ...` or `"obsidian.dom" ...`: the `{ node, dom }` form needs both keys as non-empty strings, and `node` cannot be `"obsidian-test-mocks"`.
|
|
56
|
+
- `"coverage.allowLowerThresholds" must be true or false`: pass a boolean, not a string.
|
|
57
|
+
- `defineUnitConfig(): "<package>" <version> is installed; the kit needs ...` (or `is not installed`): run the `Run: npm install --save-dev ...` command in the message. `vitest` must be 5, `@vitest/coverage-v8` the same version, `jsdom` 30 or newer when `dom` is used. `ERESOLVE` between `vitest` and `@vitest/coverage-v8`: the same cause, two versions of the pair. `webidl.util.markAsUncloneable is not a function`: Node is older than jsdom 30 supports (22.22.2, 24.15 or 26).
|
|
58
|
+
- Many tests fail after a plugin moves from Vitest 3 to 5, with `vi.fn(arrow)` used as a constructor in an `obsidian` mock (`Notice`): use a `class` or `function` in the mock.
|
|
59
|
+
- `isShown()` is true in jsdom for an element in the document without `display: none` (inline, on itself or an ancestor); the app asks for layout, which jsdom does not have. `scrollIntoView` is a no-op.
|
|
60
|
+
|
|
61
|
+
## Mocks mode
|
|
62
|
+
|
|
63
|
+
`obsidian-test-mocks` is the recommended way to test UI code (settings tabs, modals); the kit has no mock of its own. `obsidian: "obsidian-test-mocks"` uses that package's `vitest-setup` and its `obsidian` module in the `dom` project and skips the kit's polyfill, because the package installs the same helpers. When node tests also import `obsidian`, keep the plugin's stub for them: `obsidian: { node: "./src/test/stubs/obsidian.ts", dom: "obsidian-test-mocks" }`.
|
|
64
|
+
|
|
65
|
+
- Install it in the plugin, pinned to an exact version (no `^`), and set Dependabot to ignore major updates for it: new majors come often.
|
|
66
|
+
- Its peers: `obsidian`, `moment`, `@codemirror/view`, `@codemirror/state` (jest or vitest, optional). The `dom` project also needs `jsdom` in the plugin.
|
|
67
|
+
- Known gaps in 8.0.0 (check the package README): declarative `control` setting rows are not modelled (`renderTab` throws), `SettingTab.update()` does not redraw, `Modal.open()` closes on the next tick (call `onOpen()` directly), and reading a private app property the mock does not model throws (assign it on the mock in the test).
|
|
68
|
+
- Do not switch a plugin to it unless the user asks.
|
|
69
|
+
|
|
70
|
+
## Lcov for a coverage service
|
|
71
|
+
|
|
72
|
+
`coverage.extraReporters: ["lcov"]` writes `coverage/lcov.info`. A coverage service such as Codecov reads it. Add `"html"` for a local report.
|
|
73
|
+
|
|
74
|
+
## Type-check the tests
|
|
75
|
+
|
|
76
|
+
Recommended: type-check the `*.test.ts` files, but through a `tsconfig.test.json` (`extends` the root, `lib` `["ES2022", "DOM", "DOM.Iterable"]`, `noEmit`, `include` the sources, tests and `src/test`) and a script such as `tsc -p tsconfig.test.json`, so the plugin's own tsconfig keeps its target `lib`. Not required by the preset.
|
|
77
|
+
- A relative import that climbs one level too far lands on the root `main.js` (the bundle): `tsc -p tsconfig.test.json` with `strict` reports TS7016, Vitest runs it as `any`. Import from the source file (`src/main.ts`) through the right relative path. (In one folder TypeScript prefers `main.ts` over `main.js`.)
|
|
78
|
+
- `obsidianPlugin()` ignores `src/**/*.test.ts` in lint (`DEFAULT_IGNORES`), so tests are not linted; helper files such as `src/test/helpers.ts` are, unless the plugin puts them in `ignores`. The type check is what covers the tests.
|
|
79
|
+
|
|
80
|
+
## `isolate: false`
|
|
81
|
+
|
|
82
|
+
Only on request, never a default (the preset does not set it). Add `{ test: { isolate: false } }` with `mergeConfig`, and accept it only when every run passes: `vitest run --maxWorkers=1 --sequence.shuffle --sequence.seed=N` for several seeds, the default order on one worker, and the default order on two and three workers. Many-worker shuffles hide leaks (each worker gets few files). Typical leaks: a `vi.mock` that never reaches a module another file loaded, the `moment` locale, date and locale overrides, DOM left in `document`, globals. Of three plugins, one gained 3x after four fixes, one gained nothing, one gained 1.8x but failed on one worker. See `node_modules/obsidian-plugin-dev-kit/docs/unit.md`.
|
|
83
|
+
|
|
84
|
+
## Migrating a plugin
|
|
85
|
+
|
|
86
|
+
1. On Vitest 3 or older, bump to 5 first (with `@vitest/coverage-v8` and `jsdom`), as its own change. Mocks that use `vi.fn(arrow)` as a constructor (a `Notice` mock, for example) fail on Vitest 5: use a `class` or `function`.
|
|
87
|
+
2. Delete the plugin's own copy of Obsidian's DOM helpers and its `setupFiles` entry, and the calls that install the helpers by hand in `beforeAll`. The files that needed them join `dom`. Remove `environment`, `coverage.reportsDirectory` and the setup file of the old DOM polyfill from the old config (the preset adds its own to the `dom` project, or to the root with `dom: "all"`). Keep other setup files and add them with `mergeConfig`.
|
|
88
|
+
3. Replace `vitest.config.ts` with `defineUnitConfig()`, point `obsidian` at the existing stub, copy the coverage lists, and move extra reporters (`lcov`, `html`) to `extraReporters`.
|
|
89
|
+
4. Find the `dom` globs with the method above. Files that ran in jsdom without needing it now run in node: list that in the plugin's CHANGELOG, and run its e2e after.
|
|
90
|
+
5. A plugin with no DOM tests leaves `dom` out.
|