@vitest-agent/mcp 1.0.1 → 1.2.0

package/public/vendor/vitest-docs/guide/learn/testing-in-practice.md

@@ -1,430 +0,0 @@
-# Testing in Practice
-
-The previous pages covered the Vitest API: assertions, mocking, snapshots, and test lifecycle hooks. This page focuses on applying those tools to real code. It covers how to decide what to test, how to structure tests effectively, and how to organize test files as a project grows.
-
-## What to Test
-
-When you sit down to write tests for a function or module, start by thinking about its **contract**: what does it promise to do for the code that calls it? The contract is defined by its inputs (arguments, configuration) and its outputs (return values, side effects, errors). These are the things your tests should verify.
-
-Consider a `formatPrice` function:
-
-```js [formatPrice.js]
-export function formatPrice(amount, currency) {
-  return new Intl.NumberFormat('en-US', {
-    style: 'currency',
-    currency,
-  }).format(amount)
-}
-```
-
-The contract here is: given an amount and a currency code, return a formatted price string. Good tests for this function would cover:
-
-```js [formatPrice.test.js]
-import { expect, test } from 'vitest'
-import { formatPrice } from './formatPrice.js'
-
-test('formats USD prices', () => {
-  expect(formatPrice(10, 'USD')).toBe('$10.00')
-})
-
-test('formats EUR prices', () => {
-  expect(formatPrice(10, 'EUR')).toBe('€10.00')
-})
-
-test('handles zero', () => {
-  expect(formatPrice(0, 'USD')).toBe('$0.00')
-})
-
-test('handles negative amounts', () => {
-  expect(formatPrice(-5.5, 'USD')).toBe('-$5.50')
-})
-
-test('rounds to two decimal places', () => {
-  expect(formatPrice(10.999, 'USD')).toBe('$11.00')
-})
-```
-
-Notice what these tests *don't* do. They don't check which internal `Intl.NumberFormat` options were passed, or whether an intermediate variable was set. They only check the output.
-
-::: tip
-A good rule of thumb: if someone refactors the internals but the output stays the same, should the test break? If it would, you're probably testing implementation details rather than behavior.
-:::
-
-## Structuring a Test
-
-Most tests follow a natural three-part structure, sometimes called "Arrange, Act, Assert":
-
-1. **Set up** the data your test needs
-2. **Call** the function or perform the action you're testing
-3. **Check** that the result matches your expectations
-
-```js
-test('removes an item from the list', () => {
-  // Set up
-  const list = new ShoppingList()
-  list.add('milk')
-  list.add('bread')
-
-  // Act
-  list.remove('milk')
-
-  // Check
-  expect(list.getItems()).toEqual(['bread'])
-})
-```
-
-You don't need comments labeling each section. The structure becomes natural once you've written a few tests. The important thing is keeping each test focused on one behavior.
-
-### One Behavior Per Test
-
-If you find yourself writing "and" in a test name ("formats price and handles errors and logs the result"), that's a sign you should split it into separate tests.
-
-### Descriptive Names
-
-Write test names that describe the behavior, not the implementation. "returns formatted price for USD" is better than "calls Intl.NumberFormat with correct options". When a test fails, the name should tell you what broke without having to read the test body.
-
-## Testing Edge Cases
-
-After covering the main behavior, think about the boundaries. What happens at the edges? What inputs are unusual but valid? What should happen when things go wrong?
-
-Here's an example with a `parseAge` function that takes user input and returns a number:
-
-```js [parseAge.js]
-export function parseAge(input) {
-  const age = Number(input)
-  if (Number.isNaN(age) || age < 0 || age > 150) {
-    throw new Error(`Invalid age: ${input}`)
-  }
-  return Math.floor(age)
-}
-```
-
-The happy path is straightforward, but the edge cases are where bugs hide:
-
-```js [parseAge.test.js]
-import { expect, test } from 'vitest'
-import { parseAge } from './parseAge.js'
-
-test('parses a valid age', () => {
-  expect(parseAge('25')).toBe(25)
-})
-
-test('rounds down decimal ages', () => {
-  expect(parseAge('25.9')).toBe(25)
-})
-
-test('handles zero', () => {
-  expect(parseAge('0')).toBe(0)
-})
-
-test('handles the upper boundary', () => {
-  expect(parseAge('150')).toBe(150)
-})
-
-test('throws for negative numbers', () => {
-  expect(() => parseAge('-1')).toThrow('Invalid age: -1')
-})
-
-test('throws for numbers above 150', () => {
-  expect(() => parseAge('151')).toThrow('Invalid age: 151')
-})
-
-test('throws for non-numeric strings', () => {
-  expect(() => parseAge('abc')).toThrow('Invalid age: abc')
-})
-
-test('throws for empty string', () => {
-  expect(() => parseAge('')).toThrow('Invalid age: ')
-})
-```
-
-You don't need to test every possible input. Focus on the boundaries (0, 150, 151, -1), the error paths, and the types of inputs your function might realistically receive.
-
-::: tip
-If you're unsure whether an edge case matters, ask yourself: could a real user or a real caller trigger this? If yes, test it.
-:::
-
-### Property-Based Testing
-
-For functions with a wide range of valid inputs, manually choosing edge cases can only go so far. **Property-based testing** is a technique where you describe the *properties* that should hold for any input, and the testing framework generates hundreds of random inputs to try to find one that breaks.
-
-For example, you might say "for any valid age string, `parseAge` should return a non-negative integer" and let the tool find the counterexample. [fast-check](https://fast-check.dev/) is a popular property-based testing library that integrates well with Vitest. It's an advanced technique, but worth knowing about as your testing needs grow.
-
-## When to Mock
-
-Mocking is a powerful tool, but it's easy to overuse.
-
-### Slow Dependencies
-
-Network requests, file system operations, and database calls can make your tests take seconds instead of milliseconds. Replace them with mocks to keep the feedback loop fast.
-
-For HTTP requests specifically, consider using [Mock Service Worker](https://mswjs.io/) instead of mocking fetch directly. See the [Mocking Requests](/guide/mocking/requests) guide for setup instructions.
-
-### Non-Deterministic Values
-
-If your code depends on the current date, a random number, or a UUID generator, mock those to make your tests predictable. Vitest provides [`vi.useFakeTimers()`](/api/vi#vi-usefaketimers) and [`vi.setSystemTime()`](/api/vi#vi-setsystemtime) for controlling time in tests.
-
-### What Not to Mock
-
-Don't mock the thing you're testing. If you're testing a `UserService`, don't mock the `UserService`. Mock its *dependencies* (the database, the email sender) and let the service itself run for real.
-
-Also, prefer real implementations when they're fast and reliable. If a dependency is a simple in-memory data structure or a pure function, there's no reason to mock it. The closer your tests are to real usage, the more confidence they give you.
-
-::: tip
-Only reach for mocks when the real thing is slow, flaky, or has side effects you can't control in a test.
-:::
-
-## Fixing Bugs with Tests
-
-When you find a bug, it's tempting to jump straight into the code and fix it. A better approach is to write a failing test first that reproduces the bug, then fix the code and watch the test turn green.
-
-This has several benefits. The test proves the bug is real and not just a misunderstanding. It documents exactly what was broken. And it prevents the same bug from coming back later, because the test will catch it if someone accidentally reintroduces the same problem.
-
-Here's what this looks like in practice. Suppose users report that `parseAge` crashes when given a string with leading spaces like `" 25"`. First, write a test that reproduces the problem:
-
-```js
-test('handles leading spaces', () => {
-  expect(parseAge(' 25')).toBe(25)
-})
-```
-
-Run it and confirm it fails. Now you know exactly what's broken and have a clear target. Fix the implementation:
-
-```js
-export function parseAge(input) {
-  const age = Number(input.trim())
-  // ...
-}
-```
-
-Run the test again. It passes. The bug is fixed, and you have a regression test that will catch it if someone removes the `.trim()` call later.
-
-::: tip
-If you use AI agents to fix bugs, configure them to follow the same principle: reproduce the issue with a failing test first, then fix the code. This prevents the agent from "fixing" a bug by changing the test instead of the code, and gives you confidence that the fix actually works.
-:::
-
-## Organizing Test Files
-
-There's no single right way to organize tests, but some patterns scale better than others.
-
-### File Layout
-
-The simplest starting point is one test file per source file. For every `utils.js`, there's a `utils.test.js` right next to it. This makes it easy to find the tests for any given piece of code, and most editors will show them side by side in the file tree:
-
-```
-src/
-  utils.js
-  utils.test.js
-  formatPrice.js
-  formatPrice.test.js
-```
-
-Some teams prefer a separate `__tests__` or `test` directory instead. Either approach works. The important thing is consistency across the project. Vitest's [`include`](/config/include) pattern matches both layouts by default.
-
-### Grouping with `describe`
-
-When a module exports multiple functions, use `describe` blocks to group the tests for each one. This keeps the test output organized and makes it clear which function a failing test belongs to:
-
-```js
-describe('formatPrice', () => {
-  test('formats USD prices', () => { /* ... */ })
-  test('handles zero', () => { /* ... */ })
-})
-
-describe('parseAmount', () => {
-  test('parses valid amounts', () => { /* ... */ })
-  test('throws for invalid input', () => { /* ... */ })
-})
-```
-
-Avoid nesting `describe` blocks more than one or two levels deep. Deeply nested test trees are hard to read and usually mean the source module is doing too many things at once.
-
-### Splitting Large Files
-
-As a project grows, some test files will inevitably get long. If a test file grows beyond a few hundred lines, consider splitting it by theme or feature area. For example, `userService.test.js` might become `userService.creation.test.js` and `userService.auth.test.js`. This also makes it faster to run a subset of tests during development.
-
-### Naming Tests
-
-Test names matter more than you might expect. When a test fails in CI, the name is often the first thing someone reads. Names like "works correctly" or "handles edge case" don't tell you what broke.
-
-Prefer names that describe the specific behavior: "returns 0 for an empty cart", "throws if the email format is invalid", "preserves existing items when adding a new one". The test output should read like a specification of what the module does.
-
-## A Worked Example
-
-Let's put it all together. Here's a small `TodoList` module:
-
-```js [todoList.js]
-let nextId = 1
-
-export function createTodoList() {
-  const items = []
-
-  return {
-    add(text) {
-      if (!text.trim()) {
-        throw new Error('Todo text cannot be empty')
-      }
-      const todo = { id: nextId++, text, completed: false }
-      items.push(todo)
-      return todo
-    },
-
-    remove(id) {
-      const index = items.findIndex(item => item.id === id)
-      if (index === -1) {
-        throw new Error(`Todo with id ${id} not found`)
-      }
-      items.splice(index, 1)
-    },
-
-    toggle(id) {
-      const todo = items.find(item => item.id === id)
-      if (!todo) {
-        throw new Error(`Todo with id ${id} not found`)
-      }
-      todo.completed = !todo.completed
-    },
-
-    getAll() {
-      return items
-    },
-
-    getCompleted() {
-      return items.filter(item => item.completed)
-    },
-  }
-}
-```
-
-Looking at this code, we can identify the behaviors to test:
-
-- Adding items (the main purpose)
-- Adding empty items (should fail)
-- Removing items by ID
-- Removing items that don't exist (should fail)
-- Toggling completion status
-- Getting all items vs. completed items
-
-Here's how the test file might look:
-
-```js [todoList.test.js]
-import { describe, expect, test } from 'vitest'
-import { createTodoList } from './todoList.js'
-
-describe('add', () => {
-  test('adds a new todo', () => {
-    const list = createTodoList()
-    const todo = list.add('Buy groceries')
-
-    expect(todo.text).toBe('Buy groceries')
-    expect(todo.completed).toBe(false)
-    expect(list.getAll()).toHaveLength(1)
-  })
-
-  test('assigns unique IDs to each todo', () => {
-    const list = createTodoList()
-    const first = list.add('First')
-    const second = list.add('Second')
-
-    expect(first.id).not.toBe(second.id)
-  })
-
-  test('throws when text is empty', () => {
-    const list = createTodoList()
-    expect(() => list.add('')).toThrow('Todo text cannot be empty')
-  })
-
-  test('throws when text is only whitespace', () => {
-    const list = createTodoList()
-    expect(() => list.add('   ')).toThrow('Todo text cannot be empty')
-  })
-})
-
-describe('remove', () => {
-  test('removes a todo by ID', () => {
-    const list = createTodoList()
-    const todo = list.add('Buy groceries')
-
-    list.remove(todo.id)
-
-    expect(list.getAll()).toHaveLength(0)
-  })
-
-  test('keeps other items when removing one', () => {
-    const list = createTodoList()
-    const first = list.add('First')
-    list.add('Second')
-
-    list.remove(first.id)
-
-    expect(list.getAll()).toHaveLength(1)
-    expect(list.getAll()[0].text).toBe('Second')
-  })
-
-  test('throws when ID does not exist', () => {
-    const list = createTodoList()
-    expect(() => list.remove(999)).toThrow('Todo with id 999 not found')
-  })
-})
-
-describe('toggle', () => {
-  test('marks a todo as completed', () => {
-    const list = createTodoList()
-    const todo = list.add('Buy groceries')
-
-    list.toggle(todo.id)
-
-    expect(list.getAll()[0].completed).toBe(true)
-  })
-
-  test('toggles back to incomplete', () => {
-    const list = createTodoList()
-    const todo = list.add('Buy groceries')
-
-    list.toggle(todo.id)
-    list.toggle(todo.id)
-
-    expect(list.getAll()[0].completed).toBe(false)
-  })
-
-  test('throws when ID does not exist', () => {
-    const list = createTodoList()
-    expect(() => list.toggle(999)).toThrow('Todo with id 999 not found')
-  })
-})
-
-describe('getCompleted', () => {
-  test('returns only completed todos', () => {
-    const list = createTodoList()
-    const buy = list.add('Buy groceries')
-    list.add('Clean house')
-    list.toggle(buy.id)
-
-    const completed = list.getCompleted()
-
-    expect(completed).toHaveLength(1)
-    expect(completed[0].text).toBe('Buy groceries')
-  })
-
-  test('returns empty array when nothing is completed', () => {
-    const list = createTodoList()
-    list.add('Buy groceries')
-
-    expect(list.getCompleted()).toHaveLength(0)
-  })
-})
-```
-
-Each `describe` block focuses on one method. Each test verifies one specific behavior. The test names read like a specification of what the module does. And if any of these tests fail, the name and the assertion will tell you exactly what broke.
-
-::: tip
-Notice that we create a fresh `createTodoList()` in every test. This keeps tests independent, which means they can run in any order without affecting each other. If you find yourself repeating the same setup in every test, that's a good candidate for [`beforeEach`](/api/hooks#beforeeach) or a [`test.extend`](/guide/test-context#extend-test-context) fixture.
-:::
-
-::: details What about `nextId`?
-The `nextId` counter at the top of the module is shared across all calls to `createTodoList()`, including across tests. This means IDs aren't predictable: one test might get IDs 1 and 2, while another gets 3 and 4 depending on execution order. This works fine here because the tests only check *relative* uniqueness (`first.id !== second.id`), not specific ID values. If a test asserted `expect(todo.id).toBe(1)`, it would break depending on which tests ran before it. When you have shared module-level state like this, make sure your tests don't depend on its specific value.
-:::
-
----
-
-If you're building a web application and want to test components in a real browser environment, check out [Component Testing](/guide/browser/component-testing) for testing React, Vue, Svelte, and other UI frameworks.

package/public/vendor/vitest-docs/guide/learn/writing-tests-with-ai.md

@@ -1,127 +0,0 @@
-# Writing Tests with AI
-
-AI coding assistants can help you write tests faster, but the quality of the output depends heavily on what you put in. A vague prompt produces vague tests. A specific prompt with the right context produces tests that are actually worth keeping.
-
-This page covers how to get good test code from AI tools, and what to watch for when reviewing the results.
-
-## Providing Context
-
-The single most important thing you can do is give the AI enough context to understand what it's testing.
-
-Start with the source file itself. The AI needs to see the actual implementation, not just a description of what the function does. Include the full file, or at least the function you want tested along with its imports and types.
-
-Share existing test files from the same project. This helps the AI match your conventions: whether you use `test` or `it`, how you structure `describe` blocks, whether you prefer `test.extend` fixtures or `beforeEach`, and how you name your tests. AI tools are good at pattern matching, but they need patterns to match against.
-
-Include your Vitest config, especially if you've enabled [`globals`](/config/globals), set a custom [`environment`](/config/environment), or configured [`setupFiles`](/config/setupfiles). Without this context, the AI might generate unnecessary imports, use the wrong test environment, or miss setup that your tests depend on.
-
-If the code under test has dependencies that need mocking, share those files too (or at least their type signatures). The AI can't write a useful mock for a database client it's never seen.
-
-::: tip
-If your project has an `AGENTS.md` or similar file with coding conventions, include that as well. Many AI tools pick up on these automatically and will follow the rules defined there.
-:::
-
-## Writing Good Prompts
-
-Specific prompts produce better tests than generic ones. Compare these two:
-
-**Vague:** "Write tests for `userService.js`"
-
-This will produce tests, but they'll likely be shallow: one happy-path test per function, minimal edge case coverage, and generic test names.
-
-**Better:** "Write tests for the `createUser` function in `userService.js`. Cover validation errors (missing name, invalid email format, duplicate email), the successful creation path, and verify that the password is hashed before being stored."
-
-This tells the AI exactly which function to focus on, which scenarios matter, and what behavior to verify. The output will be more thorough and more relevant.
-
-### Tips for Better Prompts
-
-- Ask for edge cases explicitly. "Include tests for empty inputs, boundary values, and error handling" produces more comprehensive coverage than leaving it to the AI's judgment. Without this nudge, most tools will generate a handful of happy-path tests and stop there.
-- Mention specific Vitest features if you want them used. "Use `toMatchInlineSnapshot` for the error messages" or "use `test.each` for the different currency formats" guides the AI toward the right tools instead of letting it fall back to repetitive copy-paste tests.
-- If you're testing async code, say so. "The function returns a Promise" or "this calls an external API" helps the AI use `async`/`await` and appropriate matchers like `.resolves` and `.rejects`.
-- Tell the AI what *not* to do. "Test against the real implementation, don't mock any modules" or "don't use snapshot tests" prevents common defaults you don't want. AI tools tend to over-mock, and an explicit constraint prevents that.
-- Describe the test structure you want. "Group tests by method using `describe` blocks" or "use `test.extend` fixtures for the database connection instead of `beforeEach`" saves you from restructuring the output afterwards.
-- Reference existing tests when asking for additions. "Follow the same style as the tests in `auth.test.js`" is more effective than describing the style from scratch. The AI will pick up on naming conventions, assertion patterns, and import styles from the example.
-- If the first result isn't right, iterate. "These tests are too focused on implementation details. Rewrite them to only assert on the return values and thrown errors" is a valid follow-up. Refining through conversation often produces better results than trying to write the perfect prompt upfront.
-
-## Reviewing AI-Generated Tests
-
-AI-generated tests can look convincing at first glance but still have problems. Here's what to check before committing them.
-
-### Do the tests actually assert something meaningful?
-
-Watch for tests that call a function but only check that it doesn't throw, or tests that assert on the mock itself rather than the behavior. A test like this gives false confidence:
-
-```js
-test('creates a user', () => {
-  const user = createUser('Alice', 'alice@example.com')
-  expect(user).toBeDefined() // this passes for almost anything
-})
-```
-
-A better assertion checks the actual properties:
-
-```js
-test('creates a user with the correct fields', () => {
-  const user = createUser('Alice', 'alice@example.com')
-  expect(user).toMatchObject({
-    name: 'Alice',
-    email: 'alice@example.com',
-  })
-  expect(user.id).toBeTypeOf('string')
-})
-```
-
-### Are they testing behavior or implementation?
-
-AI tends to over-mock. If you see a test that mocks every dependency and then asserts that specific internal methods were called in a specific order, that's testing implementation details. These tests break every time you refactor, even if the behavior stays the same.
-
-Ask yourself: if someone changed the internals but the function still returned the correct result, would this test break? If yes, it's probably too coupled to the implementation. See [Testing in Practice](/guide/learn/testing-in-practice#what-to-test) for more on this distinction.
-
-### Do the tests actually run?
-
-Always run the tests before committing. AI-generated tests can have import errors, reference functions that don't exist, or use APIs incorrectly. A test that looks correct in a chat window might fail immediately when you actually execute it:
-
-```bash
-vitest run src/userService.test.js
-```
-
-### Are there real edge cases?
-
-AI tools tend to generate happy-path tests and skip the hard cases. After reviewing the generated tests, ask yourself: what happens with empty input? What about `null` or `undefined`? What if the network request fails? What if the list is empty?
-
-If these scenarios aren't covered, ask the AI to add them, or write them yourself.
-
-## Iterating on the Output
-
-Treat AI-generated tests as a first draft, not a finished product. A good workflow looks like:
-
-1. **Generate** the initial tests with a specific prompt and good context
-2. **Run** them immediately to catch errors
-3. **Review** each test for the issues described above
-4. **Ask for revisions** if entire sections need improvement ("these tests mock too much, rewrite them to test the actual integration with the database module")
-5. **Edit manually** for small fixes rather than re-prompting for every detail
-
-Over time, as the AI sees more of your codebase and test patterns, its output will improve. The earlier tests in your project set the pattern for everything that follows, so it's worth getting those right.
-
-## Common Pitfalls
-
-### Wrong APIs
-
-The most frequent issue with AI-generated Vitest tests is using the wrong API surface. AI models are trained on a lot of Jest code, so they sometimes generate `jest.fn()` instead of `vi.fn()`, or `jest.mock` instead of `vi.mock`. These will fail immediately.
-
-A related problem is imports: if your config has `globals: true`, the AI might still add `import { test, expect } from 'vitest'` (harmless but unnecessary), or the reverse, generating tests without imports when globals aren't enabled. If you keep seeing Jest APIs, point the AI to the [Vitest API reference](/api/vi) or include it in the context.
-
-### Mock Cleanup
-
-AI-generated tests often set up spies with `vi.spyOn` or replace modules with `vi.mock` but never restore them. If your config doesn't have [`restoreMocks: true`](/config/restoremocks), these mocks leak between tests and cause confusing failures. The easiest fix is enabling that config option globally.
-
-On a related note, AI tools tend to mock modules using string paths (`vi.mock('./module.js')`) when the `import()` form (`vi.mock(import('./module.js'))`) is preferable for type safety and automatic refactoring. See [Mock Functions](/guide/learn/mock-functions#mocking-modules) for why this matters.
-
-### Verbose Test Names
-
-AI tends to produce names like "should correctly return the formatted price string when given a valid positive number and a supported currency code." These are hard to scan when you have dozens of tests. Shorter names that describe the behavior work better: "formats USD prices", "throws for negative amounts", "returns empty array when no items match."
-
-### Watch Mode
-
-Vitest runs in watch mode by default, waiting for file changes and re-running tests interactively. Vitest tries to detect CI and non-interactive or agent environments and disable watch mode automatically, but this detection can be fragile.
-
-When telling an AI agent to run tests, always use `vitest run` or `vitest --no-watch` to ensure the process exits after the tests finish.