vitest

What is vitest?

Vitest is a blazing fast unit test framework powered by Vite. It is designed to provide a delightful testing experience with features like native ES modules support, TypeScript support, and a rich API for running and organizing tests.

What are vitest's main functionalities?

Unit Testing

Vitest allows you to write and run unit tests for your JavaScript/TypeScript code. The example shows a simple test suite for a math operation.

import { describe, it, expect } from 'vitest';
describe('math', () => {
  it('should add numbers correctly', () => {
    expect(1 + 1).toBe(2);
  });
});

Mocking

Vitest provides a built-in mocking utility, allowing you to create mock functions and spy on their behavior.

import { vi } from 'vitest';
const mockFunction = vi.fn(() => 42);
mockFunction();
expect(mockFunction).toHaveBeenCalled();

Snapshot Testing

Vitest supports snapshot testing, which is useful for ensuring your UI does not change unexpectedly. It saves the 'snapshot' of the output and compares it against future test runs.

import { expect, test } from 'vitest';
test('snapshot test', () => {
  const user = { id: 1, name: 'John Doe' };
  expect(user).toMatchSnapshot();
});

Code Coverage

Vitest can generate code coverage reports to help you understand which parts of your codebase are covered by tests.

// Run Vitest with the --coverage flag to generate code coverage reports
// vitest run --coverage

Watch Mode

Vitest's watch mode re-runs tests when it detects changes in the test files or the corresponding source files, providing instant feedback during development.

// Run Vitest in watch mode using the --watch flag
// vitest --watch

Other packages similar to vitest

jest

Jest is a popular testing framework with a focus on simplicity. It provides a similar set of features to Vitest, including mocking, snapshot testing, and watch mode. However, Jest is often considered slower than Vitest due to its heavier architecture.

mocha

Mocha is a flexible testing framework for Node.js and the browser. It's known for its simplicity and support for various assertion libraries. Unlike Vitest, Mocha does not include a built-in assertion library or mocking utilities, requiring additional packages for these features.

ava

AVA is a test runner for Node.js with a concise API, detailed error output, and process isolation for concurrent test execution. It differs from Vitest in its approach to concurrency and its minimalistic design.

jasmine

Jasmine is a behavior-driven development framework for testing JavaScript code. It does not require a DOM and comes with an assertion library. Jasmine is less modern compared to Vitest and does not support ES modules natively.

README

vitest

A blazing fast test runner powered by Vite.

Features

• Vite's config, transformers, resolvers, and plugins. Powered by vite-node
• Jest Snapshot
• Chai for assertions
• Sinon for mocking
• Async suite / test, top level await
• ESM friendly
• Out-of-box TypeScript support
• Suite and Test filtering (skip, only, todo)

import { it, describe, expect, assert } from 'vitest'

describe('suite name', () => {
  it('foo', () => {
    assert.equal(Math.sqrt(4), 2)
  })

  it('bar', () => {
    expect(1 + 1).eq(2)
  })

  it('snapshot', () => {
    expect({ foo: 'bar' }).toMatchSnapshot()
  })
})

$ npx vitest

Configuration

vitest will read your root vite.config.ts when it present to match with the plugins and setup as your Vite app. If you want to it to have a different configuration for testing, you could either:

• 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 to conditionally apply differnet configuration in vite.config.ts

To configure vitest itself, add test property in your Vite config

// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  test: {
    // ...
  }
})

Global APIs

By default, vitest does not provide global APIs for explicitness. If you prefer to use the APIs globally like Jest, you can pass the --global option to CLI or add global: true in the config.

// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  test: {
    global: true
  }
})

To get TypeScript working with the global APIs, add vitest/global to the types filed in your tsconfig.json

// tsconfig.json
{
  "compilerOptions": {
    "types": [
      "vitest/global"
    ]
  }
}

Filtering

Skipping suites and tasks

Use .skip to avoid running certain suites or tests

describe.skip('skipped suite', () => {
  it('task', () => {
    // Suite skipped, no error
    assert.equal(Math.sqrt(4), 3)
  })
})

describe('suite', () => {
  it.skip('skipped task', () => {
    // Task skipped, no error
    assert.equal(Math.sqrt(4), 3)
  })
})

Selecting suites and tests to run

Use .only to only run certain suites or tests

// Only this suite (and others marked with only) are run
describe.only('suite', () => {
  it('task', () => {
    assert.equal(Math.sqrt(4), 3) 
  })
})

describe('another suite', () => {
  it('skipped task', () => {
     // Task skipped, as tests are running in Only mode
    assert.equal(Math.sqrt(4), 3)
  })

  it.only('task', () => {
     // Only this task (and others marked with only) are run
    assert.equal(Math.sqrt(4), 2)
  })
})

Unimplemented suites and tests

Use .todo to stub suites and tests that should be implemented

 // An entry will be shown in the report for this suite
describe.todo('unimplemented suite')

// An entry will be shown in the report for this task
describe('suite', () => {
  it.todo('unimplemented task')
})

TODO

• Reporter & Better output
• Task filter
• Mock
• Global Mode & Types
• Parallel Executing
• CLI Help
• JSDom
• Watch
• Source Map
• Coverage

Sponsors

License

MIT License © 2021 Anthony Fu