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
@@ -0,0 +1,90 @@
1
+ /**
2
+ * Trace and video for the Obsidian window. Playwright's `use.trace` and `use.video` only apply to the browser
3
+ * contexts its own fixtures create; the window of an `_electron` launch is outside them, so the kit reads the same
4
+ * settings and does what Playwright does for a browser: decide per attempt whether to record, and whether to keep.
5
+ */
6
+ const MODES = [
7
+ "off",
8
+ "on",
9
+ "retain-on-failure",
10
+ "on-first-retry",
11
+ "on-all-retries",
12
+ "retain-on-first-failure",
13
+ "retain-on-failure-and-retries",
14
+ ];
15
+ /** Does this attempt record? `retry` is 0 for the first run, 1 for the first retry. */
16
+ export function shouldRecord(mode, retry) {
17
+ switch (mode) {
18
+ case "off":
19
+ return false;
20
+ case "on":
21
+ case "retain-on-failure":
22
+ case "retain-on-failure-and-retries":
23
+ return true;
24
+ case "retain-on-first-failure":
25
+ return retry === 0;
26
+ case "on-first-retry":
27
+ return retry === 1;
28
+ case "on-all-retries":
29
+ return retry > 0;
30
+ }
31
+ }
32
+ /** Is a recording of this attempt kept? Only meaningful when `shouldRecord` is true; otherwise nothing exists to keep. */
33
+ export function shouldKeep(mode, failed, retry) {
34
+ if (!shouldRecord(mode, retry)) {
35
+ return false;
36
+ }
37
+ switch (mode) {
38
+ case "retain-on-failure":
39
+ case "retain-on-first-failure":
40
+ return failed;
41
+ case "retain-on-failure-and-retries":
42
+ return failed || retry > 0;
43
+ default:
44
+ return true;
45
+ }
46
+ }
47
+ /** Playwright's deprecated aliases of `on-first-retry`: each one is valid for its own option only. */
48
+ const DEPRECATED_ALIASES = {
49
+ "use.trace": "retry-with-trace",
50
+ "use.trace.mode": "retry-with-trace",
51
+ "use.video": "retry-with-video",
52
+ "use.video.mode": "retry-with-video",
53
+ };
54
+ function parseMode(value, option) {
55
+ if (value !== undefined && value === DEPRECATED_ALIASES[option]) {
56
+ return "on-first-retry";
57
+ }
58
+ const mode = MODES.find((candidate) => candidate === value);
59
+ if (mode === undefined) {
60
+ throw new Error(`Unsupported ${option} value ${JSON.stringify(value)} in the Playwright config. Use one of: ${MODES.join(", ")}.`);
61
+ }
62
+ return mode;
63
+ }
64
+ function isRecord(value) {
65
+ return typeof value === "object" && value !== null;
66
+ }
67
+ /** Reads `use.trace`: a mode string or `{ mode, screenshots, snapshots, sources }`. Unset means `off`. */
68
+ export function parseTraceSetting(value) {
69
+ const mode = isRecord(value) ? parseMode(value.mode, "use.trace.mode") : parseMode(value ?? "off", "use.trace");
70
+ const flags = isRecord(value) ? value : {};
71
+ // `snapshots` can also be an object of per-kind switches in newer Playwright; any object means "on".
72
+ return {
73
+ mode,
74
+ screenshots: flags.screenshots !== false,
75
+ snapshots: flags.snapshots !== false,
76
+ sources: flags.sources !== false,
77
+ };
78
+ }
79
+ /** Reads `use.video`: a mode string or `{ mode, size }`. Unset means `off`. */
80
+ export function parseVideoSetting(value) {
81
+ if (!isRecord(value)) {
82
+ return { mode: parseMode(value ?? "off", "use.video") };
83
+ }
84
+ const mode = parseMode(value.mode, "use.video.mode");
85
+ const { size } = value;
86
+ if (isRecord(size) && typeof size.width === "number" && typeof size.height === "number") {
87
+ return { mode, size: { width: size.width, height: size.height } };
88
+ }
89
+ return { mode };
90
+ }
@@ -0,0 +1,54 @@
1
+ import fs from "node:fs";
2
+ /** Every temp folder the harness creates starts with this, so a sweep and the kit's own tests can find leftovers. */
3
+ export declare const TEMP_PREFIX = "opdk-e2e-";
4
+ /**
5
+ * Undo steps for a test session, run in reverse order. Every step runs even when an earlier one fails; the failures
6
+ * are reported together, with each step's name, so a leftover folder is named in the error and never swallowed.
7
+ */
8
+ export declare class CleanupStack {
9
+ private readonly steps;
10
+ add(name: string, undo: () => void | Promise<void>): void;
11
+ /** Runs the steps once, newest first. Throws one error listing every step that failed. */
12
+ run(): Promise<void>;
13
+ }
14
+ export interface RemoveDirOptions {
15
+ /** Injectable so a test can force the failure. */
16
+ readonly rm?: typeof fs.rmSync;
17
+ }
18
+ /**
19
+ * Removes a temp folder, retrying, and throws when it is still there. Chromium helper processes can keep writing
20
+ * into the folder for a moment after the main process exits, which makes a plain `rmSync` fail with ENOTEMPTY; node
21
+ * retries ENOTEMPTY/EBUSY/EPERM with `maxRetries`/`retryDelay`. A folder that survives the retries fails the test
22
+ * with its path: silently leaking temp folders is how a disk fills up over a week of e2e runs.
23
+ */
24
+ export declare function removeDir(dir: string, options?: RemoveDirOptions): void;
25
+ /** Creates a temp folder named `opdk-e2e-<kind>-<label>-XXXXXX`. `label` is cut to 40 characters of `[a-z0-9-]`. */
26
+ export declare function createTempDir(kind: string, label: string, root?: string): string;
27
+ export interface SweepOptions {
28
+ /** Default `os.tmpdir()`. */
29
+ readonly root?: string;
30
+ readonly olderThanHours: number;
31
+ /** Default `Date.now()`. */
32
+ readonly now?: number;
33
+ readonly rm?: typeof fs.rmSync;
34
+ }
35
+ export interface SweepResult {
36
+ readonly removed: readonly string[];
37
+ readonly failed: readonly {
38
+ readonly dir: string;
39
+ readonly error: string;
40
+ }[];
41
+ }
42
+ /**
43
+ * Removes `opdk-e2e-*` folders older than `olderThanHours` from `root`: what a crashed or killed run left behind.
44
+ * Only real directories with the kit prefix are touched (symlinks are skipped). A folder that cannot be removed is
45
+ * reported in `failed` instead of thrown: it belongs to an earlier run, not to the test that triggered the sweep.
46
+ */
47
+ export declare function sweepLeftovers(options: SweepOptions): SweepResult;
48
+ /** Names of the kit's temp folders in `root`. The kit's own tests use it to assert that nothing is left. */
49
+ export declare function listTempDirs(root?: string): string[];
50
+ /**
51
+ * What a worker does before its first test: sweep old folders and say so. A folder that cannot be removed is a
52
+ * warning (it belongs to an earlier run), not a failure of this one.
53
+ */
54
+ export declare function sweepAtWorkerStart(olderThanHours: number | false, warn: (message: string) => void, root?: string): void;
@@ -0,0 +1,109 @@
1
+ import fs from "node:fs";
2
+ import os from "node:os";
3
+ import path from "node:path";
4
+ /** Every temp folder the harness creates starts with this, so a sweep and the kit's own tests can find leftovers. */
5
+ export const TEMP_PREFIX = "opdk-e2e-";
6
+ /**
7
+ * Undo steps for a test session, run in reverse order. Every step runs even when an earlier one fails; the failures
8
+ * are reported together, with each step's name, so a leftover folder is named in the error and never swallowed.
9
+ */
10
+ export class CleanupStack {
11
+ steps = [];
12
+ add(name, undo) {
13
+ this.steps.push({ name, undo });
14
+ }
15
+ /** Runs the steps once, newest first. Throws one error listing every step that failed. */
16
+ async run() {
17
+ const failures = [];
18
+ for (const step of this.steps.splice(0).reverse()) {
19
+ try {
20
+ await step.undo();
21
+ }
22
+ catch (error) {
23
+ failures.push({ name: step.name, error });
24
+ }
25
+ }
26
+ if (failures.length > 0) {
27
+ const lines = failures.map(({ name, error }) => `- ${name}: ${error instanceof Error ? error.message : String(error)}`);
28
+ throw new AggregateError(failures.map((failure) => failure.error), `Cleanup of the Obsidian e2e session failed:\n${lines.join("\n")}`);
29
+ }
30
+ }
31
+ }
32
+ /**
33
+ * Removes a temp folder, retrying, and throws when it is still there. Chromium helper processes can keep writing
34
+ * into the folder for a moment after the main process exits, which makes a plain `rmSync` fail with ENOTEMPTY; node
35
+ * retries ENOTEMPTY/EBUSY/EPERM with `maxRetries`/`retryDelay`. A folder that survives the retries fails the test
36
+ * with its path: silently leaking temp folders is how a disk fills up over a week of e2e runs.
37
+ */
38
+ export function removeDir(dir, options = {}) {
39
+ const rm = options.rm ?? fs.rmSync;
40
+ try {
41
+ rm(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
42
+ }
43
+ catch (error) {
44
+ throw new Error(`Could not remove ${dir} after retries: ${error instanceof Error ? error.message : String(error)}. ` +
45
+ `Make sure no Obsidian process still uses it, then delete the folder by hand.`, { cause: error });
46
+ }
47
+ }
48
+ /** Creates a temp folder named `opdk-e2e-<kind>-<label>-XXXXXX`. `label` is cut to 40 characters of `[a-z0-9-]`. */
49
+ export function createTempDir(kind, label, root = os.tmpdir()) {
50
+ const safe = label
51
+ .toLowerCase()
52
+ .replace(/[^a-z0-9]+/g, "-")
53
+ .replace(/^-+|-+$/g, "")
54
+ .slice(0, 40);
55
+ return fs.mkdtempSync(path.join(root, `${TEMP_PREFIX}${kind}-${safe === "" ? "" : `${safe}-`}`));
56
+ }
57
+ /**
58
+ * Removes `opdk-e2e-*` folders older than `olderThanHours` from `root`: what a crashed or killed run left behind.
59
+ * Only real directories with the kit prefix are touched (symlinks are skipped). A folder that cannot be removed is
60
+ * reported in `failed` instead of thrown: it belongs to an earlier run, not to the test that triggered the sweep.
61
+ */
62
+ export function sweepLeftovers(options) {
63
+ const root = options.root ?? os.tmpdir();
64
+ const now = options.now ?? Date.now();
65
+ const cutoff = now - options.olderThanHours * 3_600_000;
66
+ const removed = [];
67
+ const failed = [];
68
+ for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
69
+ if (!entry.isDirectory() || !entry.name.startsWith(TEMP_PREFIX)) {
70
+ continue;
71
+ }
72
+ const dir = path.join(root, entry.name);
73
+ try {
74
+ if (fs.statSync(dir).mtimeMs >= cutoff) {
75
+ continue;
76
+ }
77
+ removeDir(dir, options.rm === undefined ? {} : { rm: options.rm });
78
+ removed.push(dir);
79
+ }
80
+ catch (error) {
81
+ failed.push({ dir, error: error instanceof Error ? error.message : String(error) });
82
+ }
83
+ }
84
+ return { removed, failed };
85
+ }
86
+ /** Names of the kit's temp folders in `root`. The kit's own tests use it to assert that nothing is left. */
87
+ export function listTempDirs(root = os.tmpdir()) {
88
+ return fs
89
+ .readdirSync(root, { withFileTypes: true })
90
+ .filter((entry) => entry.isDirectory() && entry.name.startsWith(TEMP_PREFIX))
91
+ .map((entry) => entry.name)
92
+ .sort();
93
+ }
94
+ /**
95
+ * What a worker does before its first test: sweep old folders and say so. A folder that cannot be removed is a
96
+ * warning (it belongs to an earlier run), not a failure of this one.
97
+ */
98
+ export function sweepAtWorkerStart(olderThanHours, warn, root = os.tmpdir()) {
99
+ if (olderThanHours === false) {
100
+ return;
101
+ }
102
+ const { removed, failed } = sweepLeftovers({ root, olderThanHours });
103
+ if (removed.length > 0) {
104
+ warn(`[e2e] removed ${String(removed.length)} leftover folder(s) from earlier runs.`);
105
+ }
106
+ for (const { dir, error } of failed) {
107
+ warn(`[e2e] could not remove leftover ${dir}: ${error}`);
108
+ }
109
+ }
@@ -0,0 +1,9 @@
1
+ import { type PlaywrightTestConfig } from "@playwright/test";
2
+ /**
3
+ * The Playwright settings every Obsidian plugin's e2e shares. Obsidian opens one window per process and the specs
4
+ * share nothing, so they run one at a time; a cold start can take 15 to 20 seconds on a busy machine, hence the
5
+ * long test timeout.
6
+ */
7
+ export declare function buildObsidianConfig(overrides?: PlaywrightTestConfig, env?: Readonly<Record<string, string | undefined>>): PlaywrightTestConfig;
8
+ /** `playwright.config.ts` for a plugin: `export default defineObsidianConfig()`. Pass overrides for anything plugin-specific. */
9
+ export declare function defineObsidianConfig(overrides?: PlaywrightTestConfig): PlaywrightTestConfig;
@@ -0,0 +1,42 @@
1
+ import path from "node:path";
2
+ import { fileURLToPath } from "node:url";
3
+ import { defineConfig } from "@playwright/test";
4
+ /**
5
+ * The kit's global setup next to this file, with this file's own extension: `.js` from the installed `dist/`, `.ts`
6
+ * when the kit's own smoke config loads the sources.
7
+ */
8
+ const GLOBAL_SETUP = fileURLToPath(new URL(`./global-setup${path.extname(fileURLToPath(import.meta.url))}`, import.meta.url));
9
+ function toList(value) {
10
+ return value === undefined ? [] : Array.isArray(value) ? value : [value];
11
+ }
12
+ /**
13
+ * The Playwright settings every Obsidian plugin's e2e shares. Obsidian opens one window per process and the specs
14
+ * share nothing, so they run one at a time; a cold start can take 15 to 20 seconds on a busy machine, hence the
15
+ * long test timeout.
16
+ */
17
+ export function buildObsidianConfig(overrides = {}, env = process.env) {
18
+ const ci = env.CI !== undefined && env.CI !== "" && env.CI !== "0" && env.CI !== "false";
19
+ return {
20
+ testDir: "e2e",
21
+ fullyParallel: false,
22
+ workers: 1,
23
+ forbidOnly: ci,
24
+ retries: ci ? 1 : 0,
25
+ reporter: ci ? "list" : [["list"], ["html", { open: "never" }]],
26
+ timeout: 60_000,
27
+ ...overrides,
28
+ // The kit's check runs first; a `globalSetup` of the plugin runs after it, so a missing Electron is the only error.
29
+ globalSetup: [GLOBAL_SETUP, ...toList(overrides.globalSetup)],
30
+ expect: { timeout: 10_000, ...overrides.expect },
31
+ use: {
32
+ trace: "retain-on-failure",
33
+ video: "retain-on-failure",
34
+ screenshot: "only-on-failure",
35
+ ...overrides.use,
36
+ },
37
+ };
38
+ }
39
+ /** `playwright.config.ts` for a plugin: `export default defineObsidianConfig()`. Pass overrides for anything plugin-specific. */
40
+ export function defineObsidianConfig(overrides = {}) {
41
+ return defineConfig(buildObsidianConfig(overrides));
42
+ }
@@ -0,0 +1,37 @@
1
+ import { expect, type ElectronApplication, type Page, type PlaywrightTestArgs, type PlaywrightTestOptions, type PlaywrightWorkerArgs, type PlaywrightWorkerOptions, type TestType } from "@playwright/test";
2
+ import type { DemoHelpers } from "./demo/types.js";
3
+ import type { ObsidianHelpers } from "./helpers/types.js";
4
+ import type { VaultSeed } from "./seed.js";
5
+ import { type ObsidianTestOptions } from "./options.js";
6
+ import type { VaultHandle } from "./vault.js";
7
+ /** Fixtures every spec gets. */
8
+ export interface ObsidianFixtures {
9
+ /** The Obsidian window, with the workspace laid out and every installed plugin loaded. */
10
+ win: Page;
11
+ /** The Electron application: `app.evaluate` runs in the main process. */
12
+ app: ElectronApplication;
13
+ /** The per-test copy of the seed vault. */
14
+ vault: VaultHandle;
15
+ /** Helpers for settings, commands, files, the editor, themes, mobile and fakes, bound to this window. */
16
+ obsidian: ObsidianHelpers;
17
+ /** Films and stills of the window with overlays, a clean UI, frozen time and themes; see `DemoHelpers`. Only a test that asks for it pays for it. */
18
+ demo: DemoHelpers;
19
+ }
20
+ /** Options a spec sets with `test.use(...)`. */
21
+ export interface ObsidianTestUse {
22
+ /** Files and `app.json` keys added to this test's vault before Obsidian starts; see `VaultSeed`. */
23
+ seed: VaultSeed | undefined;
24
+ }
25
+ /** What a spec can use. The internal fixtures are not part of the type, so a spec cannot ask for them by mistake. */
26
+ export type ObsidianTest = TestType<PlaywrightTestArgs & PlaywrightTestOptions & ObsidianFixtures & ObsidianTestUse, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
27
+ export interface ObsidianTestKit {
28
+ readonly test: ObsidianTest;
29
+ readonly expect: typeof expect;
30
+ /** Call at the top of a spec file: skips the file unless the env var `name` is "1". */
31
+ readonly onlyWhen: (name: string) => void;
32
+ }
33
+ /**
34
+ * Builds the Playwright `test` for a plugin: every test gets a fresh Obsidian on a fresh copy of the seed vault,
35
+ * with the plugins installed and trusted. Options are checked here, so a typo fails when `fixtures.ts` is imported.
36
+ */
37
+ export declare function createObsidianTest(options: ObsidianTestOptions): ObsidianTestKit;
@@ -0,0 +1,109 @@
1
+ import path from "node:path";
2
+ import { _electron, expect, test as base, } from "@playwright/test";
3
+ import { sweepAtWorkerStart } from "./cleanup.js";
4
+ import { createElectronProbe } from "./electron-binary.js";
5
+ import { createDemo } from "./demo/create-demo.js";
6
+ import { defaultNameText } from "./demo/names.js";
7
+ import { createFixtureFunctions } from "./fixtures.js";
8
+ import { createHelpers } from "./helpers/create-helpers.js";
9
+ import { gateSkipReason, isGateOpen } from "./gate.js";
10
+ import { resolveOptions } from "./options.js";
11
+ import { createProcessIo } from "./process-tree.js";
12
+ import { startSession } from "./session.js";
13
+ /**
14
+ * Builds the Playwright `test` for a plugin: every test gets a fresh Obsidian on a fresh copy of the seed vault,
15
+ * with the plugins installed and trusted. Options are checked here, so a typo fails when `fixtures.ts` is imported.
16
+ */
17
+ export function createObsidianTest(options) {
18
+ const resolved = resolveOptions(options, { cwd: process.cwd(), env: process.env });
19
+ const functions = createFixtureFunctions(resolved, {
20
+ start: (context) => startSession(resolved, {
21
+ launch: (launchOptions) => _electron.launch(launchOptions),
22
+ io: createProcessIo(),
23
+ electron: createElectronProbe(),
24
+ env: process.env,
25
+ }, context),
26
+ sweep: (hours) => {
27
+ sweepAtWorkerStart(hours, console.warn);
28
+ },
29
+ });
30
+ const extended = base.extend({
31
+ // Playwright reads the source text of each fixture function and insists that its first parameter is an object
32
+ // destructuring pattern (it finds the fixtures a fixture depends on that way), so a function handed over by
33
+ // reference, or with a plain parameter, is refused when the tests are listed. Hence the wrappers.
34
+ // `box: true` keeps the internal fixtures out of the report's steps and error locations.
35
+ opdkSweep: [
36
+ // eslint-disable-next-line no-empty-pattern
37
+ async ({}, use) => {
38
+ await functions.sweep({}, use);
39
+ },
40
+ { scope: "worker", auto: true, box: true },
41
+ ],
42
+ // An option fixture: `test.use({ seed })` sets it per file or describe block.
43
+ seed: [undefined, { option: true }],
44
+ // Its own timeout: see `sessionFixtureTimeout`.
45
+ opdkSession: [
46
+ // `trace` and `video` are Playwright's option fixtures, so a `test.use({ trace, video })` in a spec counts.
47
+ async ({ trace, video, seed }, use, testInfo) => {
48
+ await functions.session({ trace, video, seed }, use, testInfo);
49
+ },
50
+ { box: true, timeout: functions.sessionTimeoutMs },
51
+ ],
52
+ win: async ({ opdkSession }, use) => {
53
+ await use(opdkSession.win);
54
+ },
55
+ app: async ({ opdkSession }, use) => {
56
+ await use(opdkSession.app);
57
+ },
58
+ vault: async ({ opdkSession }, use) => {
59
+ await use(opdkSession.vault);
60
+ },
61
+ opdkHelpers: [
62
+ async ({ win }, use) => {
63
+ const kit = createHelpers(win, { readyTimeoutMs: resolved.timeouts.ready, timeouts: resolved.helperTimeouts });
64
+ await use(kit);
65
+ await kit.dispose();
66
+ },
67
+ { box: true },
68
+ ],
69
+ obsidian: async ({ opdkHelpers }, use) => {
70
+ await use(opdkHelpers.helpers);
71
+ },
72
+ demo: async ({ win, opdkHelpers }, use, testInfo) => {
73
+ const controller = createDemo({
74
+ win,
75
+ cdp: () => opdkHelpers.cdpSession(),
76
+ deviceMetrics: opdkHelpers.deviceMetrics,
77
+ setTheme: (themeOptions) => opdkHelpers.helpers.setTheme(themeOptions),
78
+ collapseSidebars: () => opdkHelpers.helpers.collapseSidebars(),
79
+ settle: () => opdkHelpers.helpers.settle(),
80
+ options: resolved.demo,
81
+ uiTimeoutMs: resolved.helperTimeouts.ui,
82
+ seedVault: resolved.seedVault,
83
+ seedVaultSource: resolved.seedVaultSource,
84
+ cwd: resolved.cwd,
85
+ testTitle: defaultNameText({ titlePath: testInfo.titlePath, project: testInfo.project.name, projectCount: testInfo.config.projects.length }),
86
+ source: {
87
+ testId: testInfo.testId,
88
+ title: testInfo.titlePath.slice(1).join(" "),
89
+ file: path.relative(resolved.cwd, testInfo.file).split(path.sep).join("/"),
90
+ },
91
+ // Workers are children of the process that runs the invocation, so its pid tells the runs apart.
92
+ runId: String(process.ppid),
93
+ });
94
+ await use(controller.demo);
95
+ // After a normal return the outcome is on `testInfo`, as in the session fixture.
96
+ controller.finish({ status: testInfo.status });
97
+ },
98
+ });
99
+ // The one cast: `extend` returns a type that also lists the internal fixtures, and TestType is invariant in its
100
+ // fixture arguments, so it cannot be narrowed by assignment. Nothing else changes: it is the same object.
101
+ const test = extended;
102
+ return {
103
+ test,
104
+ expect,
105
+ onlyWhen: (name) => {
106
+ test.skip(!isGateOpen(process.env, name), gateSkipReason(name));
107
+ },
108
+ };
109
+ }
@@ -0,0 +1,21 @@
1
+ /** A rectangle in CSS pixels, relative to the window's top-left corner. */
2
+ export interface DemoRect {
3
+ readonly x: number;
4
+ readonly y: number;
5
+ readonly width: number;
6
+ readonly height: number;
7
+ }
8
+ export interface Size {
9
+ readonly width: number;
10
+ readonly height: number;
11
+ }
12
+ /** The pixels a capture of `css` produces at `scale`. */
13
+ export declare function pixelSize(css: Size, scale: number): Size;
14
+ export declare function assertPadding(padding: number): number;
15
+ /**
16
+ * The region to capture, as whole CSS pixels (a fractional clip would give a fractional pixel count and make the
17
+ * frame size depend on rounding). The rectangle itself is snapped outward; if it sticks out of the window the shot
18
+ * fails, because a clipped screenshot would silently be smaller than the element. Padding is decoration and is cut
19
+ * at the window edge instead.
20
+ */
21
+ export declare function resolveClip(rect: DemoRect, padding: number, bounds: Size, what: string): DemoRect;
@@ -0,0 +1,44 @@
1
+ /** The pixels a capture of `css` produces at `scale`. */
2
+ export function pixelSize(css, scale) {
3
+ return { width: css.width * scale, height: css.height * scale };
4
+ }
5
+ export function assertPadding(padding) {
6
+ if (!Number.isFinite(padding) || padding < 0) {
7
+ throw new Error(`padding must be a number of CSS pixels from 0, got ${String(padding)}.`);
8
+ }
9
+ return padding;
10
+ }
11
+ /**
12
+ * The region to capture, as whole CSS pixels (a fractional clip would give a fractional pixel count and make the
13
+ * frame size depend on rounding). The rectangle itself is snapped outward; if it sticks out of the window the shot
14
+ * fails, because a clipped screenshot would silently be smaller than the element. Padding is decoration and is cut
15
+ * at the window edge instead.
16
+ */
17
+ export function resolveClip(rect, padding, bounds, what) {
18
+ assertPadding(padding);
19
+ for (const [name, value] of Object.entries(rect)) {
20
+ if (!Number.isFinite(value)) {
21
+ throw new Error(`${what}: the clip has ${name} ${String(value)}, which is not a number.`);
22
+ }
23
+ }
24
+ if (rect.width <= 0 || rect.height <= 0) {
25
+ throw new Error(`${what}: the clip is ${String(rect.width)} x ${String(rect.height)}; it needs a width and a height above 0.`);
26
+ }
27
+ const left = Math.floor(rect.x);
28
+ const top = Math.floor(rect.y);
29
+ const right = Math.ceil(rect.x + rect.width);
30
+ const bottom = Math.ceil(rect.y + rect.height);
31
+ if (left < 0 || top < 0 || right > bounds.width || bottom > bounds.height) {
32
+ throw new Error(`${what}: the clip spans x ${String(left)}..${String(right)}, y ${String(top)}..${String(bottom)}, ` +
33
+ `outside the ${String(bounds.width)} x ${String(bounds.height)} window. ` +
34
+ `Make the window bigger, scroll the target into view, or clip a smaller area.`);
35
+ }
36
+ const x = Math.max(0, left - Math.ceil(padding));
37
+ const y = Math.max(0, top - Math.ceil(padding));
38
+ return {
39
+ x,
40
+ y,
41
+ width: Math.min(bounds.width, right + Math.ceil(padding)) - x,
42
+ height: Math.min(bounds.height, bottom + Math.ceil(padding)) - y,
43
+ };
44
+ }
@@ -0,0 +1,42 @@
1
+ import type { CDPSession, Page } from "@playwright/test";
2
+ import type { DeviceMetricsTracker } from "../helpers/device-metrics.js";
3
+ import type { ThemeOptions } from "../helpers/types.js";
4
+ import { type FilmSource } from "./manifest.js";
5
+ import type { ResolvedDemoOptions } from "./options.js";
6
+ import { type SeedVaultSource } from "./privacy.js";
7
+ import type { DemoHelpers } from "./types.js";
8
+ /** What the demo fixture needs from the test: the window, the shared CDP session, and the resolved options. */
9
+ export interface DemoDeps {
10
+ readonly win: Page;
11
+ /** The helpers' CDP session. The capture must use this one: Chromium keeps device metrics per session, and a second session drops `mobile()`. */
12
+ readonly cdp: () => Promise<CDPSession>;
13
+ /** The override tracker of that session (`obsidian.mobile()` sets through it too), so a repeated override is cleared first. */
14
+ readonly deviceMetrics: DeviceMetricsTracker;
15
+ readonly setTheme: (options: ThemeOptions) => Promise<void>;
16
+ /** Folds both side panels and waits until they are folded (`obsidian.collapseSidebars()`). */
17
+ readonly collapseSidebars: () => Promise<void>;
18
+ /** Waits until the page stops changing (`obsidian.settle()`); runs before the freeze of a shot that asks for it. */
19
+ readonly settle: () => Promise<void>;
20
+ readonly options: ResolvedDemoOptions;
21
+ /** How long a target may take to become visible. The session's `timeouts.helpers.ui`. */
22
+ readonly uiTimeoutMs: number;
23
+ readonly seedVault: string;
24
+ readonly seedVaultSource: SeedVaultSource;
25
+ /** The plugin folder (the directory `playwright test` runs in); a seed vault outside it is refused. */
26
+ readonly cwd: string;
27
+ /** The text a film's default name is made of (`defaultNameText`). */
28
+ readonly testTitle: string;
29
+ /** The test that records, written into every manifest. */
30
+ readonly source: FilmSource;
31
+ /** Tells the runs of `playwright test` apart; with the test id it decides whether a name clash is two tests of one run. */
32
+ readonly runId: string;
33
+ }
34
+ export interface DemoController {
35
+ readonly demo: DemoHelpers;
36
+ /** Marks the films complete when the test's status is `passed`. Anything else (failed, timed out, skipped, interrupted) leaves them incomplete. */
37
+ finish(outcome: {
38
+ status: string | undefined;
39
+ }): void;
40
+ }
41
+ /** The `demo` fixture's functions, bound to one test's window. Everything that waits polls state; the only fixed delay is `beat()`. */
42
+ export declare function createDemo(deps: DemoDeps): DemoController;