frontend-test-authoring

星标10

分支2

更新时间2026年7月3日 14:19

Writing Modelibr frontend Jest tests — the can't-fail deletion rule, test tiers (api contract / hook+store / flow), mock infrastructure (global apiBase mock, MSW tier, typed fixtures), regression-comment convention, PrimeReact/virtuoso gotchas. Use when creating or editing any test under src/frontend. For Playwright E2E use e2e-authoring instead.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

来源

Papyszoo

Papyszoo/Modelibr

打开 GitHub 仓库查看创作者相关仓库

下载

Frontend test authoring (Jest + Testing Library)

The one rule

Every test must be able to fail while the feature is broken. Before writing (or keeping) a test, name the regression that would make it go red. Forbidden: static text/placeholder assertions with no logic behind them, "renders without crashing", asserting a mock was called with what you just passed, mocking PrimeReact (or any component library) and asserting on the stub. If the only thing that can fail it is a label rename, delete it.

Convention: name the regression

Each test (or its describe block) carries a comment saying what real bug it catches — see ScriptList.flow.test.tsx ("the language options were derived from the filtered result set…") or soundApi.test.ts ("a truthy check here would drop 'from 0 seconds'"). If you can't write that comment, see rule one.

Three tiers — pick by what you're testing

API contract tests (features/*/api/__tests__/): the mocked axios client (globally mocked in setupTests.ts; cast client.get as jest.Mock). Assert request construction — URL/params serialization, payload shape (keys omitted vs null), response unwrapping — plus at least one error path. Model: soundApi.test.ts.
Hook/store behavior: renderHook + createQueryWrapper / createTestQueryClient from src/test/renderWithProviders.tsx (fresh QueryClient per test, retries off). Stores: test transitions/persistence, not set-wrappers. Model: useScriptListData.test.ts, uploadProgressStore.test.ts.
Flow tests (X.flow.test.tsx, one per page): real component tree via renderWithProviders, real user-event, network-level mocks. Baseline: load → filter → mutate → assert the list reflects it after refetch (the invalidation check) → failure path (error state, no crash, retry recovers). Model: ScriptList.flow.test.tsx. These are the layer that catches "app broken, tests green".

Mock infrastructure (know what's already mocked)

setupTests.ts globally mocks @/lib/apiBase — every unconfigured client.get/post/… resolves undefined. A component test that doesn't set up its API responses is testing a broken data path and must not assert success states. jest.clearAllMocks() + explicit mockImplementation per file (route by URL, like the flow tests do).
MSW tier (once prompt 39 lands): flow tests opt in via src/test/mswServer.ts to run the REAL apiBase (interceptors + ApiClientError) with onUnhandledRequest: 'error' — unmocked requests fail loudly. Prefer it for new flow tests; check the helper's header for the opt-out mechanics.
Fixtures: use the typed builders in src/test/fixtures/ (once they exist — prompt 39); never hand-roll DTO literals in new tests. Typed fixtures turn backend DTO drift into compile errors.
Error paths assert the real ApiClientError fields (status, code, isOffline, isTimeout) — not just "something threw".

Gotchas

Jest, not Vitest (worker uses Vitest — don't cross-pollinate config).
import.meta.env doesn't exist in Jest — env comes from process.env set in setupTests.ts; that's why apiBase is module-mocked. Don't import modules that read import.meta at module scope without a mock.
CSS imports resolve via identity-obj-proxy — the CSS moduleNameMapper rule must stay ABOVE the @/ alias in jest.config.js (first-match-wins).
PrimeReact overlays render into document.body — query panels via document.querySelector('.p-dropdown-panel')-style helpers (see ScriptList.flow) and use real PrimeReact, never a stub.
react-virtuoso lists may not render rows in jsdom without viewport sizing — use/extend the shared helper in src/test/; never fix with timeouts.
Tab-context dependencies: stub @/hooks/useTabContext per file when a component opens tabs (see ScriptList.flow) — that's an app-shell seam, not over-mocking.

Where tests live / verify

__tests__/*.test.ts(x) next to the code under test. Run one file while iterating: npx jest path/to/file.test.tsx -t "name". Full gate: cd src/frontend && npm test && npm run lint && npm run format:check. Planned work: prompts 37 (prune), 39 (mock infra), 40 (flow rollout).

同仓库更多 Skills

同仓库

release-workflow

Papyszoo/Modelibr

Modelibr git and release conventions — version-branch naming and protection, PR targeting, conventional commits (never an AI co-author trailer), and the version-branch→main release cadence. Use when branching, committing, opening PRs, cutting a release, or configuring branch protection.

2026-07-1210

test-triage

Papyszoo/Modelibr

Diagnose a failing test suite ("visual regression failed", "e2e is red", "backend tests broke") by locating the right logs and artifacts — test-report/logs, Playwright reports/traces, visual diff PNGs, TRX files — and analyzing the failure. Use whenever the user reports a test failure and wants to know what/why, or asks where test logs live.

2026-07-1210

backend-patterns

Papyszoo/Modelibr

Modelibr backend conventions — Clean Architecture boundaries, Result/Error, CQRS handlers, domain events, validation, DI, repositories, minimal API endpoints, known traps, xUnit naming. Use when creating or editing code under src/WebApi, src/Application, src/Domain, src/Infrastructure, or src/SharedKernel.

2026-07-1110

asset-processor-patterns

Papyszoo/Modelibr

Modelibr asset-processor (Node.js worker) conventions — config.js discipline, ProcessorRegistry/BaseProcessor lifecycle, job queue/timeout traps, RendererPool/Puppeteer rules, unified API-client usage, shared cross-runtime lib, offline-safe rendering, Vitest. Use when creating or editing code under src/asset-processor.

2026-07-1110

skill-authoring

Papyszoo/Modelibr

How to write and maintain Modelibr agent skills — compactness budget, structure template, staleness rules, what belongs in a skill vs the code vs CLAUDE.md. Use when creating or editing anything under .claude/skills/.

2026-07-1010

webdav-patterns

Papyszoo/Modelibr

Modelibr WebDAV virtual drive — middleware interception (Blender Safe Save), virtual store/collections, client-compat shims for macOS Finder/Windows Explorer/Blender, temp-file lifecycle, data-safety rules. Use when creating or editing src/WebApi/Infrastructure/WebDavMiddleware.cs, src/WebApi/Services/*WebDav*/RequestHandlerFactory, or anything under src/Infrastructure/WebDav.

2026-07-1010

name	frontend-test-authoring
description	Writing Modelibr frontend Jest tests — the can't-fail deletion rule, test tiers (api contract / hook+store / flow), mock infrastructure (global apiBase mock, MSW tier, typed fixtures), regression-comment convention, PrimeReact/virtuoso gotchas. Use when creating or editing any test under src/frontend. For Playwright E2E use e2e-authoring instead.

Frontend test authoring (Jest + Testing Library)

The one rule

Convention: name the regression

Three tiers — pick by what you're testing

API contract tests (features/*/api/__tests__/): the mocked axios client (globally mocked in setupTests.ts; cast client.get as jest.Mock). Assert request construction — URL/params serialization, payload shape (keys omitted vs null), response unwrapping — plus at least one error path. Model: soundApi.test.ts.
Hook/store behavior: renderHook + createQueryWrapper / createTestQueryClient from src/test/renderWithProviders.tsx (fresh QueryClient per test, retries off). Stores: test transitions/persistence, not set-wrappers. Model: useScriptListData.test.ts, uploadProgressStore.test.ts.
Flow tests (X.flow.test.tsx, one per page): real component tree via renderWithProviders, real user-event, network-level mocks. Baseline: load → filter → mutate → assert the list reflects it after refetch (the invalidation check) → failure path (error state, no crash, retry recovers). Model: ScriptList.flow.test.tsx. These are the layer that catches "app broken, tests green".

Mock infrastructure (know what's already mocked)

setupTests.ts globally mocks @/lib/apiBase — every unconfigured client.get/post/… resolves undefined. A component test that doesn't set up its API responses is testing a broken data path and must not assert success states. jest.clearAllMocks() + explicit mockImplementation per file (route by URL, like the flow tests do).
MSW tier (once prompt 39 lands): flow tests opt in via src/test/mswServer.ts to run the REAL apiBase (interceptors + ApiClientError) with onUnhandledRequest: 'error' — unmocked requests fail loudly. Prefer it for new flow tests; check the helper's header for the opt-out mechanics.
Fixtures: use the typed builders in src/test/fixtures/ (once they exist — prompt 39); never hand-roll DTO literals in new tests. Typed fixtures turn backend DTO drift into compile errors.
Error paths assert the real ApiClientError fields (status, code, isOffline, isTimeout) — not just "something threw".

Gotchas

Jest, not Vitest (worker uses Vitest — don't cross-pollinate config).
import.meta.env doesn't exist in Jest — env comes from process.env set in setupTests.ts; that's why apiBase is module-mocked. Don't import modules that read import.meta at module scope without a mock.
CSS imports resolve via identity-obj-proxy — the CSS moduleNameMapper rule must stay ABOVE the @/ alias in jest.config.js (first-match-wins).
PrimeReact overlays render into document.body — query panels via document.querySelector('.p-dropdown-panel')-style helpers (see ScriptList.flow) and use real PrimeReact, never a stub.
react-virtuoso lists may not render rows in jsdom without viewport sizing — use/extend the shared helper in src/test/; never fix with timeouts.
Tab-context dependencies: stub @/hooks/useTabContext per file when a component opens tabs (see ScriptList.flow) — that's an app-shell seam, not over-mocking.