---
title: "Vitest 4の新機能と移行ガイド｜ブラウザモード正式化・VRT・最新バージョン"
url: "https://www.issoh.co.jp/tech/details/9465/"
published: 2025-10-24
updated: 2026-10-02
categories: ["テスト"]
publisher: "株式会社一創"
---

# Vitest 4の新機能と移行ガイド｜ブラウザモード正式化・VRT・最新バージョン

Vitest 4は、Viteと一体で動く高速なフロントエンドテストフレームワークのメジャーアップデートです。2025年10月22日に4.0が公開され、これまで実験的だったブラウザモードの正式化、スクリーンショットを基準画像と比較するビジュアルリグレッションテスト（VRT）、Playwrightトレース対応が目玉になりました。2026年3月12日の4.1ではテストタグやネイティブNode.js実行が加わり、2026年6月時点の最新は4.1系（4.1.9）です。この記事では、Vitest 4と4.1で入った新機能、Vitest 3からの移行で引っかかる破壊的変更、高速化の実務、最新バージョンとVitest 5の見通しまでを、公式ドキュメントとリリースノートの一次情報で整理します。

Vitest本体の定義や、Viteの変換パイプラインを共有する仕組み、Jestやnode:testとの選び分けは[Vitestとは？Viteネイティブなテスト基盤の仕組みと採用判断を実装目線で解説](https://www.issoh.co.jp/tech/details/16023/)で扱っています。

## まとめ：Vitest 4の要点と最新バージョン

Vitest 4の中心は3つです。第一に、実験的だったブラウザモードが正式化され、プロバイダを`@vitest/browser-playwright`などの別パッケージで指定する方式に変わりました。第二に、スクリーンショットを基準画像と比較するVRT（`toMatchScreenshot`）と、要素がビューポート内にあるか検証する`toBeInViewport`、スキーマ検証の`expect.schemaMatching`といった新マッチャーが加わりました。第三に、Playwrightトレース対応でブラウザテストの失敗調査がしやすくなりました。続く4.1（2026年3月）ではテストタグ、実験的なネイティブNode.js実行、AIエージェント向けレポーターが追加され、最新は4.1.9です。Vitest 3からの移行では、動作要件がNode.js 20.19以降・Vite 6以降に上がり、`environmentMatchGlobs`・`coverage.all`・`basic`レポーターが削除されるなど破壊的変更があります。多くのテストコードはそのまま動きますが、設定ファイルとレポーター指定は見直しが必要です。次期メジャーのVitest 5はまだベータも出ておらず計画段階なので、いま導入するなら4.1系が現実的な選択です。各機能の具体は以下で解説します。

## Vitest 4の主な新機能

4.0の新機能はブラウザUIテストとデバッグ体験の強化に寄っています。ここでは影響の大きい順に、ブラウザモードの正式化、VRT、新マッチャー、トレースの4点を具体的に見ます。

### ブラウザモードの正式化とプロバイダの別パッケージ化

Vitest 3まで実験的（experimental）だったブラウザモードが、4.0で正式機能になりました。実ブラウザ上でコンポーネントを描画してテストできるため、jsdomでは再現しにくいレイアウトやフォーカス、スクロールの挙動を実環境に近い形で検証できます。正式化に伴い公開APIが整理され、プロバイダは本体とは別のパッケージをインストールして指定する方式に変わりました。選べるのは`@vitest/browser-playwright`、`@vitest/browser-webdriverio`、`@vitest/browser-preview`の3つです。

```
npm install -D vitest@latest @vitest/browser-playwright

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

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{ browser: 'chromium' }],
    },
  },
})
```

採用の判断はコンポーネントの性質で分けるのが実務的です。DOMの見た目・操作・アクセシビリティを検証したいコンポーネントテストはブラウザモードが向きます。一方、純粋なロジックやユーティリティ関数のテストにブラウザモードを使うと、起動コストが増えて実行が遅くなるだけなので`node`環境のままにすべきです。全テストを一律ブラウザモードに寄せるのは過剰です。導入手順と設定項目は[Vitest Browser Modeの導入・セットアップ方法](/tech/details/7394/)で詳しく解説しています。

### ビジュアルリグレッションテスト（toMatchScreenshot）

4.0では、外部ライブラリを足さずにVRTが書けるようになりました。`toMatchScreenshot`マッチャーが要素やページのスクリーンショットを撮り、基準画像（リファレンス）と比較して、意図しない見た目の差分を検出します。初回実行時に基準画像が生成され、2回目以降はそれと突き合わせる流れです。

```
test('button appearance', async () => {
  await expect(page.getByRole('button', { name: 'Save' }))
    .toMatchScreenshot()
})
```

注意したいのは、VRTは環境差でflaky（不安定）になりやすい点です。OSやブラウザのバージョン、フォントレンダリング、アニメーションの違いで差分が出て、実害のない失敗が量産されることがあります。基準画像はCIと同じ環境で生成する、アニメーションは無効化する、といった前提を固めてから導入するのが安全です。ローカルとCIで画像を作り分ける運用は破綻しやすいので避けてください。

### 新マッチャー（toBeInViewportとexpect.schemaMatching）

アサーションの表現力も広がりました。`toBeInViewport`はブラウザのIntersectionObserver APIを使い、要素が現在ビューポート内に表示されているかを判定します。`ratio`引数で最小可視割合（0〜1）を指定でき、「半分以上見えていれば合格」といった条件も書けます。遅延読み込みやスクロール連動の表示制御をテストするときに有効です。もう一つの`expect.schemaMatching`は、Standard Schema v1に準拠したスキーマオブジェクト（ZodやValibotなど対応ライブラリのスキーマ）を受け取り、値がスキーマに適合するかを非対称マッチャーとして検証します。APIレスポンスの形を丸ごと検証する用途で、個別プロパティを列挙するより簡潔に書けます。

```
import { z } from 'zod'

const UserSchema = z.object({ id: z.number(), name: z.string() })

expect(response.body).toEqual(expect.schemaMatching(UserSchema))
```

### Playwrightトレースとデバッグ強化

ブラウザテストの失敗調査には、4.0で入ったPlaywrightトレース対応が効きます。`browser.trace`オプション（または設定内の`trace`）で記録方針を選べ、値は`on`・`off`・`on-first-retry`・`on-all-retries`・`retain-on-failure`があります。失敗時のみ保持する`retain-on-failure`にしておけば、テストが落ちたときだけ操作過程のトレースを残せて、原因の再現がしやすくなります。加えて、Playwrightプロバイダ限定で`page.frameLocator`が使えるようになり、iframe内の要素を辿れます。VSCode拡張ではブラウザテストでも「Debug Test」ボタンが機能します。

## Vitest 4.1で追加された機能

4.1は破壊的変更を伴わないマイナーアップデートながら、実務で効く機能が入っています。メジャーの合間に安全に上げられる位置づけです。

### テストタグによる分類とフィルタ

テストにタグを付けて分類し、タグ単位で実行対象を絞ったり、長めのタイムアウトや自動リトライといった共通オプションをまとめて適用できるようになりました。E2E寄りの重いテストだけを普段の実行から外し、CIでのみ回すといった運用が設定ファイルを分けずに書けます。

```
test('heavy integration', { tag: '@slow', retry: 2 }, async () => {
  // ...
})
```

### ネイティブNode.js実行（experimental）

4.1では実験的な`experimental.viteModuleRunner`オプションが追加され、`false`を指定するとViteのモジュールランナーを経由せず、Node.jsのネイティブ`import`でテストを走らせられます。狙いは起動の高速化と、本番挙動により近い実行です。設定は`test.experimental`配下に書きます。

```
// vitest.config.ts
export default defineConfig({
  test: {
    experimental: {
      viteModuleRunner: false,
    },
  },
})
```

ただし現時点ではexperimentalで、制約が多い点に注意が必要です。プラグインやエイリアス、`import.meta.env`が効かず、プールは`forks`か`threads`に限られ、カバレッジはistanbulが使えずv8プロバイダが必要です。Viteの変換や解決に依存する既存プロジェクトをいきなり全面切り替えするのは避け、対象を絞って検証するのが無難です。

### AIエージェントレポーターと新ライフサイクルフック

AIエージェント向けの最小レポーターが加わり、成功したテストの出力を抑えて失敗したテストとエラーだけを表示します。コーディングエージェントにテスト結果を渡すときにノイズを減らせます。ライフサイクルでは`aroundEach`と`aroundAll`が追加され、テストをコンテキストで包めるため、データベーストランザクションの開始・ロールバックやトレース用スパンの管理を一箇所に書けます。ほかに、ヘルパー関数の内部をスタックトレースから除いて呼び出し元を指す`vi.defineHelper`、リークした非同期リソースを発生箇所つきで報告する`--detect-async-leaks`フラグも入りました。

## Vitest 3から4への移行と破壊的変更

多くのテストコードは書き換えなしで動きますが、破壊的変更は設定ファイルとレポーター、ブラウザモード周りに集中しています。上げる前に自分のプロジェクトへの影響を洗い出しておくと安全です。

### 動作要件：Node.js 20.19以降・Vite 6以降

Vitest 4はNode.jsのモダンLTSを前提とし、Node 20系なら20.19以降、22系なら22.12以降が必要です。ビルド側はVite 6以降が要件になります。古いNodeやVite 5以前のプロジェクトは、Vitestを上げる前にランタイムとViteの更新から着手してください。要件を満たさないまま上げると、起動時点でエラーになります。

### 削除された設定とprojectsへの移行

非推奨だった設定がいくつか削除されました。ファイルパターンで環境を切り替える`environmentMatchGlobs`と`poolMatchGlobs`が廃止され、代わりに`projects`で分割する方式に一本化されています。カバレッジ側では`coverage.all`と`coverage.ignoreEmptyLines`も削除されました。`environmentMatchGlobs`を使っていたプロジェクトは、移行を忘れるとテストが誤った環境で走ってしまうため、優先して直す必要があります。

```
// 旧: environmentMatchGlobs で環境を出し分け
// 新: projects に分割する
export default defineConfig({
  test: {
    projects: [
      { test: { name: 'node', environment: 'node', include: ['src/**/*.node.test.ts'] } },
      { test: { name: 'dom', environment: 'jsdom', include: ['src/**/*.dom.test.ts'] } },
    ],
  },
})
```

### ブラウザモードのプロバイダ指定の変更

前述のとおり、ブラウザモードのプロバイダは本体同梱ではなくなり、`@vitest/browser-playwright`などの別パッケージを追加して`provider: 'playwright'`のように指定する方式に変わりました。3系でブラウザモードを実験的に使っていた場合は、パッケージの追加と設定キーの見直しが移行作業に含まれます。

### レポーターとモックの変更点

レポーターでは`basic`が削除され、既定レポーターは単一ファイル実行時のみツリー表示になりました。常にツリー表示したい場合は新しい`tree`レポーターを指定します。CIの出力を`basic`に固定していた設定は書き換えが要ります。モック周りでは、Jestからの移行で探されがちな`requireActual`に相当するのがVitestの`vi.importActual`です。実体を読み込んで一部だけモックする場合はこちらを使います。

```
vi.mock('./math.js', async () => {
  const actual = await vi.importActual('./math.js')
  return { ...actual, add: vi.fn() }
})
```

## Vitest 4の高速化とキャッシュの仕組み

Vitestはもともと速い部類ですが、遅くなる原因はツール側よりテストコード側にあることが多いです。仕組みを理解したうえで、ボトルネックを潰す順に手を打つのが効きます。

### 並列実行とキャッシュの既定挙動

Vitestは既定でテストファイル単位の並列実行を行い、Viteの変換結果のキャッシュを再利用します。そのため、明示的なキャッシュ設定を足さなくても2回目以降の起動は速くなります。まず押さえるべきは、この既定の並列＋キャッシュが効く構成を崩さないことです。むやみに`singleThread`や直列実行へ倒すと、この利点を手放すことになります。

### 遅いテストの特定と改善

さらに速くするなら、待ち時間を作っている箇所から削ります。実務ではまず、外部API通信やデータベースアクセスを`vi.mock`でモック化してネットワーク待ちをなくすのが最も効きます。次に、重い初期化を各テストで繰り返さず`beforeAll`に一度だけまとめる、大量の組み合わせテストを代表値・境界値に絞る、という順です。どのテストが遅いかは、レポーターで各テストの実行時間を確認して特定します。推測で並列数だけいじる前に、遅いファイルを実測で見つけるのが近道です。

## 最新バージョンの状況とVitest 5の見通し

2026年6月時点の安定版は4.1系で、最新は4.1.9です。リリースの流れは、4.0が2025年10月22日、4.1が2026年3月12日で、以降はパッチが重ねられてきました。新規導入なら4.1系を選べば、ブラウザモードの正式サポートからVRT、テストタグまでVitest 4の機能を一通り使えます。

次期メジャーのVitest 5については、ベータもまだ公開されておらず、計画・議論の段階です。開発チームは短期で破壊的変更を急がず、Vite 8のリリースに歩調を合わせる方針を示しています。議論されている変更には、`clearMocks`を既定で有効化してテスト分離を強める、`getByRole`などロケーターで`exact: true`を既定にして壊れにくくする、`toHaveTextContent`を厳格化し部分一致用に`toMatchTextContent`を用意する、Node・Deno・Bunをまたいで実行するマルチランタイム対応などがあります。いずれも確定仕様ではありません。したがって、いまVitest 5を待つ理由は薄く、4.1系で運用しつつ動向を追うのが現実的です。バージョンは更新が速いので、細かな数値は導入前にnpmや公式で確認してください。

## よくある質問

### Vitestの最新バージョンはいくつですか？

2026年6月時点の安定版は4.1系で、最新は4.1.9です。4.0は2025年10月、4.1は2026年3月に公開されました。次期メジャーのVitest 5はベータもまだ出ておらず、計画・議論の段階です（Vite 8に歩調を合わせる方針）。新規導入なら4.1系を選べば、ブラウザモードの正式サポートやビジュアルリグレッションテストなどVitest 4の新機能をすべて使えます。バージョンは更新が速いため、導入前にnpmや公式サイトで最新を確認してください。

### Vitest 4の主な新機能は何ですか？

大きく4つです。1つ目はブラウザモードの正式サポートで、プロバイダを別パッケージで指定し実ブラウザに近い環境でテストできます。2つ目はビジュアルリグレッションテスト（VRT）で、`toMatchScreenshot`により画面の見た目の差分を自動検出します。3つ目は`toBeInViewport`や`expect.schemaMatching`といった新マッチャーの追加です。4つ目はPlaywrightトレース対応によるデバッグ強化で、失敗時の操作過程を可視化できます。続く4.1ではテストタグや実験的なネイティブNode.js実行も加わりました。

### Vitest 3から4への移行で注意する点は？

破壊的変更がいくつかあります。`environmentMatchGlobs`や`poolMatchGlobs`、`coverage.all`など非推奨だった設定が削除され、`basic`レポーターも廃止されました。ブラウザモードはプロバイダを別パッケージで指定する新方式に変わっています。動作要件もNode.js 20.19以降・Vite 6以降に上がりました。多くのテストコードはそのまま動きますが、設定ファイルとレポーター指定は見直しが必要です。公式の移行ガイドで自分のプロジェクトに影響する項目を洗い出してから上げるのが安全です。

### Vitestを高速化するにはどうすればよいですか？

Vitestは既定でテストファイル単位の並列実行とViteのキャッシュを活用するため、もともと高速です。さらに速くするには、外部通信やデータベースアクセスを`vi.mock`でモック化して待ち時間をなくす、重い初期化を`beforeAll`にまとめる、大量の組み合わせテストを代表値や境界値に絞る、といった工夫が有効です。遅いテストの特定には、レポーターで各テストの実行時間を確認します。ツール側の並列数をいじる前に、テストコード側のボトルネックを実測で潰すのが効果的です。

### Vitest 4はJestから移行できますか？

できます。VitestはJestとAPI互換性が高く、多くのテストコードはそのまま動きます。`jest.fn`は`vi.fn`に、`jest.requireActual`は`vi.importActual`に置き換えるなど名前空間の差はありますが、機械的な置換で対応できる範囲がほとんどです。Viteの設定を共有できるためトランスパイル設定の重複も減ります。Reactコンポーネントテストの具体的な始め方は[React Testing LibraryでVitestのコンポーネントテストを書く実践ガイド](/tech/details/2867/)で解説しています。

## 関連記事

- [Vitest Browser Modeの導入・セットアップ方法を徹底解説](/tech/details/7394/)
- [React Testing LibraryでVitestのコンポーネントテストを書く実践ガイド](/tech/details/2867/)

---

出典: [Vitest 4の新機能と移行ガイド｜ブラウザモード正式化・VRT・最新バージョン](<https://www.issoh.co.jp/tech/details/9465/>)（株式会社一創）