@vitest-agent/mcp 1.1.0 → 1.3.0

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

@@ -1,239 +0,0 @@
-# Mocking
-
-::: tip
-New to mocking? Start with the [Mock Functions](/guide/learn/mock-functions) tutorial for a hands-on introduction to `vi.fn`, `vi.spyOn`, and `vi.mock`.
-:::
-
-When writing tests it's only a matter of time before you need to create a "fake" version of an internal — or external — service. This is commonly referred to as **mocking**. Vitest provides utility functions to help you out through its `vi` helper. You can import it from `vitest` or access it globally if [`global` configuration](/config/globals) is enabled.
-
-::: warning
-Always remember to clear or restore mocks before or after each test run to undo mock state changes between runs! See [`mockReset`](/api/mock#mockreset) docs for more info.
-:::
-
-If you are not familiar with `vi.fn`, `vi.mock` or `vi.spyOn` methods, check the [API section](/api/vi) first.
-
-Vitest has a comprehensive list of guides regarding mocking:
-
-- [Mocking Classes](/guide/mocking/classes.md)
-- [Mocking Dates](/guide/mocking/dates.md)
-- [Mocking the File System](/guide/mocking/file-system.md)
-- [Mocking Functions](/guide/mocking/functions.md)
-- [Mocking Globals](/guide/mocking/globals.md)
-- [Mocking Modules](/guide/mocking/modules.md)
-- [Mocking Requests](/guide/mocking/requests.md)
-- [Mocking Timers](/guide/mocking/timers.md)
-
-For a simpler and quicker way to get started with mocking, you can check the Cheat Sheet below.
-
-## Cheat Sheet
-
-I want to…
-
-### Mock exported variables
-```js [example.js]
-export const getter = 'variable'
-```
-```ts [example.test.ts]
-import * as exports from './example.js'
-
-vi.spyOn(exports, 'getter', 'get').mockReturnValue('mocked')
-```
-
-::: warning
-This will not work in the Browser Mode. For a workaround, see [Limitations](/guide/browser/#spying-on-module-exports).
-:::
-
-### Mock an exported function
-
-1. Example with `vi.mock`:
-
-::: warning
-Don't forget that a `vi.mock` call is hoisted to top of the file. It will always be executed before all imports.
-:::
-
-```ts [example.js]
-export function method() {}
-```
-```ts
-import { method } from './example.js'
-
-vi.mock('./example.js', () => ({
-  method: vi.fn()
-}))
-```
-
-2. Example with `vi.spyOn`:
-```ts
-import * as exports from './example.js'
-
-vi.spyOn(exports, 'method').mockImplementation(() => {})
-```
-
-::: warning
-`vi.spyOn` example will not work in the Browser Mode. For a workaround, see [Limitations](/guide/browser/#spying-on-module-exports).
-:::
-
-### Mock an exported class implementation
-
-1. Example with a fake `class`:
-```ts [example.js]
-export class SomeClass {}
-```
-```ts
-import { SomeClass } from './example.js'
-
-vi.mock(import('./example.js'), () => {
-  const SomeClass = vi.fn(class FakeClass {
-    someMethod = vi.fn()
-  })
-  return { SomeClass }
-})
-```
-
-2. Example with `vi.spyOn`:
-
-```ts
-import * as mod from './example.js'
-
-vi.spyOn(mod, 'SomeClass').mockImplementation(class FakeClass {
-  someMethod = vi.fn()
-})
-```
-
-::: warning
-`vi.spyOn` example will not work in the Browser Mode. For a workaround, see [Limitations](/guide/browser/#spying-on-module-exports).
-:::
-
-### Spy on an object returned from a function
-
-1. Example using cache:
-
-```ts [example.js]
-export function useObject() {
-  return { method: () => true }
-}
-```
-
-```ts [useObject.js]
-import { useObject } from './example.js'
-
-const obj = useObject()
-obj.method()
-```
-
-```ts [useObject.test.js]
-import { useObject } from './example.js'
-
-vi.mock(import('./example.js'), () => {
-  let _cache
-  const useObject = () => {
-    if (!_cache) {
-      _cache = {
-        method: vi.fn(),
-      }
-    }
-    // now every time that useObject() is called it will
-    // return the same object reference
-    return _cache
-  }
-  return { useObject }
-})
-
-const obj = useObject()
-// obj.method was called inside some-path
-expect(obj.method).toHaveBeenCalled()
-```
-
-### Mock part of a module
-
-```ts
-import { mocked, original } from './some-path.js'
-
-vi.mock(import('./some-path.js'), async (importOriginal) => {
-  const mod = await importOriginal()
-  return {
-    ...mod,
-    mocked: vi.fn()
-  }
-})
-original() // has original behaviour
-mocked() // is a spy function
-```
-
-::: warning
-Don't forget that this only [mocks _external_ access](/guide/mocking/modules#mocking-modules-pitfalls). In this example, if `original` calls `mocked` internally, it will always call the function defined in the module, not in the mock factory.
-:::
-
-### Mock the current date
-
-To mock `Date`'s time, you can use `vi.setSystemTime` helper function. This value will **not** automatically reset between different tests.
-
-Beware that using `vi.useFakeTimers` also changes the `Date`'s time.
-
-```ts
-const mockDate = new Date(2022, 0, 1)
-vi.setSystemTime(mockDate)
-const now = new Date()
-expect(now.valueOf()).toBe(mockDate.valueOf())
-// reset mocked time
-vi.useRealTimers()
-```
-
-### Mock a global variable
-
-You can set global variable by assigning a value to `globalThis` or using [`vi.stubGlobal`](/api/vi#vi-stubglobal) helper. When using `vi.stubGlobal`, it will **not** automatically reset between different tests, unless you enable [`unstubGlobals`](/config/unstubglobals) config option or call [`vi.unstubAllGlobals`](/api/vi#vi-unstuballglobals).
-
-```ts
-vi.stubGlobal('__VERSION__', '1.0.0')
-expect(__VERSION__).toBe('1.0.0')
-```
-
-### Mock `import.meta.env`
-
-1. To change environmental variable, you can just assign a new value to it.
-
-::: warning
-The environmental variable value will **_not_** automatically reset between different tests.
-:::
-
-```ts
-import { beforeEach, expect, it } from 'vitest'
-
-// you can reset it in beforeEach hook manually
-const originalViteEnv = import.meta.env.VITE_ENV
-
-beforeEach(() => {
-  import.meta.env.VITE_ENV = originalViteEnv
-})
-
-it('changes value', () => {
-  import.meta.env.VITE_ENV = 'staging'
-  expect(import.meta.env.VITE_ENV).toBe('staging')
-})
-```
-
-2. If you want to automatically reset the value(s), you can use the `vi.stubEnv` helper with the [`unstubEnvs`](/config/unstubenvs) config option enabled (or call [`vi.unstubAllEnvs`](/api/vi#vi-unstuballenvs) manually in a `beforeEach` hook):
-
-```ts
-import { expect, it, vi } from 'vitest'
-
-// before running tests "VITE_ENV" is "test"
-import.meta.env.VITE_ENV === 'test'
-
-it('changes value', () => {
-  vi.stubEnv('VITE_ENV', 'staging')
-  expect(import.meta.env.VITE_ENV).toBe('staging')
-})
-
-it('the value is restored before running an other test', () => {
-  expect(import.meta.env.VITE_ENV).toBe('test')
-})
-```
-
-```ts [vitest.config.ts]
-export default defineConfig({
-  test: {
-    unstubEnvs: true,
-  },
-})
-```

package/vendor/vitest-docs/guide/open-telemetry.md

@@ -1,156 +0,0 @@
-# Open Telemetry Support <Experimental /> {#open-telemetry-support}
-
-::: tip FEEDBACK
-Please, leave feedback regarding this feature in a [GitHub Discussion](https://github.com/vitest-dev/vitest/discussions/9222).
-:::
-
-::: tip Example Project
-[GitHub](https://github.com/vitest-dev/vitest/tree/main/examples/opentelemetry)
-:::
-
-[OpenTelemetry](https://opentelemetry.io/) traces can be a useful tool to debug the performance and behavior of your application inside tests.
-
-If enabled, Vitest integration generates spans that are scoped to your test's worker.
-
-::: warning
-OpenTelemetry initialization increases the startup time of every test unless Vitest runs without [isolation](/config/isolate). You can see it as the `vitest.runtime.traces` span inside `vitest.worker.start`.
-:::
-
-To start using OpenTelemetry in Vitest, specify an SDK module path via [`experimental.openTelemetry.sdkPath`](/config/experimental#experimental-opentelemetry) and set `experimental.openTelemetry.enabled` to `true`. Vitest will automatically instrument the whole process and each individual test worker.
-
-Make sure to export the SDK as a default export, so that Vitest can flush the network requests before the process is closed. Note that Vitest doesn't automatically call `start`.
-
-## Quickstart
-
-Before previewing your application traces, install required packages and specify the path to your instrumentation file in the config.
-
-```shell
-npm i @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-proto
-```
-
-::: code-group
-```js{12} [otel.js]
-import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
-import { NodeSDK } from '@opentelemetry/sdk-node'
-
-const sdk = new NodeSDK({
-  serviceName: 'vitest',
-  traceExporter: new OTLPTraceExporter(),
-  instrumentations: [getNodeAutoInstrumentations()],
-})
-
-sdk.start()
-export default sdk
-```
-```js [vitest.config.js]
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    experimental: {
-      openTelemetry: {
-        enabled: true,
-        sdkPath: './otel.js',
-      },
-    },
-  },
-})
-```
-:::
-
-::: danger FAKE TIMERS
-If you are using fake timers, it is important to reset them before the test ends, otherwise traces might not be tracked properly.
-:::
-
-Vitest doesn't process the `sdkPath` module, so it is important that the SDK can be imported within your Node.js environment. It is ideal to use the `.js` extension for this file. Using another extension will slow down your tests and may require providing additional Node.js arguments.
-
-If you want to provide a TypeScript file, make sure to familiarize yourself with [TypeScript](https://nodejs.org/api/typescript.html#type-stripping) page in the Node.js documentation.
-
-## Custom Traces
-
-You can use the OpenTelemetry API yourself to track certain operations in your code. Custom traces automatically inherit the Vitest OpenTelemetry context:
-
-```ts
-import { trace } from '@opentelemetry/api'
-import { test } from 'vitest'
-import { db } from './src/db'
-
-const tracer = trace.getTracer('vitest')
-
-test('db connects properly', async () => {
-  // this is shown inside `vitest.test.runner.test.callback` span
-  await tracer.startActiveSpan('db.connect', () => db.connect())
-})
-```
-
-## Browser Mode
-
-When running tests in [browser mode](/guide/browser/), Vitest propagates trace context between Node.js and the browser. Node.js side traces (test orchestration, browser driver communication) are available without additional configuration.
-
-To capture traces from the browser runtime, provide a browser-compatible SDK via `browserSdkPath`:
-
-```shell
-npm i @opentelemetry/sdk-trace-web @opentelemetry/exporter-trace-otlp-proto
-```
-
-::: code-group
-```js [otel-browser.js]
-import {
-  BatchSpanProcessor,
-  WebTracerProvider,
-} from '@opentelemetry/sdk-trace-web'
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
-
-const provider = new WebTracerProvider({
-  spanProcessors: [
-    new BatchSpanProcessor(new OTLPTraceExporter()),
-  ],
-})
-
-provider.register()
-export default provider
-```
-```js [vitest.config.js]
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    browser: {
-      enabled: true,
-      provider: 'playwright',
-      instances: [{ browser: 'chromium' }],
-    },
-    experimental: {
-      openTelemetry: {
-        enabled: true,
-        sdkPath: './otel.js',
-        browserSdkPath: './otel-browser.js',
-      },
-    },
-  },
-})
-```
-:::
-
-::: warning ASYNC CONTEXT
-Unlike Node.js, browsers do not have automatic async context propagation. Vitest handles this internally for test execution, but custom spans in deeply nested async code may not propagate context automatically.
-:::
-
-## View Traces
-
-To generate traces, run Vitest as usual. You can run Vitest in either watch mode or run mode. Vitest will call `sdk.shutdown()` manually after everything is finished to make sure traces are handled properly.
-
-You can view traces using any of the open source or commercial products that support OpenTelemetry API. If you did not use OpenTelemetry before, we recommend starting with [Jaeger](https://www.jaegertracing.io/docs/2.11/getting-started/#all-in-one) because it is really easy to setup.
-
-<img src="/otel-jaeger.png" alt="an example of open telemetry result in jaeger" />
-
-## `@opentelemetry/api`
-
-Vitest declares `@opentelemetry/api` as an optional peer dependency, which it uses internally to generate spans. When trace collection is not enabled, Vitest will not attempt to use this dependency.
-
-When configuring Vitest to use OpenTelemetry, you will typically install `@opentelemetry/sdk-node`, which includes `@opentelemetry/api` as a transitive dependency, thereby satisfying Vitest's peer dependency requirement. If you encounter an error indicating that `@opentelemetry/api` cannot be found, this typically means trace collection has not been enabled. If the error persists after proper configuration, you may need to install `@opentelemetry/api` explicitly.
-
-## Inter-Process Context Propagation
-
-Vitest supports automatic context propagation from parent processes via the `TRACEPARENT` and `TRACESTATE` environment variables as defined in the [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/env-carriers.md). This is particularly useful when running Vitest as part of a larger distributed tracing system (e.g., CI/CD pipelines with OpenTelemetry instrumentation).

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

@@ -1,82 +0,0 @@
-# Parallelism
-
-Vitest has two levels of parallelism: it can run multiple *test files* at the same time, and within each file it can run multiple *tests* at the same time. Understanding the difference between the two is important because they work differently and have different trade-offs.
-
-## File Parallelism
-
-By default, Vitest runs test files in parallel across multiple workers. Each file gets its own isolated environment, so tests in different files can't interfere with each other.
-
-The mechanism Vitest uses to create workers depends on the configured [`pool`](/config/pool):
-
-- `forks` (the default) and `vmForks` run each file in a separate [child process](https://nodejs.org/api/child_process.html)
-- `threads` and `vmThreads` run each file in a separate [worker thread](https://nodejs.org/api/worker_threads.html)
-
-You can control how many workers run simultaneously with the [`maxWorkers`](/config/maxworkers) option. More workers means more files run in parallel, but also more memory and CPU usage. The right number depends on your machine and how heavy your tests are.
-
-For most projects, file parallelism is the single biggest factor in test suite speed. However, there are cases where you might want to disable it — for example, if your tests share an external resource like a database that can't handle concurrent access. You can set [`fileParallelism`](/config/fileparallelism) to `false` to run files one at a time.
-
-To learn more about tuning performance, see the [Performance Guide](/guide/improving-performance).
-
-## Test Parallelism
-
-Within a single file, Vitest runs tests sequentially by default. Tests execute in the order they are defined, one after another. This is the safest default because tests within a file often share setup and state through lifecycle hooks like `beforeEach`.
-
-If the tests in a file are independent, you can opt into running them concurrently with the [`concurrent`](/api/test#test-concurrent) modifier:
-
-```ts
-import { expect, test } from 'vitest'
-
-test.concurrent('fetches user profile', async () => {
-  const user = await fetchUser(1)
-  expect(user.name).toBe('Alice')
-})
-
-test.concurrent('fetches user posts', async () => {
-  const posts = await fetchPosts(1)
-  expect(posts).toHaveLength(3)
-})
-```
-
-When tests are marked as `concurrent`, Vitest groups them together and runs them with [`Promise.all`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all). The number of tests running at once is bounded by the [`maxConcurrency`](/config/maxconcurrency) option.
-
-::: tip When does `concurrent` actually help?
-Vitest doesn't create extra workers for concurrent tests — they all run in the same worker as the file they belong to. This means `concurrent` only speeds things up when your tests spend time *waiting* (on network requests, timers, file I/O, etc.). Purely synchronous tests won't benefit because they still block the single JavaScript thread:
-
-```ts
-// These run one after another despite `concurrent`,
-// because there is nothing to await
-test.concurrent('the first test', () => {
-  expect(1).toBe(1)
-})
-
-test.concurrent('the second test', () => {
-  expect(2).toBe(2)
-})
-```
-:::
-
-You can also apply `concurrent` to an entire suite:
-
-```ts
-import { describe, expect, test } from 'vitest'
-
-describe.concurrent('user API', () => {
-  test('fetches profile', async () => {
-    const user = await fetchUser(1)
-    expect(user.name).toBe('Alice')
-  })
-
-  test('fetches posts', async () => {
-    const posts = await fetchPosts(1)
-    expect(posts).toHaveLength(3)
-  })
-})
-```
-
-If you want *all* tests in your project to run concurrently by default, set [`sequence.concurrent`](/config/sequence#sequence-concurrent) to `true` in your config.
-
-### Hooks with Concurrent Tests
-
-When tests run concurrently, lifecycle hooks behave differently. `beforeAll` and `afterAll` still run once for the group, but `beforeEach` and `afterEach` run for each test — potentially at the same time, since the tests themselves overlap.
-
-The hook execution order is controlled by [`sequence.hooks`](/config/sequence#sequence-hooks). With `sequence.hooks: 'parallel'`, hooks are also bounded by the [`maxConcurrency`](/config/maxconcurrency) limit.