@vitest-agent/mcp 1.0.0 → 1.1.0

package/vendor/vitest-docs/api/browser/vue.md

@@ -0,0 +1,222 @@
+# vitest-browser-vue
+
+The community [`vitest-browser-vue`](https://npmx.dev/package/vitest-browser-vue) package renders [Vue](https://vuejs.org/) components in [Browser Mode](/guide/browser/).
+
+```ts
+import { render } from 'vitest-browser-vue'
+import { expect, test } from 'vitest'
+import Component from './Component.vue'
+
+test('counter button increments the count', async () => {
+  const screen = await render(Component, {
+    props: {
+      initialCount: 1,
+    }
+  })
+
+  await screen.getByRole('button', { name: 'Increment' }).click()
+
+  await expect.element(screen.getByText('Count is 2')).toBeVisible()
+})
+```
+
+::: warning
+This library takes inspiration from [`@testing-library/vue`](https://github.com/testing-library/vue-testing-library).
+
+If you have used `@testing-library/vue` in your tests before, you can keep using it, however the `vitest-browser-vue` package provides certain benefits unique to the Browser Mode that `@testing-library/vue` lacks:
+
+`vitest-browser-vue` returns APIs that interact well with built-in [locators](/api/browser/locators), [user events](/api/browser/interactivity) and [assertions](/api/browser/assertions): for example, Vitest will automatically retry the element until the assertion is successful, even if it was rerendered between the assertions.
+:::
+
+The package exposes two entry points: `vitest-browser-vue` and `vitest-browser-vue/pure`. They expose identical API, but the `pure` entry point doesn't add a handler to remove the component before the next test has started.
+
+## render
+
+```ts
+export function render(
+  component: Component,
+  options?: ComponentRenderOptions,
+): RenderResult & PromiseLike<RenderResult>
+```
+
+The `render` function records a `vue.render` trace mark, visible in the [Trace View](/guide/browser/trace-view).
+
+::: warning
+Synchronous usage of `render` is deprecated and will be removed in the next major version. Please always `await` the result:
+
+```ts
+const screen = render(Component) // [!code --]
+const screen = await render(Component) // [!code ++]
+```
+:::
+
+### Options
+
+The `render` function supports all [`mount` options](https://test-utils.vuejs.org/api/#mount) from `@vue/test-utils` (except `attachTo` - use `container` instead). In addition to them, there are also `container` and `baseElement`.
+
+#### container
+
+By default, Vitest will create a `div`, append it to `document.body`, and render your component there. If you provide your own `HTMLElement` container, it will not be appended automatically — you'll need to call `document.body.appendChild(container)` before `render`.
+
+For example, if you are unit testing a `tbody` element, it cannot be a child of a `div`. In this case, you can specify a `table` as the render container.
+
+```js
+const table = document.createElement('table')
+
+const { container } = await render(TableBody, {
+  props,
+  // ⚠️ appending the element to `body` manually before rendering
+  container: document.body.appendChild(table),
+})
+```
+
+#### baseElement
+
+If the `container` is specified, then this defaults to that, otherwise this defaults to `document.body`. This is used as the base element for the queries as well as what is printed when you use `debug()`.
+
+### Render Result
+
+In addition to documented return value, the `render` function also returns all available [locators](/api/browser/locators) relative to the [`baseElement`](#baseelement), including [custom ones](/api/browser/locators#custom-locators).
+
+```ts
+const screen = await render(TableBody, { props })
+
+await screen.getByRole('link', { name: 'Expand' }).click()
+```
+
+#### container
+
+The containing DOM node where your Vue component is rendered. This is a regular DOM node, so you technically could call `container.querySelector` etc. to inspect the children.
+
+:::danger
+If you find yourself using `container` to query for rendered elements then you should reconsider! The [locators](/api/browser/locators) are designed to be more resilient to changes that will be made to the component you're testing. Avoid using `container` to query for elements!
+:::
+
+#### baseElement
+
+The containing DOM node where your Vue component is rendered in the `container`. If you don't specify the `baseElement` in the options of render, it will default to `document.body`.
+
+This is useful when the component you want to test renders something outside the container `div`, e.g. when you want to snapshot test your portal component which renders its HTML directly in the body.
+
+:::tip
+The queries returned by the `render` looks into `baseElement`, so you can use queries to test your portal component without the `baseElement`.
+:::
+
+#### locator
+
+The [locator](/api/browser/locators) of your `container`. It is useful to use queries scoped only to your component, or pass it down to other assertions:
+
+```js
+import { render } from 'vitest-browser-vue'
+
+const { locator } = await render(NumberDisplay, {
+  props: { number: 2 }
+})
+
+await locator.getByRole('button').click()
+await expect.element(locator).toHaveTextContent('Hello World')
+```
+
+#### debug
+
+```ts
+function debug(
+  el?: HTMLElement | HTMLElement[] | Locator | Locator[],
+  maxLength?: number,
+  options?: PrettyDOMOptions,
+): void
+```
+
+This method is a shortcut for `console.log(prettyDOM(baseElement))`. It will print the DOM content of the container or specified elements to the console.
+
+#### rerender
+
+```ts
+function rerender(props: Partial<Props>): void & PromiseLike<void>
+```
+
+Also records a `vue.rerender` trace mark in the [Trace View](/guide/browser/trace-view).
+
+It is better if you test the component that's doing the prop updating to ensure that the props are being updated correctly to avoid relying on implementation details in your tests. That said, if you'd prefer to update the props of a rendered component in your test, this function can be used to update props of the rendered component.
+
+::: warning
+Synchronous usage of `rerender` is deprecated and will be removed in the next major version. Please always `await` the result.
+:::
+
+```js
+import { render } from 'vitest-browser-vue'
+
+const { rerender } = await render(NumberDisplay, { props: { number: 1 } })
+
+// re-render the same component with different props
+await rerender({ number: 2 })
+```
+
+#### unmount
+
+```ts
+function unmount(): void & PromiseLike<void>
+```
+
+This will cause the rendered component to be unmounted. Also records a `vue.unmount` trace mark in the [Trace View](/guide/browser/trace-view). This is useful for testing what happens when your component is removed from the page (like testing that you don't leave event handlers hanging around causing memory leaks).
+
+::: warning
+Synchronous usage of `unmount` is deprecated and will be removed in the next major version. Please always `await` the result.
+:::
+
+#### emitted
+
+```ts
+function emitted<T = unknown>(): Record<string, T[]>
+function emitted<T = unknown[]>(eventName: string): undefined | T[]
+```
+
+Returns the emitted events from the Component.
+
+::: warning
+Emitted values are an implementation detail not exposed directly to the user, so it is better to test how your emitted values are changing the displayed content by using [locators](/api/browser/locators) instead.
+:::
+
+## cleanup
+
+```ts
+export function cleanup(): void
+```
+
+Remove all components rendered with [`render`](#render).
+
+## Extend Queries
+
+To extend locator queries, see [`"Custom Locators"`](/api/browser/locators#custom-locators). For example, to make `render` return a new custom locator, define it using the `locators.extend` API:
+
+```js {5-7,12}
+import { locators } from 'vitest/browser'
+import { render } from 'vitest-browser-vue'
+
+locators.extend({
+  getByArticleTitle(title) {
+    return `[data-title="${title}"]`
+  },
+})
+
+const screen = await render(Component)
+await expect.element(
+  screen.getByArticleTitle('Hello World')
+).toBeVisible()
+```
+
+## Configuration
+
+You can configure [Vue Test Utils](https://test-utils.vuejs.org/api/#config) options by assigning properties to the `config` export (available in both `vitest-browser-vue` and `vitest-browser-vue/pure`):
+
+```js
+import { config } from 'vitest-browser-vue/pure'
+
+config.global.stubs.CustomComponent = {
+  template: '<div></div>',
+}
+```
+
+## See also
+
+- [Vue Testing Library documentation](https://testing-library.com/docs/vue-testing-library/intro)

package/vendor/vitest-docs/api/describe.md

@@ -0,0 +1,374 @@
+# describe
+
+- **Alias:** `suite`
+
+```ts
+function describe(
+  name: string | Function,
+  body?: () => unknown,
+  timeout?: number
+): void
+function describe(
+  name: string | Function,
+  options: SuiteOptions,
+  body?: () => unknown,
+): void
+```
+
+`describe` is used to group related tests and benchmarks into a suite. Suites help organize your test files by creating logical blocks, making test output easier to read and enabling shared setup/teardown through [lifecycle hooks](/api/hooks).
+
+When you use `test` in the top level of file, they are collected as part of the implicit suite for it. Using `describe` you can define a new suite in the current context, as a set of related tests or benchmarks and other nested suites.
+
+```ts [basic.spec.ts]
+import { describe, expect, test } from 'vitest'
+
+const person = {
+  isActive: true,
+  age: 32,
+}
+
+describe('person', () => {
+  test('person is defined', () => {
+    expect(person).toBeDefined()
+  })
+
+  test('is active', () => {
+    expect(person.isActive).toBeTruthy()
+  })
+
+  test('age limit', () => {
+    expect(person.age).toBeLessThanOrEqual(32)
+  })
+})
+```
+
+You can also nest `describe` blocks if you have a hierarchy of tests:
+
+```ts
+import { describe, expect, test } from 'vitest'
+
+function numberToCurrency(value: number | string) {
+  if (typeof value !== 'number') {
+    throw new TypeError('Value must be a number')
+  }
+
+  return value.toFixed(2).toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',')
+}
+
+describe('numberToCurrency', () => {
+  describe('given an invalid number', () => {
+    test('composed of non-numbers to throw error', () => {
+      expect(() => numberToCurrency('abc')).toThrow()
+    })
+  })
+
+  describe('given a valid number', () => {
+    test('returns the correct currency format', () => {
+      expect(numberToCurrency(10000)).toBe('10,000.00')
+    })
+  })
+})
+```
+
+## Test Options
+
+You can use [test options](/api/test#test-options) to apply configuration to every test inside a suite, including nested suites. This is useful when you want to set timeouts, retries, or other options for a group of related tests.
+
+```ts
+import { describe, test } from 'vitest'
+
+describe('slow tests', { timeout: 10_000 }, () => {
+  test('test 1', () => { /* ... */ })
+  test('test 2', () => { /* ... */ })
+
+  // nested suites also inherit the timeout
+  describe('nested', () => {
+    test('test 3', () => { /* ... */ })
+  })
+})
+```
+
+### `shuffle`
+
+- **Type:** `boolean`
+- **Default:** `false` (configured by [`sequence.shuffle`](/config/sequence#sequence-shuffle))
+- **Alias:** [`describe.shuffle`](#describe-shuffle)
+
+Run tests within the suite in random order. This option is inherited by nested suites.
+
+```ts
+import { describe, test } from 'vitest'
+
+describe('randomized tests', { shuffle: true }, () => {
+  test('test 1', () => { /* ... */ })
+  test('test 2', () => { /* ... */ })
+  test('test 3', () => { /* ... */ })
+})
+```
+
+## describe.skip
+
+- **Alias:** `suite.skip`
+
+Use `describe.skip` in a suite to avoid running a particular describe block.
+
+```ts
+import { assert, describe, test } from 'vitest'
+
+describe.skip('skipped suite', () => {
+  test('sqrt', () => {
+    // Suite skipped, no error
+    assert.equal(Math.sqrt(4), 3)
+  })
+})
+```
+
+## describe.skipIf
+
+- **Alias:** `suite.skipIf`
+
+In some cases, you might run suites multiple times with different environments, and some of the suites might be environment-specific. Instead of wrapping the suite with `if`, you can use `describe.skipIf` to skip the suite whenever the condition is truthy.
+
+```ts
+import { describe, test } from 'vitest'
+
+const isDev = process.env.NODE_ENV === 'development'
+
+describe.skipIf(isDev)('prod only test suite', () => {
+  // this test suite only runs in production
+})
+```
+
+## describe.runIf
+
+- **Alias:** `suite.runIf`
+
+Opposite of [describe.skipIf](#describe-skipif).
+
+```ts
+import { assert, describe, test } from 'vitest'
+
+const isDev = process.env.NODE_ENV === 'development'
+
+describe.runIf(isDev)('dev only test suite', () => {
+  // this test suite only runs in development
+})
+```
+
+## describe.only
+
+- **Alias:** `suite.only`
+
+Use `describe.only` to only run certain suites
+
+```ts
+import { assert, describe, test } from 'vitest'
+
+// Only this suite (and others marked with only) are run
+describe.only('suite', () => {
+  test('sqrt', () => {
+    assert.equal(Math.sqrt(4), 3)
+  })
+})
+
+describe('other suite', () => {
+  // ... will be skipped
+})
+```
+
+Sometimes it is very useful to run `only` tests in a certain file, ignoring all other tests from the whole test suite, which pollute the output.
+
+In order to do that, run `vitest` with specific file containing the tests in question:
+
+```shell
+vitest interesting.test.ts
+```
+
+## describe.concurrent
+
+- **Alias:** `suite.concurrent`
+
+`describe.concurrent` runs all inner suites and tests in parallel
+
+```ts
+import { describe, test } from 'vitest'
+
+// All suites and tests within this suite will be run in parallel
+describe.concurrent('suite', () => {
+  test('concurrent test 1', async () => { /* ... */ })
+  describe('concurrent suite 2', async () => {
+    test('concurrent test inner 1', async () => { /* ... */ })
+    test('concurrent test inner 2', async () => { /* ... */ })
+  })
+  test.concurrent('concurrent test 3', async () => { /* ... */ })
+})
+```
+
+`.skip`, `.only`, and `.todo` works with concurrent suites. All the following combinations are valid:
+
+```ts
+describe.concurrent(/* ... */)
+describe.skip.concurrent(/* ... */) // or describe.concurrent.skip(/* ... */)
+describe.only.concurrent(/* ... */) // or describe.concurrent.only(/* ... */)
+describe.todo.concurrent(/* ... */) // or describe.concurrent.todo(/* ... */)
+```
+
+When running concurrent tests, Snapshots and Assertions must use `expect` from the local [Test Context](/guide/test-context) to ensure the right test is detected.
+
+```ts
+describe.concurrent('suite', () => {
+  test('concurrent test 1', async ({ expect }) => {
+    expect(foo).toMatchSnapshot()
+  })
+  test('concurrent test 2', async ({ expect }) => {
+    expect(foo).toMatchSnapshot()
+  })
+})
+```
+
+## describe.sequential
+
+- **Alias:** `suite.sequential`
+
+`describe.sequential` in a suite marks every test as sequential. This is useful if you want to run tests in sequence within `describe.concurrent` or with the `--sequence.concurrent` command option.
+
+```ts
+import { describe, test } from 'vitest'
+
+describe.concurrent('suite', () => {
+  test('concurrent test 1', async () => { /* ... */ })
+  test('concurrent test 2', async () => { /* ... */ })
+
+  describe.sequential('', () => {
+    test('sequential test 1', async () => { /* ... */ })
+    test('sequential test 2', async () => { /* ... */ })
+  })
+})
+```
+
+## describe.shuffle
+
+- **Alias:** `suite.shuffle`
+
+Vitest provides a way to run all tests in random order via CLI flag [`--sequence.shuffle`](/guide/cli) or config option [`sequence.shuffle`](/config/sequence#sequence-shuffle), but if you want to have only part of your test suite to run tests in random order, you can mark it with this flag.
+
+```ts
+import { describe, test } from 'vitest'
+
+// or describe('suite', { shuffle: true }, ...)
+describe.shuffle('suite', () => {
+  test('random test 1', async () => { /* ... */ })
+  test('random test 2', async () => { /* ... */ })
+  test('random test 3', async () => { /* ... */ })
+
+  // `shuffle` is inherited
+  describe('still random', () => {
+    test('random 4.1', async () => { /* ... */ })
+    test('random 4.2', async () => { /* ... */ })
+  })
+
+  // disable shuffle inside
+  describe('not random', { shuffle: false }, () => {
+    test('in order 5.1', async () => { /* ... */ })
+    test('in order 5.2', async () => { /* ... */ })
+  })
+})
+// order depends on sequence.seed option in config (Date.now() by default)
+```
+
+`.skip`, `.only`, and `.todo` works with random suites.
+
+## describe.todo
+
+- **Alias:** `suite.todo`
+
+Use `describe.todo` to stub suites to be implemented later. An entry will be shown in the report for the tests so you know how many tests you still need to implement.
+
+```ts
+// An entry will be shown in the report for this suite
+describe.todo('unimplemented suite')
+```
+
+## describe.each
+
+- **Alias:** `suite.each`
+
+::: tip
+While `describe.each` is provided for Jest compatibility,
+Vitest also has [`describe.for`](#describe-for) which simplifies argument types and aligns with [`test.for`](/api/test#test-for).
+:::
+
+Use `describe.each` if you have more than one test that depends on the same data.
+
+```ts
+import { describe, expect, test } from 'vitest'
+
+describe.each([
+  { a: 1, b: 1, expected: 2 },
+  { a: 1, b: 2, expected: 3 },
+  { a: 2, b: 1, expected: 3 },
+])('describe object add($a, $b)', ({ a, b, expected }) => {
+  test(`returns ${expected}`, () => {
+    expect(a + b).toBe(expected)
+  })
+
+  test(`returned value not be greater than ${expected}`, () => {
+    expect(a + b).not.toBeGreaterThan(expected)
+  })
+
+  test(`returned value not be less than ${expected}`, () => {
+    expect(a + b).not.toBeLessThan(expected)
+  })
+})
+```
+
+* First row should be column names, separated by `|`;
+* One or more subsequent rows of data supplied as template literal expressions using `${value}` syntax.
+
+```ts
+import { describe, expect, test } from 'vitest'
+
+describe.each`
+  a               | b      | expected
+  ${1}            | ${1}   | ${2}
+  ${'a'}          | ${'b'} | ${'ab'}
+  ${[]}           | ${'b'} | ${'b'}
+  ${{}}           | ${'b'} | ${'[object Object]b'}
+  ${{ asd: 1 }}   | ${'b'} | ${'[object Object]b'}
+`('describe template string add($a, $b)', ({ a, b, expected }) => {
+  test(`returns ${expected}`, () => {
+    expect(a + b).toBe(expected)
+  })
+})
+```
+
+## describe.for
+
+- **Alias:** `suite.for`
+
+The difference from `describe.each` is how array case is provided in the arguments.
+Other non array case (including template string usage) works exactly same.
+
+```ts
+// `each` spreads array case
+describe.each([
+  [1, 1, 2],
+  [1, 2, 3],
+  [2, 1, 3],
+])('add(%i, %i) -> %i', (a, b, expected) => { // [!code --]
+  test('test', () => {
+    expect(a + b).toBe(expected)
+  })
+})
+
+// `for` doesn't spread array case
+describe.for([
+  [1, 1, 2],
+  [1, 2, 3],
+  [2, 1, 3],
+])('add(%i, %i) -> %i', ([a, b, expected]) => { // [!code ++]
+  test('test', () => {
+    expect(a + b).toBe(expected)
+  })
+})
+```