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.
Files changed (329) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +223 -2
  3. package/bin/opdk.js +34 -0
  4. package/dist/build/args.d.ts +10 -0
  5. package/dist/build/args.js +45 -0
  6. package/dist/build/bundle-check.d.ts +17 -0
  7. package/dist/build/bundle-check.js +42 -0
  8. package/dist/build/bundle-file.d.ts +4 -0
  9. package/dist/build/bundle-file.js +29 -0
  10. package/dist/build/commands.d.ts +5 -0
  11. package/dist/build/commands.js +109 -0
  12. package/dist/build/config.d.ts +3 -0
  13. package/dist/build/config.js +103 -0
  14. package/dist/build/css-imports.d.ts +23 -0
  15. package/dist/build/css-imports.js +50 -0
  16. package/dist/build/css-step.d.ts +10 -0
  17. package/dist/build/css-step.js +27 -0
  18. package/dist/build/css.d.ts +24 -0
  19. package/dist/build/css.js +47 -0
  20. package/dist/build/options.d.ts +55 -0
  21. package/dist/build/options.js +70 -0
  22. package/dist/build/release.d.ts +5 -0
  23. package/dist/build/release.js +34 -0
  24. package/dist/build/report.d.ts +7 -0
  25. package/dist/build/report.js +16 -0
  26. package/dist/build/vault.d.ts +26 -0
  27. package/dist/build/vault.js +290 -0
  28. package/dist/build-info.json +1 -0
  29. package/dist/cli/argv.d.ts +14 -0
  30. package/dist/cli/argv.js +18 -0
  31. package/dist/cli/commands.d.ts +3 -0
  32. package/dist/cli/commands.js +7 -0
  33. package/dist/cli/main.d.ts +2 -0
  34. package/dist/cli/main.js +23 -0
  35. package/dist/cli/process-reporter.d.ts +5 -0
  36. package/dist/cli/process-reporter.js +15 -0
  37. package/dist/cli/registry.d.ts +4 -0
  38. package/dist/cli/registry.js +15 -0
  39. package/dist/cli/reporter.d.ts +53 -0
  40. package/dist/cli/reporter.js +100 -0
  41. package/dist/cli/run.d.ts +9 -0
  42. package/dist/cli/run.js +61 -0
  43. package/dist/cli/types.d.ts +27 -0
  44. package/dist/cli/types.js +1 -0
  45. package/dist/cli/version.d.ts +13 -0
  46. package/dist/cli/version.js +61 -0
  47. package/dist/config/define-config.d.ts +3 -0
  48. package/dist/config/define-config.js +4 -0
  49. package/dist/config/load-config.d.ts +6 -0
  50. package/dist/config/load-config.js +70 -0
  51. package/dist/config/manifest.d.ts +3 -0
  52. package/dist/config/manifest.js +72 -0
  53. package/dist/config/types.d.ts +146 -0
  54. package/dist/config/types.js +23 -0
  55. package/dist/demo/args.d.ts +4 -0
  56. package/dist/demo/args.js +13 -0
  57. package/dist/demo/checks.d.ts +56 -0
  58. package/dist/demo/checks.js +124 -0
  59. package/dist/demo/commands.d.ts +3 -0
  60. package/dist/demo/commands.js +65 -0
  61. package/dist/demo/config.d.ts +57 -0
  62. package/dist/demo/config.js +337 -0
  63. package/dist/demo/ffmpeg-run.d.ts +18 -0
  64. package/dist/demo/ffmpeg-run.js +59 -0
  65. package/dist/demo/ffmpeg.d.ts +63 -0
  66. package/dist/demo/ffmpeg.js +111 -0
  67. package/dist/demo/films.d.ts +46 -0
  68. package/dist/demo/films.js +134 -0
  69. package/dist/demo/phone-layout.d.ts +38 -0
  70. package/dist/demo/phone-layout.js +98 -0
  71. package/dist/demo/phone-render.d.ts +28 -0
  72. package/dist/demo/phone-render.js +124 -0
  73. package/dist/demo/published.d.ts +16 -0
  74. package/dist/demo/published.js +72 -0
  75. package/dist/demo/run.d.ts +31 -0
  76. package/dist/demo/run.js +397 -0
  77. package/dist/demo/stills.d.ts +21 -0
  78. package/dist/demo/stills.js +62 -0
  79. package/dist/e2e/artifacts.d.ts +27 -0
  80. package/dist/e2e/artifacts.js +90 -0
  81. package/dist/e2e/cleanup.d.ts +54 -0
  82. package/dist/e2e/cleanup.js +109 -0
  83. package/dist/e2e/config.d.ts +9 -0
  84. package/dist/e2e/config.js +42 -0
  85. package/dist/e2e/create-test.d.ts +37 -0
  86. package/dist/e2e/create-test.js +109 -0
  87. package/dist/e2e/demo/clip.d.ts +21 -0
  88. package/dist/e2e/demo/clip.js +44 -0
  89. package/dist/e2e/demo/create-demo.d.ts +42 -0
  90. package/dist/e2e/demo/create-demo.js +439 -0
  91. package/dist/e2e/demo/manifest.d.ts +76 -0
  92. package/dist/e2e/demo/manifest.js +168 -0
  93. package/dist/e2e/demo/names.d.ts +18 -0
  94. package/dist/e2e/demo/names.js +44 -0
  95. package/dist/e2e/demo/options.d.ts +22 -0
  96. package/dist/e2e/demo/options.js +59 -0
  97. package/dist/e2e/demo/ownership.d.ts +27 -0
  98. package/dist/e2e/demo/ownership.js +65 -0
  99. package/dist/e2e/demo/page-scripts.d.ts +82 -0
  100. package/dist/e2e/demo/page-scripts.js +250 -0
  101. package/dist/e2e/demo/png.d.ts +8 -0
  102. package/dist/e2e/demo/png.js +23 -0
  103. package/dist/e2e/demo/presets.d.ts +43 -0
  104. package/dist/e2e/demo/presets.js +20 -0
  105. package/dist/e2e/demo/privacy.d.ts +18 -0
  106. package/dist/e2e/demo/privacy.js +30 -0
  107. package/dist/e2e/demo/still-options.d.ts +22 -0
  108. package/dist/e2e/demo/still-options.js +68 -0
  109. package/dist/e2e/demo/types.d.ts +184 -0
  110. package/dist/e2e/demo/types.js +1 -0
  111. package/dist/e2e/electron-binary.d.ts +15 -0
  112. package/dist/e2e/electron-binary.js +30 -0
  113. package/dist/e2e/fixtures.d.ts +62 -0
  114. package/dist/e2e/fixtures.js +68 -0
  115. package/dist/e2e/gate.d.ts +4 -0
  116. package/dist/e2e/gate.js +8 -0
  117. package/dist/e2e/global-setup.d.ts +11 -0
  118. package/dist/e2e/global-setup.js +17 -0
  119. package/dist/e2e/helpers/commands.d.ts +14 -0
  120. package/dist/e2e/helpers/commands.js +56 -0
  121. package/dist/e2e/helpers/create-helpers.d.ts +24 -0
  122. package/dist/e2e/helpers/create-helpers.js +582 -0
  123. package/dist/e2e/helpers/device-metrics.d.ts +21 -0
  124. package/dist/e2e/helpers/device-metrics.js +25 -0
  125. package/dist/e2e/helpers/ime.d.ts +13 -0
  126. package/dist/e2e/helpers/ime.js +19 -0
  127. package/dist/e2e/helpers/layout-page-scripts.d.ts +103 -0
  128. package/dist/e2e/helpers/layout-page-scripts.js +224 -0
  129. package/dist/e2e/helpers/layout.d.ts +83 -0
  130. package/dist/e2e/helpers/layout.js +148 -0
  131. package/dist/e2e/helpers/mobile.d.ts +31 -0
  132. package/dist/e2e/helpers/mobile.js +26 -0
  133. package/dist/e2e/helpers/page-scripts.d.ts +194 -0
  134. package/dist/e2e/helpers/page-scripts.js +467 -0
  135. package/dist/e2e/helpers/settings.d.ts +8 -0
  136. package/dist/e2e/helpers/settings.js +16 -0
  137. package/dist/e2e/helpers/settle.d.ts +28 -0
  138. package/dist/e2e/helpers/settle.js +33 -0
  139. package/dist/e2e/helpers/types.d.ts +193 -0
  140. package/dist/e2e/helpers/types.js +1 -0
  141. package/dist/e2e/helpers/view-mode.d.ts +23 -0
  142. package/dist/e2e/helpers/view-mode.js +35 -0
  143. package/dist/e2e/index.d.ts +14 -0
  144. package/dist/e2e/index.js +4 -0
  145. package/dist/e2e/internals.d.ts +155 -0
  146. package/dist/e2e/internals.js +8 -0
  147. package/dist/e2e/obsidian-path.d.ts +17 -0
  148. package/dist/e2e/obsidian-path.js +31 -0
  149. package/dist/e2e/options.d.ts +123 -0
  150. package/dist/e2e/options.js +244 -0
  151. package/dist/e2e/page-scripts.d.ts +45 -0
  152. package/dist/e2e/page-scripts.js +53 -0
  153. package/dist/e2e/peers.d.ts +9 -0
  154. package/dist/e2e/peers.js +19 -0
  155. package/dist/e2e/plugins.d.ts +32 -0
  156. package/dist/e2e/plugins.js +119 -0
  157. package/dist/e2e/process-tree.d.ts +33 -0
  158. package/dist/e2e/process-tree.js +133 -0
  159. package/dist/e2e/readiness.d.ts +23 -0
  160. package/dist/e2e/readiness.js +63 -0
  161. package/dist/e2e/seed.d.ts +34 -0
  162. package/dist/e2e/seed.js +122 -0
  163. package/dist/e2e/session.d.ts +71 -0
  164. package/dist/e2e/session.js +266 -0
  165. package/dist/e2e/vault.d.ts +52 -0
  166. package/dist/e2e/vault.js +146 -0
  167. package/dist/e2e/version.d.ts +25 -0
  168. package/dist/e2e/version.js +40 -0
  169. package/dist/eslint/index.d.ts +2 -0
  170. package/dist/eslint/index.js +1 -0
  171. package/dist/eslint/obsidian-plugin.d.ts +49 -0
  172. package/dist/eslint/obsidian-plugin.js +115 -0
  173. package/dist/index.d.ts +3 -0
  174. package/dist/index.js +1 -0
  175. package/dist/kit/args.d.ts +7 -0
  176. package/dist/kit/args.js +21 -0
  177. package/dist/kit/commands.d.ts +3 -0
  178. package/dist/kit/commands.js +52 -0
  179. package/dist/kit/files.d.ts +3 -0
  180. package/dist/kit/files.js +24 -0
  181. package/dist/kit/pins.d.ts +89 -0
  182. package/dist/kit/pins.js +178 -0
  183. package/dist/kit/remote.d.ts +13 -0
  184. package/dist/kit/remote.js +33 -0
  185. package/dist/kit/runners.d.ts +11 -0
  186. package/dist/kit/runners.js +53 -0
  187. package/dist/kit/terminal-text.d.ts +6 -0
  188. package/dist/kit/terminal-text.js +20 -0
  189. package/dist/kit/upgrade.d.ts +26 -0
  190. package/dist/kit/upgrade.js +162 -0
  191. package/dist/peers/resolve.d.ts +8 -0
  192. package/dist/peers/resolve.js +28 -0
  193. package/dist/peers/versions.d.ts +30 -0
  194. package/dist/peers/versions.js +32 -0
  195. package/dist/release/api-check.d.ts +27 -0
  196. package/dist/release/api-check.js +119 -0
  197. package/dist/release/args.d.ts +40 -0
  198. package/dist/release/args.js +120 -0
  199. package/dist/release/assets.d.ts +21 -0
  200. package/dist/release/assets.js +35 -0
  201. package/dist/release/build-check.d.ts +43 -0
  202. package/dist/release/build-check.js +184 -0
  203. package/dist/release/build-script.d.ts +12 -0
  204. package/dist/release/build-script.js +30 -0
  205. package/dist/release/build-tagged.d.ts +26 -0
  206. package/dist/release/build-tagged.js +52 -0
  207. package/dist/release/bump.d.ts +24 -0
  208. package/dist/release/bump.js +58 -0
  209. package/dist/release/changelog.d.ts +25 -0
  210. package/dist/release/changelog.js +148 -0
  211. package/dist/release/check.d.ts +38 -0
  212. package/dist/release/check.js +150 -0
  213. package/dist/release/commands.d.ts +3 -0
  214. package/dist/release/commands.js +154 -0
  215. package/dist/release/committed-tree.d.ts +63 -0
  216. package/dist/release/committed-tree.js +118 -0
  217. package/dist/release/config.d.ts +3 -0
  218. package/dist/release/config.js +28 -0
  219. package/dist/release/gh-access.d.ts +14 -0
  220. package/dist/release/gh-access.js +45 -0
  221. package/dist/release/gh.d.ts +10 -0
  222. package/dist/release/gh.js +33 -0
  223. package/dist/release/git.d.ts +49 -0
  224. package/dist/release/git.js +111 -0
  225. package/dist/release/interrupt.d.ts +30 -0
  226. package/dist/release/interrupt.js +60 -0
  227. package/dist/release/json.d.ts +33 -0
  228. package/dist/release/json.js +81 -0
  229. package/dist/release/kit-check.d.ts +8 -0
  230. package/dist/release/kit-check.js +51 -0
  231. package/dist/release/manifest-rules.d.ts +23 -0
  232. package/dist/release/manifest-rules.js +255 -0
  233. package/dist/release/preflight.d.ts +10 -0
  234. package/dist/release/preflight.js +65 -0
  235. package/dist/release/problems.d.ts +24 -0
  236. package/dist/release/problems.js +11 -0
  237. package/dist/release/project-files.d.ts +14 -0
  238. package/dist/release/project-files.js +16 -0
  239. package/dist/release/publish-command.d.ts +21 -0
  240. package/dist/release/publish-command.js +83 -0
  241. package/dist/release/publish-git.d.ts +37 -0
  242. package/dist/release/publish-git.js +108 -0
  243. package/dist/release/publish-state.d.ts +29 -0
  244. package/dist/release/publish-state.js +70 -0
  245. package/dist/release/publish-verify.d.ts +41 -0
  246. package/dist/release/publish-verify.js +112 -0
  247. package/dist/release/publish-wait.d.ts +25 -0
  248. package/dist/release/publish-wait.js +56 -0
  249. package/dist/release/publish.d.ts +35 -0
  250. package/dist/release/publish.js +181 -0
  251. package/dist/release/release-assets.d.ts +39 -0
  252. package/dist/release/release-assets.js +68 -0
  253. package/dist/release/release.d.ts +37 -0
  254. package/dist/release/release.js +179 -0
  255. package/dist/release/remote.d.ts +12 -0
  256. package/dist/release/remote.js +15 -0
  257. package/dist/release/reproducible.d.ts +16 -0
  258. package/dist/release/reproducible.js +34 -0
  259. package/dist/release/run-tests.d.ts +5 -0
  260. package/dist/release/run-tests.js +17 -0
  261. package/dist/release/semver.d.ts +8 -0
  262. package/dist/release/semver.js +60 -0
  263. package/dist/release/version-rules.d.ts +28 -0
  264. package/dist/release/version-rules.js +63 -0
  265. package/dist/release/versions-json.d.ts +15 -0
  266. package/dist/release/versions-json.js +88 -0
  267. package/dist/release/workflow-run.d.ts +44 -0
  268. package/dist/release/workflow-run.js +71 -0
  269. package/dist/scanner/code-checks.d.ts +41 -0
  270. package/dist/scanner/code-checks.js +82 -0
  271. package/dist/scanner/commands.d.ts +3 -0
  272. package/dist/scanner/commands.js +43 -0
  273. package/dist/scanner/config.d.ts +7 -0
  274. package/dist/scanner/config.js +25 -0
  275. package/dist/scanner/css-check.d.ts +26 -0
  276. package/dist/scanner/css-check.js +63 -0
  277. package/dist/scanner/eslint-nesting.d.ts +16 -0
  278. package/dist/scanner/eslint-nesting.js +45 -0
  279. package/dist/scanner/findings.d.ts +23 -0
  280. package/dist/scanner/findings.js +21 -0
  281. package/dist/scanner/git-files.d.ts +16 -0
  282. package/dist/scanner/git-files.js +73 -0
  283. package/dist/scanner/lint.d.ts +47 -0
  284. package/dist/scanner/lint.js +163 -0
  285. package/dist/scanner/meta-checks.d.ts +8 -0
  286. package/dist/scanner/meta-checks.js +22 -0
  287. package/dist/scanner/outside-project.d.ts +19 -0
  288. package/dist/scanner/outside-project.js +20 -0
  289. package/dist/scanner/run.d.ts +19 -0
  290. package/dist/scanner/run.js +78 -0
  291. package/dist/scanner/scanner-config.d.ts +114 -0
  292. package/dist/scanner/scanner-config.js +207 -0
  293. package/dist/scanner/typescript-gate.d.ts +30 -0
  294. package/dist/scanner/typescript-gate.js +73 -0
  295. package/dist/vitest/build-config.d.ts +17 -0
  296. package/dist/vitest/build-config.js +106 -0
  297. package/dist/vitest/define-unit-config.d.ts +27 -0
  298. package/dist/vitest/define-unit-config.js +45 -0
  299. package/dist/vitest/dom/elements.d.ts +87 -0
  300. package/dist/vitest/dom/elements.js +291 -0
  301. package/dist/vitest/dom/index.d.ts +1 -0
  302. package/dist/vitest/dom/index.js +1 -0
  303. package/dist/vitest/dom/install.d.ts +8 -0
  304. package/dist/vitest/dom/install.js +261 -0
  305. package/dist/vitest/dom/setup.d.ts +1 -0
  306. package/dist/vitest/dom/setup.js +3 -0
  307. package/dist/vitest/index.d.ts +3 -0
  308. package/dist/vitest/index.js +2 -0
  309. package/dist/vitest/options.d.ts +92 -0
  310. package/dist/vitest/options.js +136 -0
  311. package/dist/vitest/peers.d.ts +10 -0
  312. package/dist/vitest/peers.js +51 -0
  313. package/dist/vitest/workspace-root.d.ts +7 -0
  314. package/dist/vitest/workspace-root.js +39 -0
  315. package/docs/build.md +232 -0
  316. package/docs/ci.md +182 -0
  317. package/docs/demo.md +364 -0
  318. package/docs/e2e.md +563 -0
  319. package/docs/release.md +374 -0
  320. package/docs/scanner.md +204 -0
  321. package/docs/unit.md +291 -0
  322. package/package.json +100 -4
  323. package/plugins/opdk/skills/audit/SKILL.md +81 -0
  324. package/plugins/opdk/skills/build/SKILL.md +79 -0
  325. package/plugins/opdk/skills/demo/SKILL.md +102 -0
  326. package/plugins/opdk/skills/e2e/SKILL.md +132 -0
  327. package/plugins/opdk/skills/release/SKILL.md +84 -0
  328. package/plugins/opdk/skills/scanner/SKILL.md +60 -0
  329. package/plugins/opdk/skills/unit/SKILL.md +90 -0
