vitest-dev · sheremet-va · Apr 8, 2026 · Apr 7, 2026 · Apr 7, 2026 · Apr 7, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -70,6 +70,14 @@ Add a `.npmrc` file with following line next to the `package.json`:
 VITEST_MODULE_DIRECTORIES=/node_modules/,/packages/
 ```
 
+## Using Unreleased Commits
+
+Each commit on the main branch and PRs with a `cr-tracked` label are published to [pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new). You can install a specific commit with:
+
+```bash
+npm i https://pkg.pr.new/vitest@{commit}
+```
+
 ## Pull Request Guidelines
 
 - Checkout a topic branch from a base branch, e.g. `main`, and merge back against that branch.

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -721,6 +721,57 @@ export default ({ mode }: { mode: string }) => {
               },
             ],
           },
+          {
+            text: 'Learn',
+            collapsed: false,
+            items: [
+              {
+                text: 'Writing Tests',
+                link: '/guide/learn/writing-tests',
+                docFooterText: 'Writing Tests | Learn',
+              },
+              {
+                text: 'Using Matchers',
+                link: '/guide/learn/matchers',
+                docFooterText: 'Using Matchers | Learn',
+              },
+              {
+                text: 'Testing Async Code',
+                link: '/guide/learn/async',
+                docFooterText: 'Testing Async Code | Learn',
+              },
+              {
+                text: 'Setup and Teardown',
+                link: '/guide/learn/setup-teardown',
+                docFooterText: 'Setup and Teardown | Learn',
+              },
+              {
+                text: 'Mock Functions',
+                link: '/guide/learn/mock-functions',
+                docFooterText: 'Mock Functions | Learn',
+              },
+              {
+                text: 'Snapshot Testing',
+                link: '/guide/learn/snapshots',
+                docFooterText: 'Snapshot Testing | Learn',
+              },
+              {
+                text: 'Testing in Practice',
+                link: '/guide/learn/testing-in-practice',
+                docFooterText: 'Testing in Practice | Learn',
+              },
+              {
+                text: 'Debugging Tests',
+                link: '/guide/learn/debugging-tests',
+                docFooterText: 'Debugging Tests | Learn',
+              },
+              {
+                text: 'Writing Tests with AI',
+                link: '/guide/learn/writing-tests-with-ai',
+                docFooterText: 'Writing Tests with AI | Learn',
+              },
+            ],
+          },
           {
             text: 'Browser Mode',
             collapsed: false,
@@ -795,35 +846,35 @@ export default ({ mode }: { mode: string }) => {
                 collapsed: true,
                 items: [
                   {
-                    text: 'Mocking Dates',
+                    text: 'Dates',
                     link: '/guide/mocking/dates',
                   },
                   {
-                    text: 'Mocking Functions',
+                    text: 'Functions',
                     link: '/guide/mocking/functions',
                   },
                   {
-                    text: 'Mocking Globals',
+                    text: 'Globals',
                     link: '/guide/mocking/globals',
                   },
                   {
-                    text: 'Mocking Modules',
+                    text: 'Modules',
                     link: '/guide/mocking/modules',
                   },
                   {
-                    text: 'Mocking the File System',
+                    text: 'File System',
                     link: '/guide/mocking/file-system',
                   },
                   {
-                    text: 'Mocking Requests',
+                    text: 'Requests',
                     link: '/guide/mocking/requests',
                   },
                   {
-                    text: 'Mocking Timers',
+                    text: 'Timers',
                     link: '/guide/mocking/timers',
                   },
                   {
-                    text: 'Mocking Classes',
+                    text: 'Classes',
                     link: '/guide/mocking/classes',
                   },
                 ],

diff --git a/docs/config/index.md b/docs/config/index.md
@@ -80,4 +80,10 @@ export default defineConfig(configEnv => mergeConfig(
 
 Since Vitest uses Vite config, you can also use any configuration option from [Vite](https://vitejs.dev/config/). For example, `define` to define global variables, or `resolve.alias` to define aliases - these options should be defined on the top level, _not_ within a `test` property.
 
+## Automatic Dependency Installation
+
+Vitest will prompt you to install certain dependencies if they are not already installed. You can disable this behavior by setting the `VITEST_SKIP_INSTALL_CHECKS=1` environment variable.
+
+## Config Options
+
 Configuration options that are not supported inside a [project](/guide/projects) config have <CRoot /> icon next to them. This means they can only be set in the root Vitest config.
diff --git a/docs/guide/features.md b/docs/guide/features.md
@@ -14,11 +14,15 @@ import FeaturesList from '../.vitepress/components/FeaturesList.vue'
 <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](/guide/#configuring-vitest).
+Learn more at [Configuring Vitest](/config/).
 
 ## Watch Mode
 

diff --git a/docs/guide/index.md b/docs/guide/index.md
@@ -1,5 +1,8 @@
 ---
 title: Getting Started | Guide
+next:
+  text: Writing Tests
+  link: /guide/learn/writing-tests
 ---
 
 # Getting Started
@@ -92,136 +95,13 @@ Test Files  1 passed (1)
 If you are using Bun as your package manager, make sure to use `bun run test` command instead of `bun test`, otherwise Bun will run its own test runner.
 :::
 
-Learn more about the usage of Vitest, see the [API](/api/test) section.
+Your first test is passing! Continue to [Writing Tests](/guide/learn/writing-tests) to learn about organizing tests, reading test output, and the core testing patterns you'll use every day.
 
-## Configuring Vitest
-
-One of the main advantages of Vitest is its unified configuration with Vite. If present, `vitest` will read your root `vite.config.ts` to match with the plugins and setup as your Vite app. For example, your Vite [resolve.alias](https://vitejs.dev/config/shared-options.html#resolve-alias) and [plugins](https://vitejs.dev/guide/using-plugins.html) configuration will work out-of-the-box. If you want a different configuration during testing, you can:
-
-- Create `vitest.config.ts`, which will have the higher priority
-- Pass `--config` option to CLI, e.g. `vitest --config ./path/to/vitest.config.ts`
-- Use `process.env.VITEST` or `mode` property on `defineConfig` (will be set to `test` if not overridden) to conditionally apply different configuration in `vite.config.ts`. Note that like any other environment variable, `VITEST` is also exposed on `import.meta.env` in your tests
-
-Vitest supports the same extensions for your configuration file as Vite does: `.js`, `.mjs`, `.cjs`, `.ts`, `.cts`, `.mts`. Vitest does not support `.json` extension.
-
-If you are not using Vite as your build tool, you can configure Vitest using the `test` property in your config file:
-
-```ts [vitest.config.ts]
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    // ...
-  },
-})
-```
-
-::: tip
-Even if you do not use Vite yourself, Vitest relies heavily on it for its transformation pipeline. For that reason, you can also configure any property described in [Vite documentation](https://vitejs.dev/config/).
-:::
+To run tests once without watching for file changes, use `vitest run`. You can also pass additional flags like `--reporter` or `--coverage`. For a full list of CLI options, run `npx vitest --help` or see the [CLI guide](/guide/cli).
 
-If you are already using Vite, add `test` property in your Vite config. You'll also need to add a reference to Vitest types using a [triple slash directive](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html#-reference-types-) at the top of your config file.
-
-```ts [vite.config.ts]
-/// <reference types="vitest/config" />
-import { defineConfig } from 'vite'
-
-export default defineConfig({
-  test: {
-    // ...
-  },
-})
-```
-
-See the list of config options in the [Config Reference](../config/)
-
-::: warning
-If you decide to have two separate config files for Vite and Vitest, make sure to define the same Vite options in your Vitest config file since it will override your Vite file, not extend it. You can also use `mergeConfig` method from `vite` or `vitest/config` entries to merge Vite config with Vitest config:
-
-:::code-group
-```ts [vitest.config.mjs]
-import { defineConfig, mergeConfig } from 'vitest/config'
-import viteConfig from './vite.config.mjs'
-
-export default mergeConfig(viteConfig, defineConfig({
-  test: {
-    // ...
-  },
-}))
-```
-
-```ts [vite.config.mjs]
-import { defineConfig } from 'vite'
-import Vue from '@vitejs/plugin-vue'
-
-export default defineConfig({
-  plugins: [Vue()],
-})
-```
-
-However, we recommend using the same file for both Vite and Vitest, instead of creating two separate files.
-:::
-
-## Projects Support
-
-Run different project configurations inside the same project with [Test Projects](/guide/projects). You can define a list of files and folders that define your projects in `vitest.config` file.
-
-```ts [vitest.config.ts]
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    projects: [
-      // you can use a list of glob patterns to define your projects
-      // Vitest expects a list of config files
-      // or directories where there is a config file
-      'packages/*',
-      'tests/*/vitest.config.{e2e,unit}.ts',
-      // you can even run the same tests,
-      // but with different configs in the same "vitest" process
-      {
-        test: {
-          name: 'happy-dom',
-          root: './shared_tests',
-          environment: 'happy-dom',
-          setupFiles: ['./setup.happy-dom.ts'],
-        },
-      },
-      {
-        test: {
-          name: 'node',
-          root: './shared_tests',
-          environment: 'node',
-          setupFiles: ['./setup.node.ts'],
-        },
-      },
-    ],
-  },
-})
-```
-
-## Command Line Interface
-
-In a project where Vitest is installed, you can use the `vitest` binary in your npm scripts, or run it directly with `npx vitest`. Here are the default npm scripts in a scaffolded Vitest project:
-
-<!-- prettier-ignore -->
-```json [package.json]
-{
-  "scripts": {
-    "test": "vitest",
-    "coverage": "vitest run --coverage"
-  }
-}
-```
-
-To run tests once without watching for file changes, use `vitest run`.
-You can specify additional CLI options like `--port` or `--https`. For a full list of CLI options, run `npx vitest --help` in your project.
-
-Learn more about the [Command Line Interface](/guide/cli)
-
-## Automatic Dependency Installation
+## Configuring Vitest
 
-Vitest will prompt you to install certain dependencies if they are not already installed. You can disable this behavior by setting the `VITEST_SKIP_INSTALL_CHECKS=1` environment variable.
+Vitest reads your `vite.config.*` by default, so your existing Vite plugins and configuration work out-of-the-box. You can also create a dedicated `vitest.config.*` for test-specific settings. See the [Config Reference](/config/) for details.
 
 ## IDE Integrations
 
@@ -242,61 +122,14 @@ Learn more about [IDE Integrations](/guide/ide)
 | `vue` | [GitHub](https://github.com/vitest-tests/browser-examples/tree/main/examples/vue) | [Play Online](https://stackblitz.com/fork/github/vitest-tests/browser-examples/tree/main/examples/vue?initialPath=__vitest__/) |
 | `marko` | [GitHub](https://github.com/vitest-tests/browser-examples/tree/main/examples/marko) | [Play Online](https://stackblitz.com/fork/github/vitest-tests/browser-examples/tree/main/examples/marko?initialPath=__vitest__/) |
 | `preact` | [GitHub](https://github.com/vitest-tests/browser-examples/tree/main/examples/preact) | [Play Online](https://stackblitz.com/fork/github/vitest-tests/browser-examples/tree/main/examples/preact?initialPath=__vitest__/) |
-| `qwik`| [Github](https://github.com/vitest-tests/browser-examples/tree/main/examples/qwik) | [Play Online](https://stackblitz.com/fork/github/vitest-tests/browser-examples/tree/main/examples/qwik?initialPath=__vitest__/) |
+| `qwik` | [GitHub](https://github.com/vitest-tests/browser-examples/tree/main/examples/qwik) | [Play Online](https://stackblitz.com/fork/github/vitest-tests/browser-examples/tree/main/examples/qwik?initialPath=__vitest__/) |
 | `react` | [GitHub](https://github.com/vitest-tests/browser-examples/tree/main/examples/react) | [Play Online](https://stackblitz.com/fork/github/vitest-tests/browser-examples/tree/main/examples/react?initialPath=__vitest__/) |
 | `solid` | [GitHub](https://github.com/vitest-tests/browser-examples/tree/main/examples/solid) | [Play Online](https://stackblitz.com/fork/github/vitest-tests/browser-examples/tree/main/examples/solid?initialPath=__vitest__/) |
 | `svelte` | [GitHub](https://github.com/vitest-tests/browser-examples/tree/main/examples/svelte) | [Play Online](https://stackblitz.com/fork/github/vitest-tests/browser-examples/tree/main/examples/svelte?initialPath=__vitest__/) |
 | `profiling` | [GitHub](https://github.com/vitest-dev/vitest/tree/main/examples/profiling) | Not Available |
 | `typecheck` | [GitHub](https://github.com/vitest-dev/vitest/tree/main/examples/typecheck) | [Play Online](https://stackblitz.com/fork/github/vitest-dev/vitest/tree/main/examples/typecheck?initialPath=__vitest__/) |
 | `projects` | [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__/) |
 
-## Projects using Vitest
-
-- [unocss](https://github.com/unocss/unocss)
-- [unplugin-auto-import](https://github.com/antfu/unplugin-auto-import)
-- [unplugin-vue-components](https://github.com/antfu/unplugin-vue-components)
-- [vue](https://github.com/vuejs/core)
-- [vite](https://github.com/vitejs/vite)
-- [vitesse](https://github.com/antfu/vitesse)
-- [vitesse-lite](https://github.com/antfu/vitesse-lite)
-- [fluent-vue](https://github.com/demivan/fluent-vue)
-- [vueuse](https://github.com/vueuse/vueuse)
-- [milkdown](https://github.com/Saul-Mirone/milkdown)
-- [gridjs-svelte](https://github.com/iamyuu/gridjs-svelte)
-- [spring-easing](https://github.com/okikio/spring-easing)
-- [bytemd](https://github.com/bytedance/bytemd)
-- [faker](https://github.com/faker-js/faker)
-- [million](https://github.com/aidenybai/million)
-- [Vitamin](https://github.com/wtchnm/Vitamin)
-- [neodrag](https://github.com/PuruVJ/neodrag)
-- [svelte-multiselect](https://github.com/janosh/svelte-multiselect)
-- [iconify](https://github.com/iconify/iconify)
-- [tdesign-vue-next](https://github.com/Tencent/tdesign-vue-next)
-- [cz-git](https://github.com/Zhengqbbb/cz-git)
-
-<!--
-For contributors:
-We no longer accept new entries to this list a this moment.
-Thanks for choosing Vitest!
--->
-
-## Using Unreleased Commits
-
-Each commit on main branch and a PR with a `cr-tracked` label are published to [pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new). You can install it by `npm i https://pkg.pr.new/vitest@{commit}`.
-
-If you want to test your own modification locally, you can build and link it yourself ([pnpm](https://pnpm.io/) is required):
-
-```bash
-git clone https://github.com/vitest-dev/vitest.git
-cd vitest
-pnpm install
-cd packages/vitest
-pnpm run build
-pnpm link --global # you can use your preferred package manager for this step
-```
-
-Then go to the project where you are using Vitest and run `pnpm link --global vitest` (or the package manager that you used to link `vitest` globally).
-
 ## Community
 
 If you have questions or need help, reach out to the community at [Discord](https://chat.vitest.dev) and [GitHub Discussions](https://github.com/vitest-dev/vitest/discussions).