Yunfei He
fa626dc90f
Document that the PTY suite runs concurrently (and the wall-clock-assertion
pitfall there), plus the two patterns that force the main suite to stay
sequential, with the root cause and fix for each:
- Inline snapshots lose test context under concurrency — fixable via the
context-local `expect` (test.concurrent("...", ({ expect }) => ...)).
- Fake timers mutate process-global timer functions, so concurrent tests
clobber each other's mocked timer state — not fixable with context; must
stay sequential.
Investigated empirically: enabling sequence.concurrent on the main suite fails
deterministically (not flaky) in exactly the snapshot files (background-color,
borders) and fake-timer files (throttle, animation-scheduler).
33 lines
3.5 KiB
Markdown
33 lines
3.5 KiB
Markdown
# Common Pitfalls & Best Practices
|
|
|
|
- AGENTS.md is the source of truth. CLAUDE.md is a symlink to it.
|
|
- Always use Vue's `shallowRef` over `ref` by default. Using `ref` requires a solid justification and a code comment explaining why deep reactivity is needed.
|
|
- Always use `defineComponent()` to define components. Never use bare `{ setup() {} }` objects — they lack component scope, so `inject`, `watch`, and `onScopeDispose` won't work correctly.
|
|
- Vue SFCs must use `<script setup>` unless there's an explicit reason not to.
|
|
- Bug fixes must follow test-first: write a failing test that reproduces the bug, then fix the code and verify the test passes.
|
|
- Tests must simulate real user conditions. Non-TTY environments disable chalk colors — use `FORCE_COLOR` env var so ANSI output is always exercised. A bug invisible in tests but visible in a real terminal is a testing gap, not a minor issue.
|
|
- When debugging color/ANSI output in non-TTY environments (e.g. Claude Code shell), use `FORCE_COLOR=3` env var to force chalk to output ANSI codes.
|
|
- The **PTY suite** (`vitest.pty.config.ts`) runs tests **concurrently** (`sequence.concurrent: true`). Each test spawns its own isolated subprocess/app, so they don't share state. Never assert on wall-clock-dependent behavior there (e.g. exact render/commit counts that rely on the renderer's ~32ms throttle): trigger the event so it renders synchronously and assert immediately after, or it flakes under CPU contention. `it.sequential` does NOT fix cross-fork CPU contention — fix the timing dependency instead.
|
|
- Two test patterns are **incompatible with concurrent execution** and must run sequentially (this is why the main `vite.config.ts` suite is **not** concurrent):
|
|
- **Inline/file snapshots** (`toMatchInlineSnapshot`): the module-level `expect` loses snapshot test context under concurrency. _Fixable_ — destructure the context-local `expect`: `test.concurrent("name", async ({ expect }) => { expect(x).toMatchInlineSnapshot() })`.
|
|
- **Fake timers** (`vi.useFakeTimers` / `advanceTimersByTime`): these mutate the **process-global** timer functions, so a concurrent test calling `useRealTimers()` yanks the mocked API out from under another mid-`advanceTimersByTime` ("timers not mocked"). _Not fixable_ with context — these tests must stay sequential.
|
|
- After completing any task, run `vp run ready` (or `vpr ready`) to verify: lint, type-check, test all packages, and build.
|
|
- Never commit anything under `docs/`. That directory is for local working notes and specs — it must stay out of git.
|
|
|
|
<!--VITE PLUS START-->
|
|
|
|
# Using Vite+, the Unified Toolchain for the Web
|
|
|
|
This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. Vite+ is distinct from Vite, and it invokes Vite through `vp dev` and `vp build`. Run `vp help` to print a list of commands and `vp <command> --help` for information about a specific command.
|
|
|
|
Docs are local at `node_modules/vite-plus/docs` or online at https://viteplus.dev/guide/.
|
|
|
|
## Review Checklist
|
|
|
|
- [ ] Run `vp install` after pulling remote changes and before getting started.
|
|
- [ ] Run `vp check` and `vp test` to format, lint, type check and test changes.
|
|
- [ ] Check if there are `vite.config.ts` tasks or `package.json` scripts necessary for validation, run via `vp run <script>`.
|
|
- [ ] If setup, runtime, or package-manager behavior looks wrong, run `vp env doctor` and include its output when asking for help.
|
|
|
|
<!--VITE PLUS END-->
|