Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -32,4 +32,5 @@ test/cli/fixtures/browser-multiple/basic-*
# exclude static html reporter folder
test/browser/html/
test/core/html/
.vitest-attachments
.vitest-attachments
explainFiles.txt
2 changes: 1 addition & 1 deletion docs/advanced/api/vitest.md
Original file line number Diff line number Diff line change
Expand Up @@ -308,7 +308,7 @@ function runTestSpecifications(
): Promise<TestRunResult>
```

This method runs every test based on the received [specifications](/advanced/api/test-specification). The second argument, `allTestsRun`, is used by the coverage provider to determine if it needs to instrument coverage on _every_ file in the root (this only matters if coverage is enabled and `coverage.all` is set to `true`).
This method runs every test based on the received [specifications](/advanced/api/test-specification). The second argument, `allTestsRun`, is used by the coverage provider to determine if it needs to include uncovered files in report.

::: warning
This method doesn't trigger `onWatcherRerun`, `onWatcherStart` and `onTestsRerun` callbacks. If you are rerunning tests based on the file change, consider using [`rerunTestSpecifications`](#reruntestspecifications) instead.
Expand Down
1 change: 0 additions & 1 deletion docs/advanced/reporters.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,6 @@ class MyReporter implements Reporter {

### Built-in reporters:

1. `BasicReporter`
1. `DefaultReporter`
2. `DotReporter`
3. `JsonReporter`
Expand Down
2 changes: 1 addition & 1 deletion docs/advanced/runner.md
Original file line number Diff line number Diff line change
Expand Up @@ -238,7 +238,7 @@ export interface TaskResult {
* Errors that occurred during the task execution. It is possible to have several errors
* if `expect.soft()` failed multiple times.
*/
errors?: ErrorWithDiff[]
errors?: TestError[]
/**
* How long in milliseconds the task took to run.
*/
Expand Down
114 changes: 12 additions & 102 deletions docs/config/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,8 +124,8 @@ When using coverage, Vitest automatically adds test files `include` patterns to
### exclude

- **Type:** `string[]`
- **Default:** `['**/node_modules/**', '**/dist/**', '**/cypress/**', '**/.{idea,git,cache,output,temp}/**', '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build,eslint,prettier}.config.*']`
- **CLI:** `vitest --exclude "**/excluded-file"`
- **Default:** `['**/node_modules/**', '**/.git/**']`
- **CLI:** `vitest --exclude "**/excluded-file" --exclude "*/other-files/*.js"`

A list of glob patterns that should be excluded from your test files.

Expand Down Expand Up @@ -1310,12 +1310,12 @@ Make sure that your files are not excluded by [`server.watch.ignored`](https://v

### coverage<NonProjectOption />

You can use [`v8`](https://v8.dev/blog/javascript-code-coverage), [`istanbul`](https://istanbul.js.org/) or [a custom coverage solution](/guide/coverage#custom-coverage-provider) for coverage collection.
You can use [`v8`](/guide/coverage.html#v8-provider), [`istanbul`](/guide/coverage.html#istanbul-provider) or [a custom coverage solution](/guide/coverage#custom-coverage-provider) for coverage collection.

You can provide coverage options to CLI with dot notation:

```sh
npx vitest --coverage.enabled --coverage.provider=istanbul --coverage.all
npx vitest --coverage.enabled --coverage.provider=istanbul
```

::: warning
Expand All @@ -1342,76 +1342,26 @@ Enables coverage collection. Can be overridden using `--coverage` CLI option.
#### coverage.include

- **Type:** `string[]`
- **Default:** `['**']`
- **Default:** Files that were imported during test run
- **Available for providers:** `'v8' | 'istanbul'`
- **CLI:** `--coverage.include=<path>`, `--coverage.include=<path1> --coverage.include=<path2>`
- **CLI:** `--coverage.include=<pattern>`, `--coverage.include=<pattern1> --coverage.include=<pattern2>`

List of files included in coverage as glob patterns
List of files included in coverage as glob patterns. By default only files covered by tests are included.

#### coverage.extension
It is recommended to pass file extensions in the pattern.

- **Type:** `string | string[]`
- **Default:** `['.js', '.cjs', '.mjs', '.ts', '.mts', '.tsx', '.jsx', '.vue', '.svelte', '.marko', '.astro']`
- **Available for providers:** `'v8' | 'istanbul'`
- **CLI:** `--coverage.extension=<extension>`, `--coverage.extension=<extension1> --coverage.extension=<extension2>`
See [Including and excluding files from coverage report](/guide/coverage.html#including-and-excluding-files-from-coverage-report) for examples.

#### coverage.exclude

- **Type:** `string[]`
- **Default:**
```js
[
'coverage/**',
'dist/**',
'**/node_modules/**',
'**/[.]**',
'packages/*/test?(s)/**',
'**/*.d.ts',
'**/virtual:*',
'**/__x00__*',
'**/\x00*',
'cypress/**',
'test?(s)/**',
'test?(-*).?(c|m)[jt]s?(x)',
'**/*{.,-}{test,spec,bench,benchmark}?(-d).?(c|m)[jt]s?(x)',
'**/__tests__/**',
'**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build,eslint,prettier}.config.*',
'**/vitest.{workspace,projects}.[jt]s?(on)',
'**/.{eslint,mocha,prettier}rc.{?(c|m)js,yml}',
]
```
- **Default:** : `[]`
- **Available for providers:** `'v8' | 'istanbul'`
- **CLI:** `--coverage.exclude=<path>`, `--coverage.exclude=<path1> --coverage.exclude=<path2>`

List of files excluded from coverage as glob patterns.

This option overrides all default options. Extend the default options when adding new patterns to ignore:

```ts
import { coverageConfigDefaults, defineConfig } from 'vitest/config'

