docs: add "Learn" section#10092
Conversation
✅ Deploy Preview for vitest-dev ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
| Thanks for choosing Vitest! | ||
| --> | ||
|
|
||
| ## Using Unreleased Commits |
There was a problem hiding this comment.
This is moved to CONTRIBUTING
There was a problem hiding this comment.
Pull request overview
This PR introduces a new “Learn” tutorial track within the Vitest docs to guide developers through core testing concepts, and wires it into the site navigation while adding cross-links from existing reference guides.
Changes:
- Add a new
/guide/learn/*tutorial series (writing tests, matchers, async, setup/teardown, mocking, snapshots, debugging, and AI-assisted test writing). - Update the docs sidebar to include the new Learn section and refine some Mocking sidebar labels.
- Add “start here” tips from existing guides to the new Learn tutorials, and relocate/condense some Getting Started and configuration-related content.
Reviewed changes
Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/guide/why.md | Refines the Vite-related note to better set expectations and link to Vite learning material. |
| docs/guide/snapshot.md | Adds a tip pointing beginners to the Learn snapshot tutorial. |
| docs/guide/mocking.md | Adds a tip pointing beginners to the Learn mock-functions tutorial. |
| docs/guide/lifecycle.md | Adds a tip pointing beginners to the Learn setup/teardown tutorial. |
| docs/guide/learn/writing-tests.md | New Learn tutorial covering core test structure, files, output, filtering, globals, and execution model. |
| docs/guide/learn/matchers.md | New Learn tutorial introducing common expect matchers and patterns. |
| docs/guide/learn/async.md | New Learn tutorial for async testing patterns (async/await, resolves/rejects, callbacks, timeouts). |
| docs/guide/learn/setup-teardown.md | New Learn tutorial for hooks, cleanup patterns, and fixtures via test.extend. |
| docs/guide/learn/mock-functions.md | New Learn tutorial for vi.fn, return values, implementations, spying, cleanup, and module mocking. |
| docs/guide/learn/snapshots.md | New Learn tutorial covering snapshot concepts, inline snapshots, updates, and best use cases. |
| docs/guide/learn/testing-in-practice.md | New Learn tutorial on what to test, structuring tests, mocking decisions, and organizing suites. |
| docs/guide/learn/debugging-tests.md | New Learn tutorial on reading failures, isolating issues, common causes, and debugging tooling. |
| docs/guide/learn/writing-tests-with-ai.md | New Learn tutorial on prompting/reviewing AI-generated tests and common pitfalls. |
| docs/guide/index.md | Adds next-step navigation into Learn, condenses sections, and updates links to config/CLI docs. |
| docs/guide/features.md | Adds a tip directing new users to Learn first and updates the configuration link. |
| docs/config/index.md | Adds an “Automatic Dependency Installation” section (moved from Getting Started). |
| docs/.vitepress/config.ts | Adds Learn sidebar group; updates Mocking sub-item labels (Dates/Functions/etc.). |
| CONTRIBUTING.md | Adds “Using Unreleased Commits” guidance (moved from Getting Started). |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
|
|
||
| ### Are snapshot tests overused? | ||
|
|
||
| AI loves snapshot tests because they're easy to generate: just call `toMatchSnapshot()` on everything. But snapshots should be used deliberately for structured output (HTML, error messages, serialized data), not as a lazy substitute for specific assertions. |
There was a problem hiding this comment.
Isn't this opposite? They prefer weaker test without snapshot and they avoid snapshot because they often feels they need to write the snapshot value "by hand" instead of generating by --update.
There was a problem hiding this comment.
Yeah, in my experience it prefers to use toContain over anything else
There was a problem hiding this comment.
I removed the section. the weaker test is covered by "Do the tests actually assert something meaningful?" in my opinion
There was a problem hiding this comment.
Not blocking, but this looks like a good place to also mention bug fix scenario where it describes three steps of
- write reproduction test case
- fix
- confirm test passes
This is something agents should also do to help avoiding hallcinated fix.
This PR adds a new "Learn" section meant to provide more context to new developers or those coming from a different test runner. Most of them could be useful in isolation too.
I have also cleaned up "Getting Started" by removing too advanced examples or moving them to other parts
This was originally generated with Claude and reviewed and improved by me. The documentation structure is based on Jest