diff --git a/docs/.vitepress/components.d.ts b/docs/.vitepress/components.d.ts index 5acc4cdb5..4b95bae77 100644 --- a/docs/.vitepress/components.d.ts +++ b/docs/.vitepress/components.d.ts @@ -7,7 +7,9 @@ export {} /* prettier-ignore */ declare module 'vue' { export interface GlobalComponents { + ArrowDown: typeof import('./components/ArrowDown.vue')['default'] BlogIndex: typeof import('./components/BlogIndex.vue')['default'] + Box: typeof import('./components/Box.vue')['default'] Contributors: typeof import('./components/Contributors.vue')['default'] CourseLink: typeof import('./components/CourseLink.vue')['default'] FeaturesList: typeof import('./components/FeaturesList.vue')['default'] diff --git a/docs/.vitepress/components/ArrowDown.vue b/docs/.vitepress/components/ArrowDown.vue new file mode 100644 index 000000000..3a25019b0 --- /dev/null +++ b/docs/.vitepress/components/ArrowDown.vue @@ -0,0 +1,27 @@ + + + diff --git a/docs/.vitepress/components/Box.vue b/docs/.vitepress/components/Box.vue new file mode 100644 index 000000000..29147476d --- /dev/null +++ b/docs/.vitepress/components/Box.vue @@ -0,0 +1,18 @@ + + + diff --git a/docs/guide/coverage.md b/docs/guide/coverage.md index 90ff19f78..17c4d61f5 100644 --- a/docs/guide/coverage.md +++ b/docs/guide/coverage.md @@ -37,6 +37,99 @@ npm i -D @vitest/coverage-istanbul ``` ::: +## V8 provider + +::: info +The description of V8 coverage below is Vitest specific and does not apply to other test runners. +Since `v3.2.0` Vitest has used [AST based coverage remapping](/blog/vitest-3-2#coverage-v8-ast-aware-remapping) for V8 coverage, which produces identical coverage reports to Istanbul. + +This allows users to have the speed of V8 coverage with accuracy of Istanbul coverage. +::: + +By default Vitest uses `'v8'` coverage provider. +This provider requires Javascript runtime that's implemented on top of [V8 engine](https://v8.dev/), such as NodeJS, Deno or any Chromium based browsers such as Google Chrome. + +Coverage collection is performed during runtime by instructing V8 using [`node:inspector`](https://nodejs.org/api/inspector.html) and [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/tot/Profiler/) in browsers. User's source files can be executed as-is without any pre-instrumentation steps. + +- ✅ Recommended option to use +- ✅ No pre-transpile step. Test files can be executed as-is. +- ✅ Faster execute times than Istanbul. +- ✅ Lower memory usagethan Istanbul. +- ✅ Coverage report accuracy is as good as with Istanbul ([since Vitest `v3.2.0`](/blog/vitest-3-2#coverage-v8-ast-aware-remapping)). +- ⚠️ In some cases can be slower than Istanbul, e.g. when loading lots of different modules. V8 does not support limiting coverage collection to specific modules. +- ⚠️ There are some minor limitations set by V8 engine. See [`ast-v8-to-istanbl` | Limitations](https://github.com/AriPerkkio/ast-v8-to-istanbul?tab=readme-ov-file#limitations). +- ❌ Does not work on environments that don't use V8, such as Firefox or Bun. Or on environments that don't expose V8 coverage via profiler, such as Cloudflare Workers. + +
+ Test file + + Enable V8 runtime coverage collection + + Run file + + Collect coverage results from V8 + + Remap coverage results to source files + + Coverage report +
+ +## Istanbul provider + +[Istanbul code coverage tooling](https://istanbul.js.org/) has existed since 2012 and is very well battle-tested. +This provider works on any Javascript runtime as coverage tracking is done by instrumenting user's source files. + +In practice, instrumenting source files means adding additional Javascript in user's files: + +```js +// Simplified example of branch and function coverage counters +const coverage = { // [!code ++] + branches: { 1: [0, 0] }, // [!code ++] + functions: { 1: 0 }, // [!code ++] +} // [!code ++] + +export function getUsername(id) { + // Function coverage increased when this is invoked // [!code ++] + coverage.functions['1']++ // [!code ++] + + if (id == null) { + // Branch coverage increased when this is invoked // [!code ++] + coverage.branches['1'][0]++ // [!code ++] + + throw new Error('User ID is required') + } + // Implicit else coverage increased when if-statement condition not met // [!code ++] + coverage.branches['1'][1]++ // [!code ++] + + return database.getUser(id) +} + +globalThis.__VITEST_COVERAGE__ ||= {} // [!code ++] +globalThis.__VITEST_COVERAGE__[filename] = coverage // [!code ++] +``` + +- ✅ Works on any Javascript runtime +- ✅ Widely used and battle-tested for over 13 years. +- ✅ In some cases faster than V8. Coverage instrumentation can be limited to specific files, as opposed to V8 where all modules are instrumented. +- ❌ Requires pre-instrumentation step +- ❌ Execution speed is slower than V8 due to instrumentation overhead +- ❌ Instrumentation increases file sizes +- ❌ Memory usage is higher than V8 + +
+ Test file + + Pre‑instrumentation with Babel + + Run file + + Collect coverage results from Javascript scope + + Remap coverage results to source files + + Coverage report +
+ ## Coverage Setup :::tip