export default defineConfig({
test: {
coverage: {
exclude: ['**/custom-pattern/**', ...coverageConfigDefaults.exclude]
},
},
})
```

::: tip NOTE
Vitest automatically adds test files `include` patterns to the `coverage.exclude`.
It's not possible to show coverage of test files.
:::

#### coverage.all

- **Type:** `boolean`
- **Default:** `true`
- **Available for providers:** `'v8' | 'istanbul'`
- **CLI:** `--coverage.all`, `--coverage.all=false`

Whether to include all files, including the untested ones into report.
See [Including and excluding files from coverage report](/guide/coverage.html#including-and-excluding-files-from-coverage-report) for examples.

#### coverage.clean

Expand Down Expand Up @@ -1678,51 +1628,11 @@ Sets thresholds to 100 for files matching the glob pattern.
}
```

#### coverage.ignoreEmptyLines

- **Type:** `boolean`
- **Default:** `true` (`false` in v1)
- **Available for providers:** `'v8'`
- **CLI:** `--coverage.ignoreEmptyLines=<boolean>`

Ignore empty lines, comments and other non-runtime code, e.g. Typescript types. Requires `experimentalAstAwareRemapping: false`.

This option works only if the used compiler removes comments and other non-runtime code from the transpiled code.
By default Vite uses ESBuild which removes comments and Typescript types from `.ts`, `.tsx` and `.jsx` files.

