@linkdesk/plugin-docs 0.1.30 → 0.1.32
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.
|
@@ -254,6 +254,27 @@ Step one: your `.linkdesk-plugin` asset shows up on the GitHub Release. Step two
|
|
|
254
254
|
|
|
255
255
|
---
|
|
256
256
|
|
|
257
|
+
## Tests in a plugin repo
|
|
258
|
+
|
|
259
|
+
Nothing to set up — but "should I test this?" deserves a straight answer.
|
|
260
|
+
|
|
261
|
+
- **The toolchain is preinstalled.** `vitest` / `jsdom` / `@testing-library/react` are already in `devDependencies` — write `src/__tests__/<same-name>.test.ts` and run `npm run test`.
|
|
262
|
+
- **The shared test ground comes from the SDK.** The minimal `window.linkdesk` mock lives in `@linkdesk/plugin-sdk/vitest-setup`, and your `vitest.setup.ts` is a **one-line pointer** to it. ⛔ **Do not paste a second copy into your repo** — a copied mock silently drifts from the shared one.
|
|
263
|
+
- **Pure logic is what pays off.** A unit under `src/**/*.ts` that touches neither React nor `window.linkdesk` should get a test. Views and interactions are worth testing **when it pays off** — nothing measures that today.
|
|
264
|
+
- **What counts as "covered" — two criteria, both mechanical.** A unit is covered when a test file shares its basename (`Foo.ts` ↔ `Foo.test.ts`) **or** any test file references it (a direct import or through a barrel). Grep is enough to self-check: `grep -rl "Foo" src/__tests__/`. Watch out for the false alarm: a unit exercised only *through* another tested module (the same-basename criterion cannot see cross-file coverage) is not "untested" — read what your tests actually cover before adding more.
|
|
265
|
+
- **Views: smoke-test when it pays off.** The cheap, honest pattern is two assertions — the component **renders without crashing** and **one key interaction works** (click → the expected callback fires). Stub `react-i18next` with a fake `t` that echoes the key, stub the slice of `window.linkdesk` your view reads in your own test file (minimal surface), and keep fixtures fictional. Nobody is expected to chase deep UI coverage.
|
|
266
|
+
- **Plugin-specific stubs stay in your own test files.** Does your code call something the shared mock does not cover (say `window.linkdesk.serial`)? Stub it with `vi.fn()` in the test that needs it — do not expect the shared mock to grow a branch for your plugin.
|
|
267
|
+
- **Declarative plugins** (pure JSON / themes / language packs) have **no testable units** — their gate is `npm run verify` (structure + declarations). **"It has no tests" is not a defect there.**
|
|
268
|
+
- **Older projects can migrate whenever they like.** Replacing the full mock body with the one-line pointer plus one `npm install` is the whole move (upside: mock upgrades then ride along with the SDK).
|
|
269
|
+
|
|
270
|
+
**How to know you did it right**
|
|
271
|
+
|
|
272
|
+
```bash
|
|
273
|
+
npm run test # vitest run — an empty suite passes on purpose (passWithNoTests)
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
257
278
|
## Pitfalls Beginners Hit Most
|
|
258
279
|
|
|
259
280
|
| Symptom | Root cause | Where to look |
|
|
@@ -281,4 +302,5 @@ Step one: your `.linkdesk-plugin` asset shows up on the GitHub Release. Step two
|
|
|
281
302
|
| A whole **replacement settings UI** | [10-building-a-settings-plugin](10-building-a-settings-plugin.md) |
|
|
282
303
|
| Build **themes/icons** | [11-authoring-themes](11-authoring-themes.md) |
|
|
283
304
|
| **Where files should go**; authoritative README/CHANGELOG criteria | [09-plugin-directory-layout](09-plugin-directory-layout.md) |
|
|
305
|
+
| Decide **whether / how to test my plugin** | [§ Tests in a plugin repo](#tests-in-a-plugin-repo) |
|
|
284
306
|
| The full documentation index | [00-readme §Documentation Index](00-readme.md#documentation-index) |
|
package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md
CHANGED
|
@@ -254,6 +254,27 @@ env:
|
|
|
254
254
|
|
|
255
255
|
---
|
|
256
256
|
|
|
257
|
+
## 插件仓里的测试怎么写
|
|
258
|
+
|
|
259
|
+
不用配任何东西——但「这段该不该测」值得一个直给的回答。
|
|
260
|
+
|
|
261
|
+
- **工具链已预装**:`vitest` / `jsdom` / `@testing-library/react` 都在 `devDependencies` 里,写 `src/__tests__/<同名>.test.ts`,然后 `npm run test`。
|
|
262
|
+
- **共享测试地基由 SDK 提供**:`window.linkdesk` 的最小 mock 住在 `@linkdesk/plugin-sdk/vitest-setup`,你仓里的 `vitest.setup.ts` 是指向它的**一行指针**。⛔ **不要在自己仓里再抄一份**——抄来的那份会与共享版**无声漂移**。
|
|
263
|
+
- **纯逻辑最值得测**:`src/**/*.ts` 里既不碰 React、也不碰 `window.linkdesk` 的单元,应该配上测试。视图与交互**划得来时再测**——今天没有任何东西在量它。
|
|
264
|
+
- **「算覆盖」的判据有两条,都是机械的**:单元被覆盖 = 有**同名测试文件**(`Foo.ts` ↔ `Foo.test.ts`)**或**被任一测试文件引用到(直接 import 或经 barrel)。自查用 grep 就够:`grep -rl "Foo" src/__tests__/`。当心**假红**:某个单元只**经过**另一个被测模块间接跑到(同名判据看不见跨文件覆盖),不等于「没测」——先读你的测试实际覆盖了什么,再决定补不补。
|
|
265
|
+
- **视图层:划得来时做冒烟**:便宜而诚实的样板就两条断言——组件**渲染不炸** + **一个关键交互走通**(点一下 ⇒ 预期回调被调)。替身面:`react-i18next` 用回 key 的假 `t`,视图读到的 `window.linkdesk` 那一片在**你自己的测试文件**里就地桩住(最小面),夹具全用虚构名。深度 UI 覆盖率不要求任何人追。
|
|
266
|
+
- **插件专属桩住本仓**:你的代码调了共享 mock 没覆盖的东西(比如 `window.linkdesk.serial`)?在需要它的那个测试文件里用 `vi.fn()` 补上——别指望共享 mock 为你的插件长一条分支。
|
|
267
|
+
- **声明式插件**(纯 JSON/主题/语言包)**没有可测单元**——它的门禁是 `npm run verify`(结构与声明)。**「没有测试」在那里不是缺陷。**
|
|
268
|
+
- **老仓什么时候迁都行**:把整份 mock 换成一枚一行指针 + 一次 `npm install`,就是全部动作(好处:mock 升级从此跟着 SDK 走)。
|
|
269
|
+
|
|
270
|
+
**怎么知道做对了**
|
|
271
|
+
|
|
272
|
+
```bash
|
|
273
|
+
npm run test # vitest run——空测试集**故意**判过(passWithNoTests)
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
257
278
|
## 新手最常踩的坑
|
|
258
279
|
|
|
259
280
|
| 症状 | 病根 | 去哪看 |
|
|
@@ -281,4 +302,5 @@ env:
|
|
|
281
302
|
| 整套**替代设置 UI** | [10-如何造一个设置插件](10-如何造一个设置插件.md) |
|
|
282
303
|
| 做**主题/图标** | [11-主题制作](11-主题制作.md) |
|
|
283
304
|
| 文件**该放哪**、README/CHANGELOG 权威判据 | [09-插件目录规范](09-插件目录规范.md) |
|
|
305
|
+
| 决定**要不要/怎么写测试** | [§ 插件仓里的测试怎么写](#插件仓里的测试怎么写) |
|
|
284
306
|
| 全部文档索引 | [00-README §文档索引](00-README.md#文档索引) |
|