@vitest-agent/mcp 1.0.0 → 1.0.1

package/public/vendor/vitest-docs/guide/profiling-test-performance.md

@@ -0,0 +1,243 @@
+# Profiling Test Performance
+
+When you run Vitest it reports multiple time metrics of your tests:
+
+> ```bash
+> RUN  v2.1.1 /x/vitest/examples/profiling
+>
+> ✓ test/prime-number.test.ts (1) 4517ms
+>   ✓ generate prime number 4517ms
+>
+> Test Files  1 passed (1)
+>      Tests  1 passed (1)
+>   Start at  09:32:53
+>   Duration  4.80s (transform 44ms, setup 0ms, import 35ms, tests 4.52s, environment 0ms)
+>   # Time metrics ^^
+> ```
+
+- Transform: How much time was spent transforming the files. See [File Transform](#file-transform).
+- Setup: Time spent for running the [`setupFiles`](/config/setupfiles) files.
+- Import: Time it took to import your test files and their dependencies. This also includes the time spent collecting all tests. Note that this doesn't include dynamic imports inside of tests.
+- Tests: Time spent for actually running the test cases.
+- Environment: Time spent for setting up the test [`environment`](/config/environment), for example JSDOM.
+
+## Test Runner
+
+In cases where your test execution time is high, you can generate a profile of the test runner. See NodeJS documentation for following options:
+
+- [`--cpu-prof`](https://nodejs.org/api/cli.html#--cpu-prof)
+- [`--heap-prof`](https://nodejs.org/api/cli.html#--heap-prof)
+- [`--prof`](https://nodejs.org/api/cli.html#--prof)
+
+:::warning
+The `--prof` option does not work with `pool: 'threads'` due to `node:worker_threads` limitations.
+:::
+
+To pass these options to Vitest's test runner, define `execArgv` in your Vitest configuration:
+
+```ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    fileParallelism: false,
+    execArgv: [
+      '--cpu-prof',
+      '--cpu-prof-dir=test-runner-profile',
+      '--heap-prof',
+      '--heap-prof-dir=test-runner-profile'
+    ],
+  },
+})
+```
+
+After the tests have run there should be a `test-runner-profile/*.cpuprofile` and `test-runner-profile/*.heapprofile` files generated. See [Inspecting profiling records](#inspecting-profiling-records) for instructions how to analyze these files.
+
+See [Profiling | Examples](https://github.com/vitest-dev/vitest/tree/main/examples/profiling) for example.
+
+## Main Thread
+
+Profiling main thread is useful for debugging Vitest's Vite usage and [`globalSetup`](/config/globalsetup) files.
+This is also where your Vite plugins are running.
+
+:::tip
+See [Performance | Vite](https://vitejs.dev/guide/performance.html) for more tips about Vite specific profiling.
+
+We recommend [`vite-plugin-inspect`](https://github.com/antfu-collective/vite-plugin-inspect) for profiling your Vite plugin performance.
+:::
+
+To do this you'll need to pass arguments to the Node process that runs Vitest.
+
+```bash
+$ node --cpu-prof --cpu-prof-dir=main-profile ./node_modules/vitest/vitest.mjs --run
+#      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^                                  ^^^^^
+#               NodeJS arguments                                           Vitest arguments
+```
+
+After the tests have run there should be a `main-profile/*.cpuprofile` file generated. See [Inspecting profiling records](#inspecting-profiling-records) for instructions how to analyze these files.
+
+## File Transform
+
+This profiling strategy is a good way to identify unnecessary transforms caused by [barrel files](https://vitejs.dev/guide/performance.html#avoid-barrel-files).
+If these logs contain files that should not be loaded when your test is run, you might have barrel files that are importing files unnecessarily.
+
+You can also use [Vitest UI](/guide/ui) to debug slowness caused by barrel file.
+The example below shows how importing files without barrel file reduces amount of transformed files by ~85%.
+
+::: code-group
+``` [File tree]
+├── src
+│   └── utils
+│       ├── currency.ts
+│       ├── formatters.ts  <-- File to test
+│       ├── index.ts
+│       ├── location.ts
+│       ├── math.ts
+│       ├── time.ts
+│       └── users.ts
+├── test
+│   └── formatters.test.ts
+└── vitest.config.ts
+```
+```ts [example.test.ts]
+import { expect, test } from 'vitest'
+import { formatter } from '../src/utils' // [!code --]
+import { formatter } from '../src/utils/formatters' // [!code ++]
+
+test('formatter works', () => {
+  expect(formatter).not.toThrow()
+})
+```
+:::
+
+<img src="/module-graph-barrel-file.png" alt="Vitest UI demonstrating barrel file issues" />
+
+To see how files are transformed, you can open the "Module Info" view in the UI:
+
+<img alt="The module info view for an inlined module" img-light src="/ui/light-module-info.png">
+<img alt="The module info view for an inlined module" img-dark src="/ui/dark-module-info.png">
+
+## File Import
+
+Some modules just take a long time to load. To identify which modules are the slowest, enable [`experimental.importDurations`](/config/experimental#experimental-importdurations) in your configuration:
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    experimental: {
+      importDurations: {
+        print: true,
+      },
+    },
+  },
+})
+```
+
+This will print a breakdown of the slowest imports after your tests finish:
+
+```bash
+Import Duration Breakdown (Top 10)
+
+Module                      Self     Total
+my-test.test.ts              5ms    620ms [████████████████████]
+date-fns/index.js          500ms    500ms [████████████████░░░░] # [!code error]
+src/utils/helpers.ts        10ms    120ms [████████░░░░░░░░░░░░]
+```
+
+You can also use `--experimental.importDurations.print` from the CLI without changing your configuration:
+
+```bash
+vitest --experimental.importDurations.print
+```
+
+Once you've identified the slow modules, there are several strategies to speed up imports:
+
+### Use Specific Entry Points
+
+Many libraries ship multiple entry points. Importing the main entry point (which is often a [barrel file](https://vitejs.dev/guide/performance.html#avoid-barrel-files)) can pull in far more code than you need.
+
+For example, `date-fns` re-exports hundreds of functions from its main entry point. Instead of importing from the top-level module, import directly from the specific function:
+
+```ts
+import { format } from 'date-fns' // [!code --]
+import { format } from 'date-fns/format' // [!code ++]
+```
+
+### Use `resolve.alias` to Redirect Imports
+
+If a dependency doesn't provide granular entry points, or if third-party code imports the heavy entry point, you can use [`resolve.alias`](https://vite.dev/config/shared-options#resolve-alias) to redirect imports to a lighter alternative:
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  resolve: {
+    alias: [
+      {
+        find: /^date-fns$/,
+        replacement: join(dirname(require.resolve('date-fns/package.json')), 'index.cjs'),
+      },
+    ]
+  },
+})
+```
+
+### Use the Dependency Optimizer
+
+Vitest can bundle external libraries into a single file using [`deps.optimizer`](/config/deps#deps-optimizer), which reduces the overhead of importing packages with many internal modules:
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    deps: {
+      optimizer: {
+        ssr: {
+          enabled: true,
+          include: ['date-fns'],
+        },
+      },
+    },
+  },
+})
+```
+
+This is especially effective for UI libraries and packages with deep import trees. Use `optimizer.ssr` for `node`/`edge` environments and `optimizer.client` for `jsdom`/`happy-dom` environments.
+
+## Code Coverage
+
+If code coverage generation is slow on your project you can use `DEBUG=vitest:coverage` environment variable to enable performance logging.
+
+```bash
+$ DEBUG=vitest:coverage vitest --run --coverage
+
+ RUN  v3.1.1 /x/vitest-example
+
+  vitest:coverage Reading coverage results 2/2
+  vitest:coverage Converting 1/2
+  vitest:coverage 4 ms /x/src/multiply.ts
+  vitest:coverage Converting 2/2
+  vitest:coverage 552 ms /x/src/add.ts
+  vitest:coverage Uncovered files 1/2
+  vitest:coverage File "/x/src/large-file.ts" is taking longer than 3s # [!code error]
+  vitest:coverage 3027 ms /x/src/large-file.ts
+  vitest:coverage Uncovered files 2/2
+  vitest:coverage 4 ms /x/src/untested-file.ts
+  vitest:coverage Generate coverage total time 3521 ms
+```
+
+This profiling approach is great for detecting large files that are accidentally picked by coverage providers.
+For example if your configuration is accidentally including large built minified Javascript files in code coverage, they should appear in logs.
+In these cases you might want to adjust your [`coverage.include`](/config/coverage#coverage-include) and [`coverage.exclude`](/config/coverage#coverage-exclude) options.
+
+## Inspecting Profiling Records
+
+You can inspect the contents of `*.cpuprofile` and `*.heapprofile` with various tools. See list below for examples.
+
+- [Speedscope](https://www.speedscope.app/)
+- [Performance Profiling JavaScript in Visual Studio Code](https://code.visualstudio.com/docs/nodejs/profiling#_analyzing-a-profile)
+- [Profile Node.js performance with the Performance panel | developer.chrome.com](https://developer.chrome.com/docs/devtools/performance/nodejs#analyze)
+- [Memory panel overview | developer.chrome.com](https://developer.chrome.com/docs/devtools/memory-problems/heap-snapshots#view_snapshots)

package/public/vendor/vitest-docs/guide/projects.md

@@ -0,0 +1,291 @@
+# Test Projects
+
+::: tip Sample Project
+
+[GitHub](https://github.com/vitest-dev/vitest/tree/main/examples/projects) - [Play Online](https://stackblitz.com/fork/github/vitest-dev/vitest/tree/main/examples/projects?initialPath=__vitest__/)
+
+:::
+
+::: warning
+This feature is also known as a `workspace`. The `workspace` is deprecated since 3.2 and replaced with the `projects` configuration. They are functionally the same.
+:::
+
+Vitest provides a way to define multiple project configurations within a single Vitest process. This feature is particularly useful for monorepo setups but can also be used to run tests with different configurations, such as `resolve.alias`, `plugins`, or `test.browser` and more.
+
+## Defining Projects
+
+You can define projects in your root [config](/config/):
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    projects: ['packages/*'],
+  },
+})
+```
+
+Project configurations are inlined configs, files, or glob patterns referencing your projects. For example, if you have a folder named `packages` that contains your projects, you can define an array in your root Vitest config:
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    projects: ['packages/*'],
+  },
+})
+```
+
+Vitest will treat every folder in `packages` as a separate project even if it doesn't have a config file inside. If a project entry resolves to a file (either from a glob pattern or a direct file path), Vitest will validate that the name either:
+
+- starts with `vitest.config` or `vite.config` (for example, `vitest.config.unit.ts`)
+- or matches `vitest.<name>.config.*` / `vite.<name>.config.*`, where `<name>` can contain letters, numbers, `_`, and `-`
+
+For example, these config files are valid:
+
+- `vitest.config.ts`
+- `vite.config.js`
+- `vitest.unit.config.ts`
+- `vitest.e2e-node.config.ts`
+- `vite.e2e.config.js`
+- `vitest.config.unit.js`
+- `vite.config.e2e.js`
+
+To exclude folders and files, you can use the negation pattern:
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    // include all folders inside "packages" except "excluded"
+    projects: [
+      'packages/*',
+      '!packages/excluded'
+    ],
+  },
+})
+```
+
+If you have a nested structure where some folders need to be projects, but other folders have their own subfolders, you have to use brackets to avoid matching the parent folder:
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+
+// For example, this will create projects:
+// packages/a
+// packages/b
+// packages/business/c
+// packages/business/d
+// Notice that "packages/business" is not a project itself
+
+export default defineConfig({
+  test: {
+    projects: [
+      // matches every folder inside "packages" except "business"
+      'packages/!(business)',
+      // matches every folder inside "packages/business"
+      'packages/business/*',
+    ],
+  },
+})
+```
+
+::: warning
+Vitest does not treat the root `vitest.config` file as a project unless it is explicitly specified in the configuration. Consequently, the root configuration will only influence global options such as `reporters` and `coverage`. Note that Vitest will always run certain plugin hooks, like `apply`, `config`, `configResolved` or `configureServer`, specified in the root config file. Vitest also uses the same plugins to execute global setups and custom coverage provider.
+:::
+
+You can also reference projects with their config files:
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    projects: ['packages/*/vitest.config.{e2e,unit}.ts'],
+  },
+})
+```
+
+This pattern will only include projects with a `vitest.config` file that contains `e2e` or `unit` before the extension.
+
+You can also define projects using inline configuration. The configuration supports both syntaxes simultaneously.
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    projects: [
+      // matches every folder and file inside the `packages` folder
+      'packages/*',
+      {
+        // add "extends: true" to inherit the options from the root config
+        extends: true,
+        test: {
+          include: ['tests/**/*.{browser}.test.{ts,js}'],
+          // it is recommended to define a name when using inline configs
+          name: 'happy-dom',
+          environment: 'happy-dom',
+        }
+      },
+      {
+        test: {
+          include: ['tests/**/*.{node}.test.{ts,js}'],
+          // color of the name label can be changed
+          name: { label: 'node', color: 'green' },
+          environment: 'node',
+        }
+      }
+    ]
+  }
+})
+```
+
+::: warning
+All projects must have unique names; otherwise, Vitest will throw an error. If a name is not provided in the inline configuration, Vitest will assign a number. For project configurations defined with glob syntax, Vitest will default to using the "name" property in the nearest `package.json` file or, if none exists, the folder name.
+:::
+
+Projects do not support all configuration properties. For better type safety, use the `defineProject` method instead of `defineConfig` within project configuration files:
+
+```ts twoslash [packages/a/vitest.config.ts]
+// @errors: 2769
+import { defineProject } from 'vitest/config'
+
+export default defineProject({
+  test: {
+    environment: 'jsdom',
+    // "reporters" is not supported in a project config,
+    // so it will show an error
+    reporters: ['json']
+  }
+})
+```
+
+## Running Tests
+
+To run tests, define a script in your root `package.json`:
+
+```json [package.json]
+{
+  "scripts": {
+    "test": "vitest"
+  }
+}
+```
+
+Now tests can be run using your package manager:
+
+::: code-group
+```bash [npm]
+npm run test
+```
+```bash [yarn]
+yarn test
+```
+```bash [pnpm]
+pnpm run test
+```
+```bash [bun]
+bun run test
+```
+:::
+
+If you need to run tests only inside a single project, use the `--project` CLI option:
+
+::: code-group
+```bash [npm]
+npm run test --project e2e
+```
+```bash [yarn]
+yarn test --project e2e
+```
+```bash [pnpm]
+pnpm run test --project e2e
+```
+```bash [bun]
+bun run test --project e2e
+```
+:::
+
+::: tip
+CLI option `--project` can be used multiple times to filter out several projects:
+
+::: code-group
+```bash [npm]
+npm run test --project e2e --project unit
+```
+```bash [yarn]
+yarn test --project e2e --project unit
+```
+```bash [pnpm]
+pnpm run test --project e2e --project unit
+```
+```bash [bun]
+bun run test --project e2e --project unit
+```
+:::
+
+## Configuration
+
+None of the configuration options are inherited from the root-level config file. You can create a shared config file and merge it with the project config yourself:
+
+```ts [packages/a/vitest.config.ts]
+import { defineProject, mergeConfig } from 'vitest/config'
+import configShared from '../vitest.shared.js'
+
+export default mergeConfig(
+  configShared,
+  defineProject({
+    test: {
+      environment: 'jsdom',
+    }
+  })
+)
+```
+
+Additionally, you can use the `extends` option to inherit from your root-level configuration. All options will be merged.
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    pool: 'threads',
+    projects: [
+      {
+        // will inherit options from this config like plugins and pool
+        extends: true,
+        test: {
+          name: 'unit',
+          include: ['**/*.unit.test.ts'],
+        },
+      },
+      {
+        // won't inherit any options from this config
+        // this is the default behaviour
+        extends: false,
+        test: {
+          name: 'integration',
+          include: ['**/*.integration.test.ts'],
+        },
+      },
+    ],
+  },
+})
+```
+
+::: danger Unsupported Options
+Some of the configuration options are not allowed in a project config. Most notably:
+
+- `coverage`: coverage is done for the whole process
+- `reporters`: only root-level reporters can be supported
+- `resolveSnapshotPath`: only root-level resolver is respected
+- all other options that don't affect test runners
+
+All configuration options that are not supported inside a project configuration are marked with a <CRoot /> icon next to their name. They can only be defined once in the root config file.
+:::

package/public/vendor/vitest-docs/guide/recipes.md

@@ -0,0 +1,59 @@
+# Recipes
+
+## Disabling Isolation for Specific Test Files Only
+
+You can speed up your test run by disabling isolation for specific set of files by specifying `isolate` per `projects` entries:
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    projects: [
+      {
+        test: {
+          // Non-isolated unit tests
+          name: 'Unit tests',
+          isolate: false,
+          exclude: ['**.integration.test.ts'],
+        },
+      },
+      {
+        test: {
+          // Isolated integration tests
+          name: 'Integration tests',
+          include: ['**.integration.test.ts'],
+        },
+      },
+    ],
+  },
+})
+```
+
+## Parallel and Sequential Test Files
+
+You can split test files into parallel and sequential groups by using `projects` option:
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    projects: [
+      {
+        test: {
+          name: 'Parallel',
+          exclude: ['**.sequential.test.ts'],
+        },
+      },
+      {
+        test: {
+          name: 'Sequential',
+          include: ['**.sequential.test.ts'],
+          fileParallelism: false,
+        },
+      },
+    ],
+  },
+})
+```