If you want to apply ESBuild to other files as well, define them in [`esbuild` options](https://vitejs.dev/config/shared-options.html#esbuild):

```ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
esbuild: {
// Transpile all files with ESBuild to remove comments from code coverage.
// Required for `test.coverage.ignoreEmptyLines` to work:
include: ['**/*.js', '**/*.jsx', '**/*.mjs', '**/*.ts', '**/*.tsx'],
},
test: {
coverage: {
provider: 'v8',
ignoreEmptyLines: true,
},
},
})
```
#### coverage.experimentalAstAwareRemapping

- **Type:** `boolean`
- **Default:** `false`
- **Available for providers:** `'v8'`
- **CLI:** `--coverage.experimentalAstAwareRemapping=<boolean>`

Remap coverage with experimental AST based analysis. Provides more accurate results compared to default mode.

#### coverage.ignoreClassMethods

- **Type:** `string[]`
- **Default:** `[]`
- **Available for providers:** `'istanbul'`
- **Available for providers:** `'v8' | 'istanbul'`
- **CLI:** `--coverage.ignoreClassMethods=<method>`

Set to array of class method names to ignore for coverage.
Expand Down
42 changes: 42 additions & 0 deletions docs/guide/browser/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -584,3 +584,45 @@ test('renders a message', async () => {
When using Vitest Browser, it's important to note that thread blocking dialogs like `alert` or `confirm` cannot be used natively. This is because they block the web page, which means Vitest cannot continue communicating with the page, causing the execution to hang.

In such situations, Vitest provides default mocks with default returned values for these APIs. This ensures that if the user accidentally uses synchronous popup web APIs, the execution would not hang. However, it's still recommended for the user to mock these web APIs for better experience. Read more in [Mocking](/guide/mocking).

### Spying on Module Exports

Browser Mode uses the browser's native ESM support to serve modules. The module namespace object is sealed and can't be reconfigured, unlike in Node.js tests where Vitest can patch the Module Runner. This means you can't call `vi.spyOn` on an imported object:

```ts
import { vi } from 'vitest'
import * as module from './module.js'

vi.spyOn(module, 'method') // ❌ throws an error
```

To bypass this limitation, Vitest supports `{ spy: true }` option in `vi.mock('./module.js')`. This will automatically spy on every export in the module without replacing them with fake ones.

```ts
import { vi } from 'vitest'
import * as module from './module.js'

vi.mock('./module.js', { spy: true })

vi.mocked(module.method).mockImplementation(() => {
// ...
})
```

However, the only way to mock exported _variables_ is to export a method that will change the internal value:

::: code-group
```js [module.js]
export let MODE = 'test'
export function changeMode(newMode) {
MODE = newMode
}
```
```js [module.test.ts]
import { expect } from 'vitest'
import { changeMode, MODE } from './module.js'

changeMode('production')
expect(MODE).toBe('production')
```
:::
16 changes: 1 addition & 15 deletions docs/guide/cli-generated.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ Hide logs for skipped tests
- **CLI:** `--reporter <name>`
- **Config:** [reporters](/config/#reporters)

Specify reporters (default, basic, blob, verbose, dot, json, tap, tap-flat, junit, hanging-process, github-actions)
Specify reporters (default, blob, verbose, dot, json, tap, tap-flat, junit, hanging-process, github-actions)

### outputFile

Expand All @@ -98,13 +98,6 @@ Specify reporters (default, basic, blob, verbose, dot, json, tap, tap-flat, juni

Write test results to a file when supporter reporter is also specified, use cac's dot notation for individual outputs of multiple reporters (example: `--outputFile.tap=./tap.txt`)

### coverage.all

- **CLI:** `--coverage.all`
- **Config:** [coverage.all](/config/#coverage-all)

Whether to include all files, including the untested ones into report

### coverage.provider

- **CLI:** `--coverage.provider <name>`
Expand Down Expand Up @@ -133,13 +126,6 @@ Files included in coverage as glob patterns. May be specified more than once whe

Files to be excluded in coverage. May be specified more than once when using multiple extensions (default: Visit [`coverage.exclude`](https://vitest.dev/config/#coverage-exclude))

### coverage.extension

- **CLI:** `--coverage.extension <extension>`
- **Config:** [coverage.extension](/config/#coverage-extension)

Extension to be included in coverage. May be specified more than once when using multiple extensions (default: `[".js", ".cjs", ".mjs", ".ts", ".mts", ".tsx", ".jsx", ".vue", ".svelte"]`)

### coverage.clean

- **CLI:** `--coverage.clean`
Expand Down
Loading