Merge branch 'main' into pretty-format-shadow-root

Author: wkillerud

.github/copilot-instructions.md

@@ -0,0 +1,11 @@
+# copilot-instructions.md
+
+This file provides guidance to Copilot Agent when working with code in this repository.
+
+## Codebase Overview
+
+Vitest is a next-generation testing framework powered by Vite. This is a monorepo using pnpm workspaces.
+
+## Essential references
+
+- Agent-specific guide: See [AGENTS.md](../AGENTS.md)

AGENTS.md

@@ -0,0 +1,144 @@
+# Vitest AI Agent Guide
+
+This document provides comprehensive information for AI agents working on the Vitest codebase.
+
+## Project Overview
+
+Vitest is a next-generation testing framework powered by Vite. This is a monorepo using pnpm workspaces with the following key characteristics:
+
+- **Language**: TypeScript/JavaScript (ESM-first)
+- **Package Manager**: pnpm (required)
+- **Node Version**: ^18.0.0 || >=20.0.0
+- **Build System**: Vite + Rollup
+- **Monorepo Structure**: 15+ packages in `packages/` directory
+
+## Setup and Development
+
+### Initial Setup
+1. Run `pnpm install` to install dependencies
+2. Run `pnpm build` to build all packages
+3. Install Playwright browsers when working with browser features: `npx playwright install --with-deps`
+
+### Key Scripts
+- `pnpm build` - Build all packages
+- `pnpm dev` - Watch mode for development
+- `pnpm lint` - Run ESLint
+- `pnpm lint:fix` - Fix linting issues automatically
+- `pnpm typecheck` - Run TypeScript type checking
+
+## Testing
+
+### Running Tests
+- **All tests**: `CI=true pnpm test:ci`
+- **Examples**: `CI=true pnpm test:examples`
+- **Specific test suite**: `CI=true cd test/<test-folder> && pnpm test <test-file>`
+- **Core directory test**: `CI=true pnpm test <test-file>` (for `test/core`)
+- **Browser tests**: `CI=true pnpm test:browser:playwright` or `CI=true pnpm test:browser:webdriverio`
+
+### Testing Utilities
+- **`runInlineTests`** from `test/test-utils/index.ts` - You must use this for complex file system setups (>1 file)
+- **`runVitest`** from `test/test-utils/index.ts` - You can use this to run Vitest programmatically
+- **No mocking policy** - You must never mock anything in tests
+
+## Project Structure
+
+### Core Packages (`packages/`)
+- `vitest` - Main testing framework
+- `vite-node` - Vite SSR runtime
+- `browser` - Browser testing support
+- `ui` - Web UI for test results
+- `runner` - Test runner core
+- `expect` - Assertion library
+- `spy` - Mocking and spying utilities
+- `snapshot` - Snapshot testing
+- `coverage-v8` / `coverage-istanbul` - Code coverage
+- `utils` - Shared utilities
+- `mocker` - Module mocking
+
+### Test Organization (`test/`)
+- `test/core` - Core functionality tests
+- `test/browser` - Browser-specific tests
+- Various test suites organized by feature
+
+### Important Directories
+- `docs/` - Documentation (Vite-powered)
+- `examples/` - Example projects and integrations
+- `scripts/` - Build and development scripts
+- `.github/` - GitHub Actions workflows
+- `patches/` - Package patches via pnpm
+
+## Code Style and Conventions
+
+### Formatting and Linting
+- **Always run** `pnpm lint:fix` after making changes
+- Fix non-auto-fixable errors manually
+
+### TypeScript
+- Strict TypeScript configuration
+- Use `pnpm typecheck` to verify types
+- Configuration files: `tsconfig.base.json`, `tsconfig.build.json`, `tsconfig.check.json`
+
+### Code Quality
+- ESM-first approach
+- Follow existing patterns in the codebase
+- Use utilities from `@vitest/utils/*` when available. Never import from `@vitest/utils` main entry point directly.
+
+## Common Workflows
+
+### Adding New Features
+1. Identify the appropriate package in `packages/`
+2. Follow existing code patterns
+3. Add tests using testing utilities
+4. Run `pnpm build && pnpm typecheck && pnpm lint:fix`
+5. Add tests with relevant test suites
+
+### Debugging
+- Use VS Code: `⇧⌘B` (Shift+Cmd+B) or `Ctrl+Shift+B` for dev tasks
+- Check `scripts/` directory for specialized development tools
+
+### Documentation
+- Main docs in `docs/` directory
+- Built with `pnpm docs:build`
+- Local dev server: `pnpm docs`
+
+## Dependencies and Tools
+
+### Key Dependencies
+- **Vite** - Build tool and dev server
+- **Rollup** - Bundler
+- **ESLint** - Linting
+- **TypeScript** - Type checking
+- **Playwright** - Browser testing
+- **Chai/Expect** - Assertions
+- **Tinypool** - Worker threading
+- **Tinybench** - Benchmarking
+
+### Development Tools
+- **tsx** - TypeScript execution
+- **ni/nr** - Package manager abstraction
+- **bumpp** - Version bumping
+- **changelogithub** - Changelog generation
+
+## Browser Testing
+- Two modes: Playwright and WebDriverIO
+- Separate test commands for each
+- Component testing supported (Vue, React, Svelte, Lit, Marko)
+
+## Performance Considerations
+- This is a performance-critical testing framework
+- Pay attention to import costs and bundle size
+- Use lazy loading where appropriate
+- Consider worker thread implications
+
+## Troubleshooting
+
+### Common Issues
+- Ensure pnpm is used (not npm/yarn)
+- Build before running tests
+- Check Node.js version compatibility
+- Playwright browsers must be installed for browser tests
+
+### Getting Help
+- Check existing issues and documentation
+- Review CONTRIBUTING.md for detailed guidelines
+- Follow patterns in existing code

