@vitest-agent/mcp 1.1.0 → 1.3.0

package/vendor/vitest-docs/guide/environment.md

@@ -1,101 +0,0 @@
-# Test Environment
-
-Vitest provides [`environment`](/config/environment) option to run code inside a specific environment. You can modify how environment behaves with [`environmentOptions`](/config/environmentoptions) option.
-
-By default, you can use these environments:
-
-- `node` is default environment
-- `jsdom` emulates browser environment by providing Browser API, uses [`jsdom`](https://github.com/jsdom/jsdom) package
-- `happy-dom` emulates browser environment by providing Browser API, and considered to be faster than jsdom, but lacks some API, uses [`happy-dom`](https://github.com/capricorn86/happy-dom) package
-- `edge-runtime` emulates Vercel's [edge-runtime](https://edge-runtime.vercel.app/), uses [`@edge-runtime/vm`](https://npmx.dev/package/@edge-runtime/vm) package
-
-::: info
-When using `jsdom` or `happy-dom` environments, Vitest follows the same rules that Vite does when importing [CSS](https://vitejs.dev/guide/features.html#css) and [assets](https://vitejs.dev/guide/features.html#static-assets). If importing external dependency fails with `unknown extension .css` error, you need to inline the whole import chain manually by adding all packages to [`server.deps.inline`](/config/server#inline). For example, if the error happens in `package-3` in this import chain: `source code -> package-1 -> package-2 -> package-3`, you need to add all three packages to `server.deps.inline`.
-
-The `require` of CSS and assets inside the external dependencies are resolved automatically.
-:::
-
-::: warning
-"Environments" exist only when running tests in Node.js.
-
-`browser` is not considered an environment in Vitest. If you wish to run part of your tests using [Browser Mode](/guide/browser/), you can create a [test project](/guide/browser/#projects-config).
-:::
-
-## Environments for Specific Files
-
-When setting `environment` option in your config, it will apply to all the test files in your project. To have more fine-grained control, you can use control comments to specify environment for specific files. Control comments are comments that start with `@vitest-environment` and are followed by the environment name:
-
-```ts
-// @vitest-environment jsdom
-
-import { expect, test } from 'vitest'
-
-test('test', () => {
-  expect(typeof window).not.toBe('undefined')
-})
-```
-
-## Custom Environment
-
-You can create your own package to extend Vitest environment. To do so, create package with the name `vitest-environment-${name}` or specify a path to a valid JS/TS file. That package should export an object with the shape of `Environment`:
-
-```ts
-import type { Environment } from 'vitest/runtime'
-
-export default <Environment>{
-  name: 'custom',
-  viteEnvironment: 'ssr',
-  // optional - only if you support "vmForks" or "vmThreads" pools
-  async setupVM() {
-    const vm = await import('node:vm')
-    const context = vm.createContext()
-    return {
-      getVmContext() {
-        return context
-      },
-      teardown() {
-        // called after all tests with this env have been run
-      }
-    }
-  },
-  setup() {
-    // custom setup
-    return {
-      teardown() {
-        // called after all tests with this env have been run
-      }
-    }
-  }
-}
-```
-
-::: warning
-Vitest requires `viteEnvironment` option on environment object (fallbacks to the Vitest environment name by default). It should be equal to `ssr`, `client` or any custom [Vite environment](https://vite.dev/guide/api-environment) name. This value determines which environment is used to process file.
-:::
-
-You also have access to default Vitest environments through `vitest/runtime` entry:
-
-```ts
-import { builtinEnvironments, populateGlobal } from 'vitest/runtime'
-
-console.log(builtinEnvironments) // { jsdom, happy-dom, node, edge-runtime }
-```
-
-Vitest also provides `populateGlobal` utility function, which can be used to move properties from object into the global namespace:
-
-```ts
-interface PopulateOptions {
-  // should non-class functions be bind to the global namespace
-  bindFunctions?: boolean
-}
-
-interface PopulateResult {
-  // a list of all keys that were copied, even if value doesn't exist on original object
-  keys: Set<string>
-  // a map of original object that might have been overridden with keys
-  // you can return these values inside `teardown` function
-  originals: Map<string | symbol, any>
-}
-
-export function populateGlobal(global: any, original: any, options: PopulateOptions): PopulateResult
-```

package/vendor/vitest-docs/guide/extending-matchers.md

@@ -1,160 +0,0 @@
-# Extending Matchers
-
-Since Vitest is compatible with both Chai and Jest, you can use either the [`chai.use`](https://www.chaijs.com/guide/plugins/) API or `expect.extend`, whichever you prefer.
-
-This guide will explore extending matchers with `expect.extend`. If you are interested in Chai's API, check [their guide](https://www.chaijs.com/guide/plugins/).
-
-To extend default matchers, call `expect.extend` with an object containing your matchers.
-
-```ts
-expect.extend({
-  toBeFoo(received, expected) {
-    const { isNot } = this
-    return {
-      // do not alter your "pass" based on isNot. Vitest does it for you
-      pass: received === 'foo',
-      message: () => `${received} is${isNot ? ' not' : ''} foo`
-    }
-  }
-})
-```
-
-If you are using TypeScript, you can extend default `Matchers` interface in an ambient declaration file (e.g: `vitest.d.ts`) with the code below:
-
-```ts
-import 'vitest'
-
-declare module 'vitest' {
-  interface Matchers<T = any> {
-    toBeFoo: () => R
-  }
-}
-```
-
-::: tip
-Importing `vitest` makes TypeScript think this is an ES module file, type declaration won't work without it.
-:::
-
-Extending the `Matchers` interface will add a type to `expect.extend`, `expect().*`, and `expect.*` methods at the same time.
-
-::: warning
-Don't forget to include the ambient declaration file in your `tsconfig.json`.
-:::
-
-The return value of a matcher should be compatible with the following interface:
-
-```ts
-interface MatcherResult {
-  pass: boolean
-  message: () => string
-  // If you pass these, they will automatically appear inside a diff when
-  // the matcher does not pass, so you don't need to print the diff yourself
-  actual?: unknown
-  expected?: unknown
-}
-```
-
-::: warning
-If you create an asynchronous matcher, don't forget to `await` the result (`await expect('foo').toBeFoo()`) in the test itself:
-
-```ts
-expect.extend({
-  async toBeAsyncAssertion() {
-    // ...
-  }
-})
-
-await expect().toBeAsyncAssertion()
-```
-:::
-
-The first argument inside a matcher's function is the received value (the one inside `expect(received)`). The rest are arguments passed directly to the matcher. Since version 4.1, Vitest exposes several types that can be used by your custom matcher:
-
-```ts
-import type {
-  // the function type
-  Matcher,
-  // the return value
-  MatcherResult,
-  // state available as `this`
-  MatcherState,
-} from 'vitest'
-import { expect } from 'vitest'
-
-// a simple matcher, using "function" to have access to "this"
-const customMatcher: Matcher = function (received) {
-  // ...
-}
-
-// a matcher with arguments
-const customMatcher: Matcher<MatcherState, [arg1: unknown, arg2: unknown]> = function (received, arg1, arg2) {
-  // ...
-}
-
-// a matcher with custom annotations
-function customMatcher(this: MatcherState, received: unknown, arg1: unknown, arg2: unknown): MatcherResult {
-  // ...
-  return {
-    pass: false,
-    message: () => 'something went wrong!',
-  }
-}
-
-expect.extend({ customMatcher })
-```
-
-::: tip
-To build custom **snapshot matchers** (wrappers around `toMatchSnapshot()` / `toMatchInlineSnapshot()` / `toMatchFileSnapshot()`), use `Snapshots` exported from `vitest`. See [Custom Snapshot Matchers](/guide/snapshot#custom-snapshot-matchers).
-:::
-
-Matcher function has access to `this` context with the following properties:
-
-## `isNot`
-
-Returns true, if matcher was called on `not` (`expect(received).not.toBeFoo()`). You do not need to respect it, Vitest will reverse the value of `pass` automatically.
-
-## `promise`
-
-If matcher was called on `resolved/rejected`, this value will contain the name of modifier. Otherwise, it will be an empty string.
-
-## `equals`
-
-This is a utility function that allows you to compare two values. It will return `true` if values are equal, `false` otherwise. This function is used internally for almost every matcher. It supports objects with asymmetric matchers by default.
-
-## `utils`
-
-This contains a set of utility functions that you can use to display messages.
-
-`this` context also contains information about the current test. You can also get it by calling `expect.getState()`. The most useful properties are:
-
-## `currentTestName`
-
-Full name of the current test (including describe block).
-
-## `task` <Advanced /> <Version>4.1.0</Version> {#task}
-
-Contains a reference to [the `Test` runner task](/api/advanced/runner#tasks) when available.
-
-::: warning
-When using the global `expect` with concurrent tests, `this.task` is `undefined`. Use `context.expect` instead to ensure `task` is available in custom matchers.
-:::
-
-## `testPath`
-
-File path to the current test.
-
-## `environment`
-
-The name of the current [`environment`](/config/environment) (for example, `jsdom`).
-
-## `soft`
-
-Was assertion called as a [`soft`](/api/expect#soft) one. You don't need to respect it, Vitest will always catch the error.
-
-## `assertion` <Advanced /> <Version type="experimental">4.1.4</Version> {#assertion}
-
-The underlying [Chai assertion](https://www.chaijs.com/guide/plugins/) object. This is the same instance that Chai plugins receive, giving you access to Chai's flag system and chainable methods. This can be useful for building custom matchers that need to interact with Chai's internals.
-
-::: tip
-These are not all of the available properties, only the most useful ones. The other state values are used by Vitest internally.
-:::

package/vendor/vitest-docs/guide/features.md

@@ -1,310 +0,0 @@
-# Features
-
-<script setup>
-import FeaturesList from '../.vitepress/components/FeaturesList.vue'
-</script>
-
-<FeaturesList class="!gap-1 text-lg" />
-
-<div h-2 />
-<CourseLink href="https://vueschool.io/lessons/your-first-test?friend=vueuse">Learn how to write your first test by Video</CourseLink>
-
-::: tip
-This page is a high-level overview of Vitest's capabilities. If you're new to Vitest, we recommend reading the [Learn](/guide/learn/writing-tests) tutorial first for a hands-on introduction.
-:::
-
-## Shared Config between Test, Dev and Build
-
-Vite's config, transformers, resolvers, and plugins. Use the same setup from your app to run the tests.
-
-Learn more at [Configuring Vitest](/config/).
-
-## Watch Mode
-
-```bash
-$ vitest
-```
-
-When you modify your source code or the test files, Vitest smartly searches the module graph and only reruns the related tests, just like how HMR works in Vite!
-
-`vitest` starts in `watch mode` **by default in development environment** and `run mode` in CI environment (when `process.env.CI` presents) smartly. You can use `vitest watch` or `vitest run` to explicitly specify the desired mode.
-
-Start Vitest with the `--standalone` flag to keep it running in the background. It won't run any tests until they change. Vitest will not run tests if the source code is changed until the test that imports the source has been run
-
-## Common Web Idioms Out-Of-The-Box
-
-Out-of-the-box ES Module / TypeScript / JSX support / PostCSS
-
-## Threads
-
-By default Vitest runs test files in [multiple processes](/guide/parallelism) using [`node:child_process`](https://nodejs.org/api/child_process.html), allowing tests to run simultaneously. If you want to speed up your test suite even further, consider enabling `--pool=threads` to run tests using [`node:worker_threads`](https://nodejs.org/api/worker_threads.html) (beware that some packages might not work with this setup).
-To run tests in a single thread or process, see [`fileParallelism`](/config/fileparallelism).
-
-Vitest also isolates each file's environment so env mutations in one file don't affect others. Isolation can be disabled by passing `--no-isolate` to the CLI (trading correctness for run performance).
-
-## Test Filtering
-
-Vitest provides many ways to narrow down the tests to run in order to speed up testing so you can focus on development.
-
-Learn more about [Test Filtering](/guide/filtering).
-
-## Running Tests Concurrently
-
-Use `.concurrent` in consecutive tests to start them in parallel.
-
-```ts
-import { describe, it } from 'vitest'
-
-// The two tests marked with concurrent will be started in parallel
-describe('suite', () => {
-  it('serial test', async () => { /* ... */ })
-  it.concurrent('concurrent test 1', async ({ expect }) => { /* ... */ })
-  it.concurrent('concurrent test 2', async ({ expect }) => { /* ... */ })
-})
-```
-
-If you use `.concurrent` on a suite, every test in it will be started in parallel.
-
-```ts
-import { describe, it } from 'vitest'
-
-// All tests within this suite will be started in parallel
-describe.concurrent('suite', () => {
-  it('concurrent test 1', async ({ expect }) => { /* ... */ })
-  it('concurrent test 2', async ({ expect }) => { /* ... */ })
-  it.concurrent('concurrent test 3', async ({ expect }) => { /* ... */ })
-})
-```
-
-You can also use `.skip`, `.only`, and `.todo` with concurrent suites and tests. Read more in the [API Reference](/api/test#test-concurrent).
-
-::: warning
-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.
-:::
-
-## Snapshot
-
-[Jest-compatible](https://jestjs.io/docs/snapshot-testing) snapshot support.
-
-```ts
-import { expect, it } from 'vitest'
-
-it('renders correctly', () => {
-  const result = render()
-  expect(result).toMatchSnapshot()
-})
-```
-
-Learn more at [Snapshot](/guide/snapshot).
-
-## Chai and Jest `expect` Compatibility
-
-[Chai](https://www.chaijs.com/) is built-in for assertions with [Jest `expect`](https://jestjs.io/docs/expect)-compatible APIs.
-
-Notice that if you are using third-party libraries that add matchers, setting [`test.globals`](/config/globals) to `true` will provide better compatibility.
-
-## Mocking
-
-Vitest provides `jest`-compatible APIs on `vi` object.
-
-```ts
-import { expect, vi } from 'vitest'
-
-const fn = vi.fn()
-
-fn('hello', 1)
-
-expect(vi.isMockFunction(fn)).toBe(true)
-expect(fn.mock.calls[0]).toEqual(['hello', 1])
-
-fn.mockImplementation((arg: string) => arg)
-
-fn('world', 2)
-
-expect(fn.mock.results[1].value).toBe('world')
-```
-
-Vitest supports both [happy-dom](https://github.com/capricorn86/happy-dom) or [jsdom](https://github.com/jsdom/jsdom) for mocking DOM and browser APIs. They don't come with Vitest, you will need to install them separately:
-
-::: code-group
-```bash [happy-dom]
-$ npm i -D happy-dom
-```
-```bash [jsdom]
-$ npm i -D jsdom
-```
-:::
-
-After that, change the `environment` option in your config file:
-
-```ts [vitest.config.ts]
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    environment: 'happy-dom', // or 'jsdom', 'node'
-  },
-})
-```
-
-Learn more at [Mocking](/guide/mocking).
-
-## Coverage
-
-Vitest supports Native code coverage via [`v8`](https://v8.dev/blog/javascript-code-coverage) and instrumented code coverage via [`istanbul`](https://istanbul.js.org/).
-
-```json [package.json]
-{
-  "scripts": {
-    "test": "vitest",
-    "coverage": "vitest run --coverage"
-  }
-}
-```
-
-Learn more at [Coverage](/guide/coverage).
-
-## In-Source Testing
-
-Vitest also provides a way to run tests within your source code along with the implementation, similar to [Rust's module tests](https://doc.rust-lang.org/book/ch11-03-test-organization.html#the-tests-module-and-cfgtest).
-
-This makes the tests share the same closure as the implementations and able to test against private states without exporting. Meanwhile, it also brings the feedback loop closer for development.
-
-```ts [src/index.ts]
-// the implementation
-export function add(...args: number[]): number {
-  return args.reduce((a, b) => a + b, 0)
-}
-
-// in-source test suites
-if (import.meta.vitest) {
-  const { it, expect } = import.meta.vitest
-  it('add', () => {
-    expect(add()).toBe(0)
-    expect(add(1)).toBe(1)
-    expect(add(1, 2, 3)).toBe(6)
-  })
-}
-```
-
-Learn more at [In-source testing](/guide/in-source).
-
-## Benchmarking <Badge type="warning">Experimental</Badge> {#benchmarking}
-
-You can run benchmark tests with [`bench`](/api/test#bench) function via [Tinybench](https://github.com/tinylibs/tinybench) to compare performance results.
-
-```ts [sort.bench.ts]
-import { bench, describe } from 'vitest'
-
-describe('sort', () => {
-  bench('normal', () => {
-    const x = [1, 5, 4, 2, 3]
-    x.sort((a, b) => {
-      return a - b
-    })
-  })
-
-  bench('reverse', () => {
-    const x = [1, 5, 4, 2, 3]
-    x.reverse().sort((a, b) => {
-      return a - b
-    })
-  })
-})
-```
-
-<img alt="Benchmark report" img-dark src="https://github.com/vitest-dev/vitest/assets/4232207/6f0383ea-38ba-4f14-8a05-ab243afea01d">
-<img alt="Benchmark report" img-light src="https://github.com/vitest-dev/vitest/assets/4232207/efbcb427-ecf1-4882-88de-210cd73415f6">
-
-## Type Testing <Badge type="warning">Experimental</Badge> {#type-testing}
-
-You can [write tests](/guide/testing-types) to catch type regressions. Vitest comes with [`expect-type`](https://github.com/mmkal/expect-type) package to provide you with a similar and easy to understand API.
-
-```ts [types.test-d.ts]
-import { assertType, expectTypeOf, test } from 'vitest'
-import { mount } from './mount.js'
-
-test('my types work properly', () => {
-  expectTypeOf(mount).toBeFunction()
-  expectTypeOf(mount).parameter(0).toExtend<{ name: string }>()
-
-  // @ts-expect-error name is a string
-  assertType(mount({ name: 42 }))
-})
-```
-
-## Sharding
-
-Run tests on different machines using [`--shard`](/guide/cli#shard) and [`--reporter=blob`](/guide/reporters#blob-reporter) flags.
-All test and coverage results can be merged at the end of your CI pipeline using `--merge-reports` command:
-
-```bash
-vitest --shard=1/2 --reporter=blob --coverage
-vitest --shard=2/2 --reporter=blob --coverage
-vitest --merge-reports --reporter=junit --coverage
-```
-
-See [`Improving Performance | Sharding`](/guide/improving-performance#sharding) for more information.
-
-## Environment Variables
-
-Vitest exclusively autoloads environment variables prefixed with `VITE_` from `.env` files to maintain compatibility with frontend-related tests, adhering to [Vite's established convention](https://vitejs.dev/guide/env-and-mode.html#env-files). To load every environmental variable from `.env` files anyway, you can use `loadEnv` method imported from `vite`:
-
-```ts [vitest.config.ts]
-import { loadEnv } from 'vite'
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig(({ mode }) => ({
-  test: {
-    // mode defines what ".env.{mode}" file to choose if exists
-    env: loadEnv(mode, process.cwd(), ''),
-  },
-}))
-```
-
-## Unhandled Errors
-
-By default, Vitest catches and reports all [unhandled rejections](https://developer.mozilla.org/en-US/docs/Web/API/Window/unhandledrejection_event), [uncaught exceptions](https://nodejs.org/api/process.html#event-uncaughtexception) (in Node.js) and [error](https://developer.mozilla.org/en-US/docs/Web/API/Window/error_event) events (in the [browser](/guide/browser/)).
-
-You can disable this behaviour by catching them manually. Vitest assumes the callback is handled by you and won't report the error.
-
-::: code-group
-```ts [setup.node.js]
-// in Node.js
-process.on('unhandledRejection', () => {
-  // your own handler
-})
-
-process.on('uncaughtException', () => {
-  // your own handler
-})
-```
-```ts [setup.browser.js]
-// in the browser
-window.addEventListener('error', () => {
-  // your own handler
-})
-
-window.addEventListener('unhandledrejection', () => {
-  // your own handler
-})
-```
-:::
-
-Alternatively, you can also ignore reported errors with a [`dangerouslyIgnoreUnhandledErrors`](/config/dangerouslyignoreunhandlederrors) option. Vitest will still report them, but they won't affect the test result (exit code won't be changed).
-
-If you need to test that error was not caught, you can create a test that looks like this:
-
-```ts
-test('my function throws uncaught error', async ({ onTestFinished }) => {
-  const unhandledRejectionListener = vi.fn()
-  process.on('unhandledRejection', unhandledRejectionListener)
-  onTestFinished(() => {
-    process.off('unhandledRejection', unhandledRejectionListener)
-  })
-
-  callMyFunctionThatRejectsError()
-
-  await expect.poll(unhandledRejectionListener).toHaveBeenCalled()
-})
-```