package/docs/e2e.md ADDED
@@ -0,0 +1,563 @@
1
+ # End-to-end tests
2
+
3
+ `obsidian-plugin-dev-kit/e2e` runs Playwright specs against the real Obsidian. Every test gets its own Obsidian process, its own copy of a seed vault and its own user-data folder; your built plugin is installed and trusted before the window opens, and the test starts only when the workspace and every plugin have finished loading. When the test ends, however it ends, the process tree and the folders are gone. A set of helpers drives Settings, the command palette, the editor (including IME composition), themes, the mobile layout, and swaps a plugin's network client for a fake.
4
+
5
+ ![Obsidian driven by the kit: in a note, text is typed key by key, the command palette finds a command, a notice appears, and the plugin's settings tab opens](media/e2e.gif)
6
+
7
+ It runs Obsidian through Electron (`_electron.launch` on Obsidian's `app.asar`). Attaching to the real Obsidian binary over CDP is not built yet; see [Limits today](#limits-today).
8
+
9
+ ## Why
10
+
11
+ Plugins that grow their own harness each pay separately for the same things:
12
+
13
+ - One plugin's specs broke on Obsidian 1.13 because Settings began to open in a second window. Five specs failed at once, and every harness has to work around it on its own.
14
+ - The "Trust author and enable plugins" dialog was handled by pressing Escape after a fixed wait, followed by sleeps to let plugins finish loading: waits of 800 ms and 500 ms and up to 5 s for the trust dialog in one harness, a fixed 1500 ms in two others. A slow start still raced them, and a plugin that never loaded was only noticed when a command was missing.
15
+ - Cleanup deleted the temp vault inside a `try` that ignored the error, so a folder Obsidian still held open stayed on disk, run after run.
16
+ - Playwright's `trace` and `video` options do not reach a window opened through `_electron`, so a red test left nothing to look at.
17
+
18
+ The kit fixes each of these once: the trust flag is set before the vault loads, readiness waits for plugin state, cleanup retries and then fails loudly with the path, and the Obsidian window gets its own trace and video.
19
+
20
+ ## What a test gets
21
+
22
+ `createObsidianTest` returns a Playwright `test` whose tests can ask for four fixtures:
23
+
24
+ | Fixture | Type | What it is |
25
+ |---|---|---|
26
+ | `win` | `Page` | The Obsidian window, workspace laid out, every installed plugin loaded |
27
+ | `app` | `ElectronApplication` | The Electron app; `app.evaluate` runs in the main process. It is the only way to reach `BrowserWindow`, `app.getVersion()` and the like |
28
+ | `vault` | `VaultHandle` | The per-test copy of the seed vault: `path`, `resolve(rel)`, `exists(rel)`, `read(rel)`, `write(rel, content)`. A path that leaves the vault throws |
29
+ | `obsidian` | `ObsidianHelpers` | The [helpers](#helpers), bound to this window |
30
+
31
+ `vault.write` is plain file system access. Obsidian's index (`app.vault.getFileByPath`, the metadata cache, the file explorer) learns of the new file only when its file watcher fires, a moment later. A spec that writes a file and then acts through the index, for example by opening it from the palette or clicking a link to it, races the watcher. Poll for the file first:
32
+
33
+ ```ts
34
+ import type { App } from "obsidian";
35
+
36
+ vault.write("notes/new.md", "# New\n");
37
+ // obsidian.evaluate runs in the page and passes Obsidian's `app`; the `app` fixture is the Electron app.
38
+ await expect
39
+ .poll(() => obsidian.evaluate((app: App, p: string) => app.vault.getFileByPath(p) !== null, "notes/new.md"))
40
+ .toBe(true);
41
+ ```
42
+
43
+ `obsidian.waitForMetadataCache()` is not a substitute for that poll: it only loops over the files already in `getMarkdownFiles()`, so it returns at once for a file the index has not seen yet. Poll for the file first, then call `waitForMetadataCache()` when the spec reads links, tags or frontmatter of it (or poll `app.metadataCache.getCache(p) !== null` the same way).
44
+
45
+ Obsidian's own `app` object (`app.workspace`, `app.plugins`) lives in the page, so you reach it with `win.evaluate`. The kit's helpers do that for the common cases.
46
+
47
+ ## Quick start
48
+
49
+ Install the kit and the two things it runs on. The kit does not declare them as peer dependencies (npm would refuse to install the kit next to an older Playwright or Electron, even in a plugin without e2e); the e2e `globalSetup` checks them before the first test and fails with the install command when `@playwright/test` is older than 1.62 (or not major 1) or `electron` is older than 39:
50
+
51
+ ```json
52
+ {
53
+ "scripts": {
54
+ "build": "opdk build",
55
+ "e2e": "npm run build && playwright test"
56
+ },
57
+ "devDependencies": {
58
+ "@playwright/test": "1.65.0",
59
+ "electron": "44.10.2",
60
+ "obsidian-plugin-dev-kit": "github:Dimagious/obsidian-plugin-dev-kit#v0.3.2"
61
+ }
62
+ }
63
+ ```
64
+
65
+ Replace `vX.Y.Z` with the latest tag and pin it exactly. The kit accepts `@playwright/test` `^1.62.0` and `electron` `>=39.0.0` and is developed against 1.65.0 and 44.10.2. Electron 42 and newer do not download their binary at install time but on first use (about 100 MB); 39 to 41 download it on install. Run `node node_modules/electron/install.js` once after installing (the script downloads the binary; `npx electron --version` would download it too, but it starts Electron), and in a fresh checkout and in CI cache the Electron download (the `ELECTRON_CACHE` folder) and run that command in a step before the tests. Without it the run fails once, before any test starts, saying exactly this, instead of every test timing out in the launch.
66
+
67
+ The tests drive the Obsidian that is installed on the machine. On macOS the kit finds `/Applications/Obsidian.app`; elsewhere, set `OBSIDIAN_PATH` or the `obsidianPath` option.
68
+
69
+ Make a seed vault, a folder the tests copy. It can be any path (`seedVault` is resolved against the directory `playwright test` runs in), and the smallest one is a `.obsidian` folder and a note. If you use the palette helpers, enable the command palette in it:
70
+
71
+ ```text
72
+ e2e/vault/.obsidian/core-plugins.json ["file-explorer", "command-palette"]
73
+ e2e/vault/Welcome.md # Welcome
74
+ ```
75
+
76
+ `e2e/fixtures.ts`:
77
+
78
+ ```ts
79
+ import { createObsidianTest } from "obsidian-plugin-dev-kit/e2e";
80
+
81
+ export const { test, expect, onlyWhen } = createObsidianTest({
82
+ seedVault: "e2e/vault",
83
+ });
84
+ ```
85
+
86
+ By default the plugin installed is the one in the current directory: `manifest.json` and `main.js` (and `styles.css` if there is one) in the folder you run `playwright test` in. The plugin id comes from `manifest.json`.
87
+
88
+ `playwright.config.ts`:
89
+
90
+ ```ts
91
+ import { defineObsidianConfig } from "obsidian-plugin-dev-kit/e2e";
92
+
93
+ export default defineObsidianConfig();
94
+ ```
95
+
96
+ A first spec, `e2e/smoke.spec.ts`:
97
+
98
+ ```ts
99
+ import { expect, test } from "./fixtures.js";
100
+
101
+ test("the plugin's command writes into the note", async ({ obsidian }) => {
102
+ await obsidian.openFile("Welcome.md", { mode: "source" });
103
+ await obsidian.editor().setCursor(1, 0);
104
+ await obsidian.runCommand("my-plugin:insert-date");
105
+ expect(await obsidian.editor().text()).toMatch(/\d{4}-\d{2}-\d{2}/);
106
+ });
107
+ ```
108
+
109
+ Run `npm run e2e`. Each test starts a real Obsidian window, so expect it to open and close once per test. Build before you test: the stale-build guard refuses a `main.js` that is older than your sources.
110
+
111
+ The preset from `defineObsidianConfig` sets `testDir: "e2e"`, one worker, no parallel files, a 60 s test timeout, a 10 s `expect` timeout, `forbidOnly` and one retry when the `CI` variable is set, the `list` reporter plus an HTML report (`list` only on CI), and `trace: "retain-on-failure"`, `video: "retain-on-failure"`, `screenshot: "only-on-failure"`, plus a `globalSetup` that checks the Electron binary once (your own `globalSetup`, a string or a list, runs after it). Pass overrides as the argument; they win, and `expect` and `use` are merged key by key:
112
+
113
+ ```ts
114
+ export default defineObsidianConfig({
115
+ timeout: 90_000,
116
+ use: { video: "on" },
117
+ });
118
+ ```
119
+
120
+ Obsidian opens one window per process and the specs share nothing, so they run one at a time. A cold start can take 15 to 20 seconds on a busy machine.
121
+
122
+ ### Typecheck the specs
123
+
124
+ A plugin's root `tsconfig.json` usually includes only `src/`, and may lack DOM, which `win.evaluate` callbacks reading `document` need. Specs pass functions to `win.evaluate` that read `document` and `window`, which needs the DOM library. Give the folder its own `e2e/tsconfig.json` that extends the root one:
125
+
126
+ ```json
127
+ {
128
+ "extends": "../tsconfig.json",
129
+ "compilerOptions": { "lib": ["ES2020", "DOM", "DOM.Iterable"], "types": ["node"] },
130
+ "include": ["./**/*.ts", "../playwright.config.ts"]
131
+ }
132
+ ```
133
+
134
+ and check it next to the plugin's own sources:
135
+
136
+ ```json
137
+ {
138
+ "scripts": {
139
+ "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p e2e/tsconfig.json --noEmit"
140
+ }
141
+ }
142
+ ```
143
+
144
+ The snippet needs `typescript` and `@types/node`; set the ES entry of `lib` to the level the root uses. It was checked on a project whose root `tsconfig.json` has `lib: ["ES2020"]`, `module: "ESNext"`, `moduleResolution: "Bundler"` and `strict`, with the quick-start `fixtures.ts`, `playwright.config.ts` and spec (and a typed `evaluate`) under `e2e/`.
145
+
146
+ ### Install from GitHub in CI
147
+
148
+ npm records a GitHub dependency in `package-lock.json` as `git+ssh://git@github.com/...`. For a public repository such as the kit this needs no SSH key: with SSH switched off (`GIT_SSH_COMMAND=false`), an empty npm cache and `npm ci`, the kit still installs, because npm fetches the tarball over https. If you install from a private fork, or `npm ci` fails with `Permission denied (publickey)`, tell git to use https for GitHub before installing. Locally, set it through the environment for one command:
149
+
150
+ ```sh
151
+ GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=url.https://github.com/.insteadOf GIT_CONFIG_VALUE_0=ssh://git@github.com/ npm ci
152
+ ```
153
+
154
+ On a CI runner, which is thrown away after the job, `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://github.com/Dimagious/obsidian-plugin-dev-kit.git#v0.3.2` in `package.json`.
155
+
156
+ ## What happens per test
157
+
158
+ 1. The kit checks everything that can be checked without creating anything: Obsidian's `app.asar` exists (`OBSIDIAN_PATH`, then `obsidianPath`, then the macOS default; the first one that is set must exist, with no silent fall-through), every plugin folder has `manifest.json` and a built `main.js`, plugin ids are unique, every `data` key is an installed plugin, and the `main.js` of each checked plugin is not older than the newest file under its `src/` (compared by modification time; a test file, whose name ends in `.test.<ext>` or `.spec.<ext>`, does not count, every other file does). Which plugins are checked is set by [`staleBuildCheck`](#stale-build-check). A plugin folder without `src/` is not checked for staleness.
159
+ 2. It checks that `electron` is installed and its binary is downloaded. The check runs once per run, in a global setup that `defineObsidianConfig` registers before your own `globalSetup`: a missing binary is one error and no test starts. A check in a fixture ran again for every test, because Playwright replaces a worker after each failed test and the fixture runs in the new one (59 tests gave 59 identical failures in one plugin). A config that does not use `defineObsidianConfig` has no global setup, so the session repeats the check for each test and a missing binary fails every test with the same message.
160
+ 3. It creates two temp folders, `opdk-e2e-vault-<title>-XXXXXX` (the test title lowercased, reduced to a-z, 0-9 and hyphens, and cut to 40 characters) and `opdk-e2e-userdata-XXXXXX`, and copies the seed vault into a `vault/` subfolder of the first with symlinks resolved, so nothing a test does reaches the repository or a linked build. A symlink loop or a dangling link fails the copy, naming the link.
161
+ 4. It writes `.obsidian/app.json` with `settingsPopoutWindow: false` and `alwaysUpdateLinks: true` unless the seed vault sets them (Settings in a popout is a second window the test does not drive, and renaming a file otherwise shows an "Update links?" modal that blocks forever).
162
+ 5. It copies each plugin's `main.js`, `manifest.json` and `styles.css` into `.obsidian/plugins/<id>/`, writes `community-plugins.json` as the ids the seed vault enables plus the installed ones, and writes `data.json` for every plugin in the `data` option (replacing a seeded one).
163
+ 6. It generates a vault id and writes `obsidian.json` into the user-data folder: the vault registered as the last opened (both auto-open markers), and `updateDisabled: true`, so Obsidian shows no vault picker and does not update itself during the run.
164
+ 7. It launches Obsidian: `_electron.launch` with the `app.asar`, `--user-data-dir=<temp folder>` and your `electronArgs`. The environment is yours minus `ELECTRON_RUN_AS_NODE` (it makes Electron reject Chromium flags) and `VAULT_PLUGIN` (the dev vault of `opdk build --vault` has no business in a test). The launch is bounded by `timeouts.launch`.
165
+ 8. It starts the trace when `use.trace` asks for one, so the startup is in it.
166
+ 9. It sets the plugin trust flag (`enable-plugin-<vaultId>` in `localStorage`) with an init script that runs before the vault loads. The "Trust author and enable plugins" dialog never opens, and the kit never clicks it: both of its buttons have side effects. If it opens anyway, the readiness wait fails and says so. Native `alert`, `confirm` and `prompt` dialogs are dismissed.
167
+ 10. It resizes the window when `window` is given.
168
+ 11. It waits, polling every 50 ms with no sleeps, until `app.workspace.layoutReady` is true and, for every installed plugin, `app.plugins.plugins[id]` exists and `app.plugins.loadingPluginId` is no longer that id. Obsidian registers a plugin before it awaits its `onload()`, so a command or settings tab that `onload()` adds after an `await` exists when the fixtures resolve. The wait is bounded by `timeouts.ready`; a timeout names the state: `plugin still loading: <id>`, `plugin not loaded: <id>`, the trust dialog being open, or that the workspace was not ready. It waits for every plugin's `onload()` to finish, not for what the plugin draws afterwards: a view, a code block or a reading-view render that happens after `onload()` may not exist yet when your test starts.
169
+ 12. It reads the running Obsidian version and puts it in the test report as the annotations `obsidian-version` and `launch-mode` (`electron`). When a version is pinned (`version` or `OBSIDIAN_VERSION`), the test also gets the annotation `obsidian-expected-version`, and it fails if the running version differs or cannot be read. Without a pinned version, an unreadable version is only recorded as `unknown`. The annotation `obsidian-launch-ms` holds the time from the launch call until the workspace and every plugin are ready.
170
+ 13. Your test runs.
171
+
172
+ Durations: 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: not the setup (steps 1 to 12) and not the teardown. The launch itself (steps 7 to 11) is in the annotation `obsidian-launch-ms`; the teardown is not measured. Wall time of a run is roughly the sum of the three.
173
+
174
+ ## Cleanup
175
+
176
+ Teardown runs when the test passes, fails, times out, and when any step above throws. In this order:
177
+
178
+ 1. The trace is stopped while the app is still open, bounded by `timeouts.trace`, and written only if the mode keeps it.
179
+ 2. Obsidian is closed, bounded by `timeouts.close` (Obsidian sometimes ignores a close request), and then the whole process tree is ended: the process group with SIGTERM and then SIGKILL on macOS and Linux, `taskkill /T /F` on Windows. A process that survives fails the test.
180
+ 3. The video is finished and kept or deleted per its mode.
181
+ 4. The user-data folder and the vault copy are removed, with retries, because Chromium helpers may still be writing for a moment after the main process exits. A folder that is still there after the retries fails the test, naming the path.
182
+
183
+ Every step runs even if an earlier one fails, and all failures are reported together. A setup error and a cleanup error are reported together too. The session fixture has its own timeout (launch + ready + 3 * close + 20 s), separate from the test timeout, so the kit's budgets fire first and the cleanup always gets to run.
184
+
185
+ A crashed or killed run (a `kill -9`, a power cut) cannot clean up after itself. When a worker starts, the kit removes `opdk-e2e-*` folders in the temp directory that are older than `sweepAfterHours` (default 2) and warns about any it cannot remove. `sweepLeftovers({ olderThanHours })` is exported if you want the same sweep in a `globalSetup`.
186
+
187
+ ## Options
188
+
189
+ `createObsidianTest(options)` checks the options when `e2e/fixtures.ts` is imported, so a typo fails before any Obsidian starts. An unknown key fails naming it and the allowed keys; a wrong value names the key and what it must be. Relative paths are resolved against the directory `playwright test` runs in.
190
+
191
+ | Option | Type | Default | Meaning |
192
+ |---|---|---|---|
193
+ | `seedVault` | string | required | The vault copied for every test. The env var `OPDK_E2E_VAULT` replaces it |
194
+ | `plugins` | `{ dir: string, staleBuildCheck?: boolean }[]` | the plugin in the current directory | Plugin folders to install, each holding `manifest.json`, the built `main.js` and, if the plugin has one, `styles.css`. A non-empty list; the same folder twice is an error. `staleBuildCheck` on an entry overrides the top-level option for that plugin, see [Stale build check](#stale-build-check) |
195
+ | `data` | `Record<pluginId, object>` | `{}` | `data.json` content per plugin, written before Obsidian starts. Replaces a `data.json` in the seed vault. A key that is not an installed plugin id is an error |
196
+ | `window` | `{ width, height }` | what Obsidian opens with | Window size in points |
197
+ | `obsidianPath` | string | the macOS install | Obsidian's `app.asar`. The env var `OBSIDIAN_PATH` replaces it. On other platforms one of the two is required |
198
+ | `electronArgs` | string[] | `[]` | Extra Electron arguments, for example `--use-mock-keychain`. `--user-data-dir` is refused: the kit gives every test its own |
199
+ | `version` | string | unset | Fail the test when the running Obsidian is not this `x.y.z`. The env var `OBSIDIAN_VERSION` replaces it. Channels such as `latest` are refused: the kit checks the installed Obsidian, it does not download versions |
200
+ | `timeouts.launch` | ms | 45000 | `_electron.launch` |
201
+ | `timeouts.ready` | ms | 30000 | From the window opening until the workspace and every plugin are loaded. Also bounds the reload in `mobile()`, `desktop()` and `reload()` |
202
+ | `timeouts.close` | ms | 5000 | How long `app.close()` may take before the process tree is killed. Also bounds finishing the video |
203
+ | `timeouts.trace` | ms | 60000 | How long stopping the Obsidian trace may take. The stop writes every snapshot and screenshot of the test to a zip, so it grows with the length of the test; raise it for a long traced test |
204
+ | `timeouts.helpers.settings` | ms | 15000 | A plugin's settings tab to register (`openSettings(tab)`) |
205
+ | `timeouts.helpers.metadataCache` | ms | 45000 | Every markdown file to have its metadata cached (`waitForMetadataCache()`) |
206
+ | `timeouts.helpers.compose` | ms | 5000 | CodeMirror to leave a composition and show the composed text (`compose()`) |
207
+ | `timeouts.helpers.theme` | ms | 5000 | The body to get the class of the theme (`setTheme()`) |
208
+ | `timeouts.helpers.ui` | ms | 10000 | A dialog, the palette, the editor or a view to appear or go away (`openCommandPalette()`, `openFile()`, `editor().type()`, `closeSettings()`, `settle()` and others) |
209
+ | `staleBuildCheck` | boolean | `true` | Refuse the plugin in the current directory when its `main.js` is older than its newest source file (by modification time; `.test.<ext>` and `.spec.<ext>` files do not count). Other `plugins` entries are not checked unless they set it themselves. `OPDK_E2E_ALLOW_STALE_BUILD=1` turns every check off for one run |
210
+ | `sweepAfterHours` | number or `false` | 2 | Remove `opdk-e2e-*` temp folders older than this when a worker starts. `false` disables it |
211
+
212
+ Every wait inside the helpers has a budget and a failure that names the wait and the option to raise. Keep the helper budgets below the Playwright test timeout (60000 in the preset), or the test is killed before the helper can explain what it waited for.
213
+
214
+ Several plugins, a seeded `data.json` and a window size:
215
+
216
+ ```ts
217
+ import { createObsidianTest } from "obsidian-plugin-dev-kit/e2e";
218
+
219
+ export const { test, expect, onlyWhen } = createObsidianTest({
220
+ seedVault: "e2e/vault",
221
+ plugins: [{ dir: "." }, { dir: "../my-other-plugin" }],
222
+ data: { "my-plugin": { units: "metric", language: "en" } },
223
+ window: { width: 1200, height: 900 },
224
+ electronArgs: ["--use-mock-keychain"],
225
+ timeouts: { ready: 45_000, helpers: { metadataCache: 60_000 } },
226
+ });
227
+ ```
228
+
229
+ ### Stale build check
230
+
231
+ A `main.js` older than the plugin's newest source file means the test would run code that no longer exists, so the kit refuses it and names both files. The check applies to the plugin in the current directory only; a second plugin from a sibling checkout (a dependency your plugin talks to) is installed as built and not checked. Its working tree is not yours to rebuild, and a source file touched by a `git pull` would otherwise fail every test. Switch it on or off per plugin:
232
+
233
+ ```ts
234
+ createObsidianTest({
235
+ seedVault: "e2e/vault",
236
+ plugins: [
237
+ { dir: "." }, // follows the top-level option (off in this example)
238
+ { dir: "../sibling-plugin" }, // not checked
239
+ { dir: "../other-plugin", staleBuildCheck: true }, // checked
240
+ ],
241
+ staleBuildCheck: false, // here: turns the check off for "." only
242
+ });
243
+ ```
244
+
245
+ An entry's own value always wins over the top-level one, and `OPDK_E2E_ALLOW_STALE_BUILD=1` wins over everything. The error message carries these three ways out. A plugin from a sibling checkout has to be built there (`opdk build` in its folder) before the run.
246
+
247
+ ### Environment variables
248
+
249
+ | Variable | Meaning |
250
+ |---|---|
251
+ | `OPDK_E2E_VAULT` | Replaces the `seedVault` option. A way to run the same specs on a copy of a real vault |
252
+ | `OBSIDIAN_PATH` | Replaces `obsidianPath`: Obsidian's `app.asar` |
253
+ | `OBSIDIAN_VERSION` | Replaces `version`: fail unless the running Obsidian is this `x.y.z` |
254
+ | `OPDK_E2E_ALLOW_STALE_BUILD` | `1` turns the stale-build guard off for every plugin for one run |
255
+ | `CI` | Read by the config preset: any value other than empty, `0` or `false` sets `forbidOnly`, one retry and the `list` reporter only |
256
+ | `ELECTRON_CACHE` | Electron's own: where its binary is downloaded. Cache it in CI |
257
+ | `ELECTRON_RUN_AS_NODE`, `VAULT_PLUGIN` | Removed from Obsidian's environment, see step 7 |
258
+
259
+ The kit does not read an env var for anything else. The names that gate your own specs are yours; see [Specs that run only on request](#specs-that-run-only-on-request).
260
+
261
+ ### Seeding one test's vault
262
+
263
+ `seed` is a per-test option, set with `test.use` for a file or a `describe` block. It adds files and `app.json` keys to that test's vault copy before Obsidian starts, so a spec does not write them and call `obsidian.reload()`:
264
+
265
+ ```ts
266
+ test.describe("with templates", () => {
267
+ test.use({
268
+ seed: {
269
+ files: {
270
+ "Daily/2026-03-14.md": "# Friday\n",
271
+ ".obsidian/templates.json": JSON.stringify({ folder: "Templates" }),
272
+ },
273
+ config: { propertiesInDocument: "hidden" },
274
+ },
275
+ });
276
+
277
+ test("inserts the template", async ({ obsidian }) => {
278
+ // Obsidian opened with the note, the templates setting and the hidden properties already in place.
279
+ });
280
+ });
281
+ ```
282
+
283
+ | Key | Type | Meaning |
284
+ |---|---|---|
285
+ | `files` | `Record<string, string>` | Vault-relative path to text. Folders are created; a file of the same path in the seed vault is replaced. A path may point into `.obsidian/`, except the files the kit writes (below). Empty, absolute, folder (trailing slash), `..`, `.` and `.obsidian` paths fail |
286
+ | `config` | `Record<string, unknown>` | Keys merged into `.obsidian/app.json` over the seed vault's and the kit's defaults (`settingsPopoutWindow`, `alwaysUpdateLinks`) |
287
+
288
+ The seed is applied after the plugins are installed, and it refuses what would replace the kit's own files, so nothing is lost without a word: `.obsidian/app.json` (the kit fills it with its defaults; set keys with `config`), `.obsidian/community-plugins.json` (written from the `plugins` option), `.obsidian/plugins/<id>/data.json` of a plugin in the `data` option (change the settings there) and the build files `main.js`, `manifest.json`, `styles.css` of an installed plugin (they would replace the build under test). The `data.json` of a plugin without a `data` entry is the spec's to seed, per test, and so is any other file in an installed plugin's folder. Paths are compared after normalising `./`, backslashes and case. A wrong shape (an unknown key, a non-string file) fails the test before Obsidian starts, naming the key. The seed vault itself is never written: every test still gets its own copy. For content that depends on something only the running app knows, write it from the spec with `vault.write` and `reload()` as before.
289
+
290
+ ## Helpers
291
+
292
+ The `obsidian` fixture. Each helper that waits polls Obsidian's state; the only fixed delays are the 15 ms between key presses of `editor().type()` and, inside `scrollThrough`, a 100 ms fallback per step for a window that draws no frames. A failure says what went wrong and what to do. The selectors the helpers rely on (`.modal.mod-settings`, `.vertical-tab-content`, `.prompt-input`, `.prompt-results`, `.notice` and the editor's) are Obsidian internals, verified on 1.14.5; when a newer Obsidian renames one, the helper that uses it fails with its own message.
293
+
294
+ ### Settings
295
+
296
+ | Helper | What it does |
297
+ |---|---|
298
+ | `openSettings(tab?)` | Opens Settings in the main window and returns the content of the open tab. `tab` is a plugin id or a core tab id. A tab a plugin registers late is waited for; a missing one fails listing the registered ids. `const content = await obsidian.openSettings("my-plugin")` |
299
+ | `closeSettings()` | Closes the modal and waits until it is gone. `await obsidian.closeSettings()` |
300
+
301
+ `openSettings` returns the Locator of the settings content (`.modal.mod-settings .vertical-tab-content`), not of the page. Use it for lookups inside the tab (`content.getByText("Refresh")`). A filter on the whole page, such as `win.locator(".setting-item", { has: win.locator("input") })`, and a screenshot of the container (`win.locator(".modal.mod-settings").screenshot()`) go through `win`. Settings opens in the main window, so a settings screenshot has the size of the container in that window, not of a separate popout window as in a harness that opened Settings in a second window.
302
+
303
+ Settings opens in the main window because the kit sets `settingsPopoutWindow: false` (step 4). That is a default: a value in the seed vault's `.obsidian/app.json` wins. When Settings then opens in a second window, `openSettings` fails after `timeouts.helpers.ui` with a message that names the seed's `app.json` and the key.
304
+
305
+ ### Commands
306
+
307
+ | Helper | What it does |
308
+ |---|---|
309
+ | `runCommand(id)` | Runs `app.commands.executeCommandById`. An unknown id fails with the close matches. A command whose `checkCallback` declined (it needs a state that is not there, such as an open note) fails too: the check comes first, because Obsidian reports success for it. `await obsidian.runCommand("my-plugin:sync")` |
310
+ | `openCommandPalette()` | Presses `Mod+P` and returns the palette's input |
311
+ | `runCommandFromPalette(name)` | Fills the palette input with `name`, waits for the entry to be selected, presses Enter, and waits for the palette to close. The palette needs the `command-palette` core plugin in the seed vault. `await obsidian.runCommandFromPalette("Sync now")` |
312
+ | `press(keys)` | Presses a key or combination; `Mod` is Cmd on macOS and Ctrl elsewhere. `await obsidian.press("Mod+Shift+F")` |
313
+
314
+ ### Files and editor
315
+
316
+ | Helper | What it does |
317
+ |---|---|
318
+ | `openFile(path, { mode })` | Opens a note by vault path in the active tab. `mode` is `source`, `live` or `preview`, and is also forced on a note that is already open in the tab. `await obsidian.openFile("Notes/Today.md", { mode: "live" })` |
319
+ | `readingView(path?)` | Shows a note in reading view (the active note without `path`) |
320
+ | `collapseSidebars()` | Collapses the left and right side panels and waits until both report collapsed (they animate), so the note pane gets the whole window: a 390 px viewport is then 390 px of note. It is a helper of its own and not an option of `readingView()`, because it is about the window layout and serves source and live mode and screenshots as well. It then writes the workspace layout to disk, so a `reload()` right after it keeps the panels folded. Fails, naming the helper, when this Obsidian has no `workspace.leftSplit` and `rightSplit` to drive. `await obsidian.collapseSidebars()` |
321
+ | `expandSidebars()` | The inverse: expands both panels and waits until they are expanded |
322
+ | `editor().type(text)` | Types key by key, so per-keystroke listeners (a snippet expander) fire. It clicks the editor to focus it only when it is not focused: a second click would move the cursor |
323
+ | `editor().text()` | The whole document, read through `getValue()`, because CodeMirror keeps only the visible lines in the DOM |
324
+ | `editor().clear()` | Selects all, deletes, and waits until the document is empty |
325
+ | `editor().setCursor(line, ch)` | Both from 0; a position past the end is clamped |
326
+ | `editor().selection()` | `{ text, anchor, head }`, positions as `{ line, ch }` |
327
+
328
+ `openFile` does not collapse the side splits; call `collapseSidebars()` before it if your plugin needs the room. The editor is found without the `mod-active` class (Obsidian drops it from the leaf while a modal is open), so `type()` right after a closed modal works. `editor().text()` and `clear()` throw `There is no active editor` when no note is open in source or live mode.
329
+
330
+ `openFile`'s `mode` is the name of what you see. Obsidian's view state stores source and live preview as the same `mode: "source"`, told apart by a `source` flag, so a harness that set the state itself maps like this:
331
+
332
+ | Obsidian view state | `mode` |
333
+ |---|---|
334
+ | `{ mode: "source", source: false }` | `"live"` |
335
+ | `{ mode: "source", source: true }` | `"source"` |
336
+ | `{ mode: "preview" }` | `"preview"` |
337
+
338
+ ```ts
339
+ await obsidian.openFile("Welcome.md", { mode: "source" });
340
+ await obsidian.editor().clear();
341
+ await obsidian.editor().type("::date");
342
+ expect(await obsidian.editor().text()).toContain("2026");
343
+ ```
344
+
345
+ ### Layout checks
346
+
347
+ `checkLayout({ root, overflow?, touchTargets?, focusRing? })` looks at the part of the window under the CSS selector `root` (a modal, a view, a settings tab) and fails with the list of everything wrong, so one run shows all the problems and not the first. `layoutProblems(options)` runs the same checks and returns the list (empty when all is well), for `expect.soft` or a report. `root` is required and must match something (the first match is used), also when every check is off; it is looked up once, before the checks. A call with nothing to check (every check off) fails with "nothing to check", and a Tab walk with no stop inside `root` fails too: a check never passes by looking at nothing.
348
+
349
+ | Check | Option | Default | What it reports |
350
+ |---|---|---|---|
351
+ | Horizontal overflow | `overflow` | on | `root` and every element under it with `scrollWidth > clientWidth + 1`, scroll panes included: a pane with `overflow-y: auto` computes `overflow-x: auto` too, so its style cannot say whether it scrolls sideways on purpose. Left out: text cut with an ellipsis (`text-overflow: ellipsis`, or `white-space: nowrap` with `overflow: hidden`) and visually hidden boxes (1 px or less, clipped by `overflow`, `clip` or `clip-path`). `{ ignore }` is a selector for the rest, matched against the element and its ancestors (`overflow: { ignore: "pre, .table-wrapper" }` for a code block or a table that scrolls on purpose) |
352
+ | Touch targets | `touchTargets` | on in the mobile emulation (`mobile()`), off otherwise | Visible (has a box, so `position: fixed` targets count; not `visibility: hidden`) buttons, links, selects, inputs, textareas, summaries and elements with role `button`, `tab` or `menuitem` under `root` that are under 44 px wide or high (0.5 px less for rounding). `{ minSize, selector, ignore }` changes the size, what counts as a target, and what to leave out (matched against the element and its ancestors) |
353
+ | Focus ring | `focusRing` | off, because it presses Tab and moves focus | Focuses the first focusable element of `root` that is visible and not disabled (`{ from }` picks another; it must be inside `root` and take focus), presses Tab until focus leaves `root`, comes back to a stop it already visited (a focus trap) or `maxStops` (20, at most 100) presses are done, and reports each stop that shows no ring. A ring is an outline or a box-shadow that focus changes, on the element or its `::before`/`::after` (Obsidian rings a `.setting-item` on `::after`): the outline must be visible (not `none`, width above 0) and differ, the box-shadow must differ between the focused and the unfocused state, because Obsidian gives buttons and selects a resting `box-shadow`; the element is blurred and focused again for the second read, with transitions off, and the check fails with a clear error if it did not take focus back (a control that replaces itself on blur: skip it with `focusRing: { ignore }`). Range and colour inputs ring a vendor pseudo-element (`::-webkit-slider-thumb`, `::-webkit-color-swatch`) that `getComputedStyle` cannot read, so for these the check compares screenshots of the control focused and blurred. A modifier key (Shift) is pressed before the walk so Chromium matches `:focus-visible` on the script focus even after a mouse click. `{ ignore: ".prompt-input" }` skips elements inside the selector: Obsidian's command palette and quick switcher search field shows the caret and no ring by design, so the palette passes only with it. Keep the pointer off colour inputs during the walk: their hover style can read as a ring. After `mobile()` Obsidian draws no focus ring on range inputs, so add `ignore: "input[type=range]"` there. `{ stayInside: true }` also reports the Tab that moves focus out of `root` (a modal that must trap focus); without it, leaving ends the walk |
354
+
355
+ ```ts
356
+ await obsidian.mobile();
357
+ await obsidian.runCommand("my-plugin:open-wizard");
358
+ await obsidian.settle({ root: ".my-plugin-wizard" });
359
+ await obsidian.checkLayout({ root: ".my-plugin-wizard", focusRing: { from: ".my-plugin-key" } });
360
+ ```
361
+
362
+ ```text
363
+ checkLayout(): 3 problems inside ".my-plugin-wizard":
364
+ - horizontal overflow: div.my-plugin-wizard (scrollWidth 420 > clientWidth 390)
365
+ - touch target too small: button.my-plugin-close (30 x 28 px)
366
+ - no focus ring: input.my-plugin-key (focus changes neither the outline (none 0px rgb(0, 0, 0)) nor the box-shadow (none), on the element or its ::before, ::after)
367
+ Touch targets must be at least 44 px; raise the size in CSS for the mobile layout, or pass touchTargets: { ignore } for an element that is not a target.
368
+ A focus ring is an outline or a box-shadow that focus changes, on the element or its ::before/::after (a resting box-shadow does not count); a theme that sets outline: none needs a replacement.
369
+ ```
370
+
371
+ Each kind of problem lists at most 10 elements; a longer list ends with `(first 10 of N)`. Identical Tab stops are listed once. The checks read the page as it is: open the part you check and `settle()` it first. They measure; they do not judge a design. A person should still look at the pictures of a tour: take them with `demo.still(name, { publish: false })`, with a name prefix such as `review-` so they are easy to tell from the published ones (they stay in `.opdk/demo/stills` and are not published by `opdk demo`, see [docs/demo.md](demo.md)). The kit has no review-shot helper or contact sheet of its own; `/opdk:audit` makes a contact sheet of GIFs.
372
+
373
+ ### IME
374
+
375
+ `editor().compose(text, { chunking })` enters text through real composition events (`Input.imeSetComposition`, then `Input.insertText`, over a CDP session), the way an input method does. `chunking` is `"word"` (default: each word composed and committed with its trailing space) or `"character"`. It inserts at the cursor, waits for CodeMirror to leave the composition between chunks, and fails when CodeMirror is still composing after a commit or the document did not change.
376
+
377
+ ```ts
378
+ await obsidian.editor().compose("hello world", { chunking: "word" });
379
+ ```
380
+
381
+ `compose` always commits. A test that must leave a composition uncommitted (a preedit that a plugin has to survive) needs a raw CDP session of its own: `win.context().newCDPSession(win)`.
382
+
383
+ ### Appearance and state
384
+
385
+ | Helper | What it does |
386
+ |---|---|
387
+ | `setTheme({ mode, theme? })` | Switches light or dark and, with `theme`, a community theme (`""` for the default); waits until the page carries the class. An uninstalled theme fails listing the installed ones. `await obsidian.setTheme({ mode: "dark" })` |
388
+ | `waitForMetadataCache()` | Waits until every markdown file has its metadata cached. Returns at once for a vault with no markdown files |
389
+ | `clearNotices()` | Removes the notices on screen and returns how many there were. `const removed = await obsidian.clearNotices()` |
390
+ | `hideProperties()` | Hides the properties block of notes (a display setting; the notes are unchanged). Saved to `.obsidian/app.json` at once, so a later settings save does not bring the block back. Throws on an Obsidian without `vault.setConfig` / `vault.saveConfig` (the setting would not stick) |
391
+ | `scrollThrough(selector?)` | Scrolls a reading view from top to bottom so blocks that draw when visible are drawn. `await obsidian.scrollThrough()` |
392
+ | `settle({ quietMs?, root? })` | Waits until the page stops changing: no DOM mutation for `quietMs` (150 ms), no font loading, every image in the viewport complete. `await obsidian.settle()` |
393
+
394
+ `scrollThrough` stays at the bottom and does not scroll back: the reading view drops the sections that leave the viewport, and scrolling back would drop the blocks it just drew. Without a selector it takes the active reading view; a selector that matches nothing fails.
395
+
396
+ `settle()` is the wait to use where a spec would sleep before a screenshot. It watches the DOM with a `MutationObserver` on the `<body>` (or on `root`, a CSS selector) and resolves when nothing was added, removed or changed there for `quietMs` and no web font is loading and every `<img>` in the viewport has finished loading (a broken image counts as finished). The default of 150 ms is above the 100 ms debounce that views and plugins commonly use for a refresh, and still costs a fraction of a second on a page that is already still. CSS animations and transitions are not DOM changes, so an endless spinner or a blinking caret does not hold it up. It waits `timeouts.helpers.ui` at most; on timeout it throws an error that names `settle()`, the budget, what was still changing (the DOM, a font or a number of images) and how to raise it. It sees changes that are happening, not ones that are only scheduled: a gap between two changes longer than `quietMs` (a request that takes 400 ms between the click and the render) looks like a still page, so raise `quietMs` for such a view, or assert on the element it renders. Content that a script keeps rewriting (a clock, a live counter) inside the watched part never settles: pass a `root` that leaves it out. Drawing on a `<canvas>` (a chart) is not a DOM change either: `settle()` can return while the chart is still animating or has not been drawn, so a screenshot of a canvas needs its own wait, for example polling a pixel (`getImageData`) until it is not blank, or the ready flag or `animation.onComplete` callback of the chart library. A `quietMs` that is not below the budget is refused up front. The demo helpers call it for you when a shot or a still passes `settle: true` ([docs/demo.md](demo.md)).
397
+
398
+ ### Mobile
399
+
400
+ `mobile({ width, height, scale })` switches Obsidian to its mobile interface in a phone-sized viewport (390 x 844 at scale 2 unless given): CDP `Emulation.setDeviceMetricsOverride` plus `app.emulateMobile(true)`. That call reloads the window, and the only rejection the helper accepts is the one the reload causes; it then waits until every plugin has loaded again and keeps the viewport phone-sized. `desktop()` undoes it.
401
+
402
+ ```ts
403
+ await obsidian.mobile();
404
+ await obsidian.runCommand("my-plugin:open-view");
405
+ await obsidian.mobile({ width: 820, height: 1180 }); // a tablet: the window loads again
406
+ await obsidian.desktop();
407
+ ```
408
+
409
+ Screenshots: `mobile({ scale })` sets the device scale of the page, but `win.screenshot()` still uses the pixel ratio of the display the Obsidian window opened on, so the same test gives a 1x picture on one machine and a 2x one on a Retina display. Take `win.screenshot({ scale: "css" })` for a picture that is always one pixel per CSS pixel (390 pixels wide on the default phone).
410
+
411
+ A harness that made stills larger with `webFrame.setZoomFactor` gets different pictures here. The zoom changed the CSS size of the page, so a layout was drawn at a smaller width and every pixel measure scaled with it. The kit's stills are the page at its real CSS size, and their pixel size follows the display: on a Retina display `win.screenshot()` is 2x. For a picture of a fixed CSS size, set the viewport with `mobile({ width, height, scale })` and cut it with a `clip` in CSS pixels; `scale: "css"` gives 1 pixel per CSS pixel on any display:
412
+
413
+ ```ts
414
+ await obsidian.mobile({ width: 450, height: 844, scale: 2 });
415
+ await win.screenshot({ path: "listing.png", clip: { x: 0, y: 0, width: 450, height: 800 } }); // 900 x 1600 on a 2x display
416
+ await win.screenshot({ path: "listing-1x.png", clip: { x: 0, y: 0, width: 450, height: 800 }, scale: "css" }); // 450 x 800 anywhere
417
+ ```
418
+
419
+ Verified on a 2x display with Obsidian 1.14.5: the first call gave 900 x 1600 and the second 450 x 800. `scale` in `mobile()` was 2 there; `mobile({ scale: 3 })` gave the same 900 x 1600, so the size of `win.screenshot()` is the display's ratio and not the `scale` option. If you need N-times pixels on a display that is not N times, the picture has to be scaled after it is taken.
420
+
421
+ A second `mobile()` with another width reloads the window, because the phone or tablet layout is decided from the viewport at load; the same width does not. Plugins with `isDesktopOnly: true` do not load on mobile, so the wait fails naming them.
422
+
423
+ ### Reload
424
+
425
+ `reload()` runs Obsidian's own "Reload app without saving" command (`app:reload`) and returns once the new page is up and every enabled plugin has loaded again. It marks the old page, waits until it is gone, then waits for the plugins, the same way `mobile()` does after its reload, so the next line can use the editor without racing the load. `app:reload` reloads without saving, so text typed right before `reload()` can be lost to Obsidian's save debounce: wait for the file to be written first (for example poll `vault.read` until it holds the text). The page call that starts the reload never returns; that rejection is the only one accepted. Anything installed in the old page is gone afterwards, `replace()` fakes included. It fails naming the command when the Obsidian has no `app:reload`, with its own message when Obsidian refuses to run it, and with `timeouts.ready` as the budget when the window does not come back.
426
+
427
+ ```ts
428
+ await obsidian.reload();
429
+ await obsidian.openFile("Notes/a.md");
430
+ ```
431
+
432
+ ### Page code
433
+
434
+ `evaluate(fn, arg?)` runs `fn(app, arg)` in the page, where `app` is Obsidian's `window.app`, and returns the result (a promise is awaited). A function that declares the `arg` parameter must be given one, as with `page.evaluate`. Type `app` with Obsidian's own `App` through a type-only import; the kit does not depend on the `obsidian` package, so the type comes from yours:
435
+
436
+ ```ts
437
+ import type { App } from "obsidian";
438
+
439
+ const count = await obsidian.evaluate(
440
+ (app: App, folder: string) => app.vault.getMarkdownFiles().filter((file) => file.path.startsWith(folder)).length,
441
+ "Notes/",
442
+ );
443
+ ```
444
+
445
+ The generics are `evaluate<R, A = undefined, App = unknown>`: `R` is the result, `A` the argument, `App` the type of `app`, all inferred from the function you pass. `fn` is serialised as source text and rebuilt in the page, so it cannot close over variables of the test or use imports (a variable it reads fails with `<name> is not defined`); pass what it needs as `arg`. `arg` and the result must be serialisable, as for `page.evaluate`: a `TFile` or a DOM node does not survive, return the fields you need. An exception thrown by `fn` fails the test with its message. `evaluate` fails with its own message when `window.app` is missing or `fn` is not a function expression (a method shorthand is not).
446
+
447
+ ### Obsidian internals
448
+
449
+ Obsidian's public typings leave out the internal objects that specs reach: `app.plugins.plugins`, `enablePlugin` and `disablePlugin`, `app.setting`, `app.commands`, `app.internalPlugins`, `metadataCache.inProgressTaskCount`, `vault.getConfig`. `AppWithInternals` (exported from `obsidian-plugin-dev-kit/e2e`) types them narrowly, so a spec does not declare its own copy:
450
+
451
+ ```ts
452
+ import type { AppWithInternals } from "obsidian-plugin-dev-kit/e2e";
453
+
454
+ await obsidian.evaluate(async (app: AppWithInternals) => {
455
+ await app.plugins.disablePlugin("my-plugin");
456
+ await app.plugins.enablePlugin("my-plugin");
457
+ });
458
+
459
+ // Read and return fields: the result has to be serialisable.
460
+ const tabs = await obsidian.evaluate((app: AppWithInternals) => app.setting.pluginTabs.map((tab) => tab.id));
461
+ ```
462
+
463
+ A plugin instance is `PluginInstance`: its `manifest` is typed and every other member is `unknown`. To read what your plugin adds, give the type as the parameter: `AppWithInternals<PluginInstance & { settings?: MySettings }>`. A member that only some Obsidian versions have is optional (`setting.activeTab`, `metadataCache.inProgressTaskCount`). The types describe Obsidian 1.14.5; a renamed member shows up as a failed spec, not a compile error, because the types cannot see the running version. The kit's own page scripts use the same types, so they and your specs agree.
464
+
465
+ ### Fakes
466
+
467
+ `replace(pluginId, propertyPath, impl, arg?)` assigns a function at `app.plugins.plugins[id].<path>` on the live plugin instance and returns `{ calls(), restore() }`. `impl` is a factory: it runs once in the page with `arg` and returns the replacement, so it can keep state between calls. A factory that declares a parameter must be given the `arg`.
468
+
469
+ ```ts
470
+ const fake = await obsidian.replace(
471
+ "my-plugin",
472
+ "client.fetch",
473
+ (delayMs: number) => async (path: string) => {
474
+ await new Promise((resolve) => setTimeout(resolve, delayMs));
475
+ return { path, items: [] };
476
+ },
477
+ 250,
478
+ );
479
+ await obsidian.runCommand("my-plugin:sync");
480
+ expect(await fake.calls()).toEqual([["/items"]]);
481
+ await fake.restore();
482
+ ```
483
+
484
+ The factory is serialised as source text and rebuilt in the page, so it cannot close over variables of the test 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`, which must be serialisable, as for `page.evaluate`. Failure modes and delays belong in the function the factory returns. `replace` refuses a plugin that is not loaded, a property that does not exist, and a factory that throws or does not return a function. `calls()` records the arguments of each call, oldest first, and still works after `restore()`. After the window was reloaded (`mobile()`, `desktop()`) the page has forgotten the replacement: `calls()` and `restore()` fail with a clear message, unless `restore()` ran before the reload, in which case `calls()` returns the record it kept.
485
+
486
+ ## Failure artifacts
487
+
488
+ Playwright's `use.trace` and `use.video` apply to browser contexts its own fixtures create; the window of an `_electron` launch is outside them. The kit reads the same settings from your config and records the Obsidian window itself, in every mode Playwright has (`off`, `on`, `retain-on-failure`, `on-first-retry`, `on-all-retries`, `retain-on-first-failure`, `retain-on-failure-and-retries`, and the object forms `{ mode, ... }`). A value it does not know fails naming the setting.
489
+
490
+ With the preset (`retain-on-failure`), a red test leaves in `test-results/<test folder>/`:
491
+
492
+ - `obsidian-trace.zip`, attached to the report as `trace`: the Obsidian window's screencast, actions and snapshots, recorded from right after the launch. Open it with `npx playwright show-trace test-results/<test folder>/obsidian-trace.zip`.
493
+ - A `.webm` video of the window in `test-results/<test folder>/video/`, attached as `video`. Pass a size with `use: { video: { mode: "on", size: { width: 1024, height: 640 } } }`.
494
+ - Playwright's own `trace.zip` and `test-failed-1.png`. The own trace holds the runner's steps and attachments and no screencast of the Obsidian window; use `obsidian-trace.zip`.
495
+
496
+ A recording that the mode does not keep is deleted. CDP mode, when it comes, will have a trace but no video: Playwright cannot record a page it only attached to.
497
+
498
+ ## Specs that run only on request
499
+
500
+ A spec that should run only when asked (a capture run, a film, a long matrix) calls `onlyWhen` at the top of the file. The file is skipped unless that environment variable is exactly `1`, and a skipped file never starts Obsidian:
501
+
502
+ ```ts
503
+ import { expect, onlyWhen, test } from "./fixtures.js";
504
+
505
+ onlyWhen("CAPTURE");
506
+
507
+ test("capture the dashboard", async ({ obsidian }) => {
508
+ await obsidian.openFile("Dashboard.md", { mode: "preview" });
509
+ await obsidian.scrollThrough();
510
+ });
511
+ ```
512
+
513
+ ```bash
514
+ CAPTURE=1 npx playwright test capture
515
+ ```
516
+
517
+ This replaces `--grep-invert` in a script: the default run needs no flag to leave the spec out.
518
+
519
+ ## Migrating from a plugin's own harness
520
+
521
+ 1. Install `@playwright/test` and `electron` as devDependencies, and the kit. On a fresh checkout run `node node_modules/electron/install.js` once, so the binary is downloaded before the first test.
522
+ 2. Replace the plugin's `e2e/fixtures.ts` with `createObsidianTest({ seedVault, plugins, data, window })`. Delete the code it replaces: the vault copy, `obsidian.json`, plugin installation (a setup shell script too), `data.json` seeding, the Electron launch, the dialog handlers, the version reader, the folder removal.
523
+ 3. Replace `playwright.config.ts` with `defineObsidianConfig()` and keep only what is yours (`globalSetup`, a different `testDir`).
524
+ 4. Move the shared helpers to the `obsidian` fixture (see the table below) and keep only the plugin's own (page objects for its own views, for example).
525
+ 5. Replace `--grep-invert` scripts and `test.skip` env checks with `onlyWhen`.
526
+ 6. Search the plugin for callers of the old setup script (a capture script, `e2e-setup.sh`, a `pretest` or `e2e` entry in `package.json`, CI steps, docs) and replace each with the build command, `opdk build`. `grep -rn "e2e-setup\|capture.mjs" --exclude-dir=node_modules .` finds them with your script names.
527
+ 7. Run the specs and read each difference below against your own.
528
+
529
+ What changes:
530
+
531
+ - `onlyWhen("X")` runs the file only when `X` is exactly `1`. An old `test.skip(!process.env.X)` gate accepted any non-empty value, so `X=true` or `X=yes` now skips the file; change the command that sets it.
532
+ - The seed vault is copied as it is, then the plugins are installed over it. A plugin folder in the seed (`<seed>/.obsidian/plugins/<id>`, committed or generated by an old setup script) is overwritten by the kit's install of `main.js`, `manifest.json` and `styles.css` (other files there, such as a seeded `data.json`, stay unless the `data` option replaces them). Delete the committed copy, and drop the `.gitignore` line that hid a generated one. The seed's `community-plugins.json` is optional: the kit writes the ids it lists plus the installed plugins.
533
+ - No fixed sleeps. Waits after enabling plugins, a wait for the trust dialog and fixed waits of 1500 ms are gone: the fixture waits for plugin state. The fixture waits for every plugin's `onload()` to finish, not for the plugin's first render. A spec that slept to let a view, a block or a reading-view render appear now needs a wait of its own for what it asserts (an assertion on the element, or `settle()` when the page just has to stop changing before a picture): `expect(locator).toBeVisible()` (a locator waits by itself), `expect.poll(...)` for a value read from the page, or `waitForFunction`. A spec like that fails on its own assertion or locator timeout, not with `plugin still loading`, which is reported only when an `onload()` is still running at `timeouts.ready`.
534
+ - No Escape, no `setEnable`. The trust flag is set before the vault loads; if the dialog opens anyway the test fails and says so.
535
+ - Cleanup retries and then fails with the folder path. A leftover that an old harness swallowed is now a failing test.
536
+ - A fallback that read the Obsidian version from the `obsidian.asar` on disk, and a `require("obsidian")` fallback (it never worked), are not carried over. The version is read with `ipcRenderer.sendSync("version")`, and an unreadable version fails the test when a version is pinned.
537
+ - `editor().text()` and `clear()` throw `There is no active editor` where a hand-written `editorText` helper returned an empty string and a `clearEditor` helper clicked a missing editor.
538
+ - `openFile` does not collapse the side splits, which a hand-written `openInReading` helper did. Call `collapseSidebars()` first.
539
+ - `compose()` fails when CodeMirror is still composing after a commit and when the document did not change; it always commits, so a spec that tests an uncommitted preedit keeps a raw CDP session.
540
+ - A plugin-specific vault variable becomes `OPDK_E2E_VAULT`. A video option read nowhere else goes; video now follows `use.video`.
541
+ - A harness mode that launches Obsidian over CDP (`E2E_LAUNCH=cdp`) has no replacement yet.
542
+
543
+ Where a shared helper goes:
544
+
545
+ | A helper you may have written | In the kit |
546
+ |---|---|
547
+ | Open settings, a settings spec | `obsidian.openSettings(tab)`, `closeSettings()` |
548
+ | Open the command palette, run a command | `openCommandPalette()`, `runCommandFromPalette(name)`, `runCommand(id)` |
549
+ | Type in the editor, read its text, clear it | `editor().type()`, `text()`, `clear()` |
550
+ | An IME composition spec | `editor().compose()` |
551
+ | Change the theme, wait for the index, remove notices, scroll so lazy blocks draw | `setTheme()`, `waitForMetadataCache()`, `clearNotices()`, `hideProperties()`, `scrollThrough()` |
552
+ | An `emulateMobile` block copied into several specs | `mobile()`, `desktop()` |
553
+ | A fake for a network client | `replace()` |
554
+ | Collapse the sidebars, collapse the splits before opening in reading view | `collapseSidebars()`, `expandSidebars()` |
555
+ | A fixed `waitForTimeout` before a screenshot | `settle()` |
556
+
557
+ ## Limits today
558
+
559
+ - Electron launch mode only. CDP mode (the real Obsidian binary over `--remote-debugging-port`, which also allows pinned versions later) is not built yet, and `app` exists only in Electron mode.
560
+ - Verified on macOS with Obsidian 1.14.5. Linux CI (a virtual display, `--no-sandbox`) is a later item, and Windows is untested. The code has Windows branches (`taskkill`); nobody has run them.
561
+ - The kit checks the installed Obsidian's version; it does not download one.
562
+ - The Obsidian window opens on your screen during a run. The kit does not hide it.
563
+ - The e2e specs of the kit itself (`npm run e2e:smoke`) run by hand before a release, never in `npm test` or CI.