CLAUDE.md

@@ -0,0 +1,11 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Codebase Overview
+
+Vitest is a next-generation testing framework powered by Vite. This is a monorepo using pnpm workspaces.
+
+## Essential references
+
+- Agent-specific guide: See [AGENTS.md](AGENTS.md)

docs/advanced/reporters.md

@@ -93,6 +93,7 @@ class MyReporter implements Reporter {
 6. `JUnitReporter`
 7. `TapFlatReporter`
 8. `HangingProcessReporter`
+9. `TreeReporter`
 
 ### Base Abstract reporters:
 

docs/config/index.md

@@ -328,7 +328,7 @@ TypeError: createAsyncThunk is not a function
 TypeError: default is not a function
 ```
 
-By default, Vitest assumes you are using a bundler to bypass this and will not fail, but you can disable this behaviour manually, if you code is not processed.
+By default, Vitest assumes you are using a bundler to bypass this and will not fail, but you can disable this behaviour manually, if your code is not processed.
 
 #### deps.moduleDirectories
 

docs/guide/cli-generated.md

@@ -89,7 +89,7 @@ Hide logs for skipped tests
 - **CLI:** `--reporter <name>`
 - **Config:** [reporters](/config/#reporters)
 
-Specify reporters (default, blob, verbose, dot, json, tap, tap-flat, junit, hanging-process, github-actions)
+Specify reporters (default, blob, verbose, dot, json, tap, tap-flat, junit, tree, hanging-process, github-actions)
 
 ### outputFile
 

docs/guide/migration.md

@@ -7,20 +7,6 @@ outline: deep
 
 ## Migrating to Vitest 4.0 {#vitest-4}
 
-### Removed `reporters: 'basic'`
-
-Basic reporter is removed as it is equal to:
-
-```ts
-export default defineConfig({
-  test: {
-    reporters: [
-      ['default', { summary: false }]
-    ]
-  }
-})
-```
-
 ### V8 Code Coverage Major Changes
 
 Vitest's V8 code coverage provider is now using more accurate coverage result remapping logic.
@@ -291,6 +277,32 @@ exports[`custom element with shadow root 1`] = `
   </div>
 </body>"
 `
+
+### Reporter Updates
+
+Reporter APIs `onCollected`, `onSpecsCollected`, `onPathsCollected`, `onTaskUpdate` and `onFinished` were removed. See [`Reporters API`](/advanced/api/reporters) for new alternatives. The new APIs were introduced in Vitest `v3.0.0`.
+
+The `basic` reporter was removed as it is equal to:
+
+```ts
+export default defineConfig({
+  test: {
+    reporters: [
+      ['default', { summary: false }]
+    ]
+  }
+})
+```
+
+The [`verbose`](/guide/reporters#verbose-reporter) reporter now prints test cases as a flat list. To revert to the previous behaviour, use `--reporter=tree`:
+
+```ts
+export default defineConfig({
+  test: {
+    reporters: ['verbose'], // [!code --]
+    reporters: ['tree'], // [!code ++]
+  }
+})
 ```
 
 ### Deprecated APIs are Removed
@@ -299,7 +311,6 @@ Vitest 4.0 removes some deprecated APIs, including:
 
 - `poolMatchGlobs` config option. Use [`projects`](/guide/projects) instead.
 - `environmentMatchGlobs` config option. Use [`projects`](/guide/projects) instead.
-- Reporter APIs `onCollected`, `onSpecsCollected`, `onPathsCollected`, `onTaskUpdate` and `onFinished`. See [`Reporters API`](/advanced/api/reporters) for new alternatives. These APIs were introduced in Vitest `v3.0.0`.
 - `deps.external`, `deps.inline`, `deps.fallbackCJS` config options. Use `server.deps.external`, `server.deps.inline`, or `server.deps.fallbackCJS` instead.
 - `browser.testerScripts` config option. Use [`browser.testerHtmlPath`](/guide/browser/config#browser-testerhtmlpath) instead.
 - `minWorkers` config option. Only `maxWorkers` has any effect on how tests are running, so we are removing this public option.

docs/guide/projects.md

@@ -42,7 +42,54 @@ export default defineConfig({
 })
 ```
 
-Vitest will treat every folder in `packages` as a separate project even if it doesn't have a config file inside. If this glob pattern matches _any file_, it will be considered a Vitest config even if it doesn't have a `vitest` in its name or has an obscure file extension.
+Vitest will treat every folder in `packages` as a separate project even if it doesn't have a config file inside. If the glob pattern matches a file, it will validate that the name starts with `vitest.config`/`vite.config` or matches `(vite|vitest).*.config.*` pattern to ensure it's a Vitest configuration file. For example, these config files are valid:
+
+- `vitest.config.ts`
+- `vite.config.js`
+- `vitest.unit.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.

docs/guide/reporters.md

@@ -141,9 +141,27 @@ Final output after tests have finished:
    Duration  1.26s (transform 35ms, setup 1ms, collect 90ms, tests 1.47s, environment 0ms, prepare 267ms)
 ```
 
+If there is only one test file running, Vitest will output the full test tree of that file, simillar to the [`tree`](#tree-reporter) reporter. The default reporter will also print the test tree if there is at least one failed test in the file.
+
+```bash
+✓ __tests__/file1.test.ts (2) 725ms
+   ✓ first test file (2) 725ms
+     ✓ 2 + 2 should equal 4
+     ✓ 4 - 2 should equal 2
+
+ Test Files  1 passed (1)
+      Tests  2 passed (2)
+   Start at  12:34:32
+   Duration  1.26s (transform 35ms, setup 1ms, collect 90ms, tests 1.47s, environment 0ms, prepare 267ms)
+```
+
 ### Verbose Reporter
 
-Verbose reporter is same as `default` reporter, but it also displays each individual test after the suite has finished. It also displays currently running tests that are taking longer than [`slowTestThreshold`](/config/#slowtestthreshold). Similar to `default` reporter, you can disable the summary by configuring the reporter.
+The verbose reporter prints every test case once it is finished. It does not report suites or files separately. If `--includeTaskLocation` is enabled, it will also include the location of each test in the output. Similar to `default` reporter, you can disable the summary by configuring the reporter.
+
+In addition to this, the `verbose` reporter prints test error messages right away. The full test error is reported when the test run is finished.
+
+This is the only terminal reporter that reports [annotations](/guide/test-annotations) when the test doesn't fail.
 
 :::code-group
 ```bash [CLI]
@@ -161,6 +179,54 @@ export default defineConfig({
 ```
 :::
 
+Example output:
+
+```bash
+✓ __tests__/file1.test.ts > first test file > 2 + 2 should equal 4 1ms
+✓ __tests__/file1.test.ts > first test file > 4 - 2 should equal 2 1ms
+✓ __tests__/file2.test.ts > second test file > 1 + 1 should equal 2 1ms
+✓ __tests__/file2.test.ts > second test file > 2 - 1 should equal 1 1ms
+
+ Test Files  2 passed (2)
+      Tests  4 passed (4)
+   Start at  12:34:32
+   Duration  1.26s (transform 35ms, setup 1ms, collect 90ms, tests 1.47s, environment 0ms, prepare 267ms)
+```
+
+An example with `--includeTaskLocation`:
+
+```bash
+✓ __tests__/file1.test.ts:2:1 > first test file > 2 + 2 should equal 4 1ms
+✓ __tests__/file1.test.ts:3:1 > first test file > 4 - 2 should equal 2 1ms
+✓ __tests__/file2.test.ts:2:1 > second test file > 1 + 1 should equal 2 1ms
+✓ __tests__/file2.test.ts:3:1 > second test file > 2 - 1 should equal 1 1ms
+
+ Test Files  2 passed (2)
+      Tests  4 passed (4)
+   Start at  12:34:32
+   Duration  1.26s (transform 35ms, setup 1ms, collect 90ms, tests 1.47s, environment 0ms, prepare 267ms)
+```
+
+### Tree Reporter
+
+The tree reporter is same as `default` reporter, but it also displays each individual test after the suite has finished. Similar to `default` reporter, you can disable the summary by configuring the reporter.
+
+:::code-group
+```bash [CLI]
+npx vitest --reporter=tree
+```
+
+```ts [vitest.config.ts]
+export default defineConfig({
+  test: {
+    reporters: [
+      ['tree', { summary: false }]
+    ]
+  },
+})
+```
+:::
+
 Example output for tests in progress with default `slowTestThreshold: 300`:
 
 ```bash