Reactの表示の変化をVitestのスナップショットで見つける

​​React​jsdom,React Testing Library,TypeScript,Vitest

React のコンポーネントの文言やクラス名が意図せず変わったとき、それに気づくには、Vitest のスナップショットテストが使えます。描画した結果をファイルに記録しておき、次の実行で記録と違えばテストを落として、どこが変わったかを差分で見せてくれます。リファクタリングやライブラリの更新のあとに、画面の表示(DOM)が変わっていないかを確かめたい場面で役に立ちます。

私は検証環境で、価格の表示を出す小さなコンポーネントを React Testing Library で描画し、記録・差分・更新・CI での動きを順に確かめました。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4 です。使ったのは vitest 5.1.0、jsdom 31.0.0、@testing-library/react 16.3.3、@testing-library/dom 10.4.2、react / react-dom 19.3.1、@vitejs/plugin-react 6.3.0、typescript 7.0.2 です。ウォッチモードで u キーを押して更新する操作、toMatchFileSnapshot()、ブラウザーモードでの画像の比較(toMatchScreenshot())は試していません。

描画結果をスナップショットに記録する

試したのは、商品名と価格を出し、セール中ならバッジも出すコンポーネントです。

tsx
// src/PriceTag.tsx
type Props = {
  name: string;
  price: number;
  onSale?: boolean;
};

export function PriceTag({ name, price, onSale = false }: Props) {
  return (
    <div className={onSale ? 'price-tag price-tag--sale' : 'price-tag'}>
      <span className="price-tag__name">{name}</span>
      <span className="price-tag__price">{price.toLocaleString('ja-JP')}円</span>
      {onSale && <span className="price-tag__badge">セール中</span>}
    </div>
  );
}

テストでは、React Testing Library の render() が返す asFragment() で描画結果の DOM を取り出し、Vitest の toMatchSnapshot() に渡します。

tsx
// src/PriceTag.test.tsx
import { render } from '@testing-library/react';
import { expect, test } from 'vitest';
import { PriceTag } from './PriceTag';

test('通常の価格の表示', () => {
  const { asFragment } = render(<PriceTag name="猫用ブラシ" price={1980} />);
  expect(asFragment()).toMatchSnapshot();
});

test('セール中の表示', () => {
  const { asFragment } = render(<PriceTag name="猫用ブラシ" price={1480} onSale />);
  expect(asFragment()).toMatchSnapshot();
});

Vitest の設定では、React のプラグインを入れ、テストの環境を jsdom にしただけです。

ts
// vitest.config.ts
import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
  },
});

初めて実行すると、テストは通り、スナップショットが2つ書かれたと表示されます。出力の中のプロジェクトの場所は <project> に置き換えています。

text
$ npx vitest run

 RUN  v5.1.0 <project>


  Snapshots  2 written
 Test Files  1 passed (1)
      Tests  2 passed (2)

書かれたのは、テストファイルの隣の __snapshots__/PriceTag.test.tsx.snap です。中身は、テストの名前ごとに DOM を整形した文字列でした(「セール中の表示」の分だけ抜き出しています)。

text
exports[`セール中の表示 1`] = `
<DocumentFragment>
  <div
    class="price-tag price-tag--sale"
  >
    <span
      class="price-tag__name"
    >
      猫用ブラシ
    </span>
    <span
      class="price-tag__price"
    >
      1,480円
    </span>
    <span
      class="price-tag__badge"
    >
      セール中
    </span>
  </div>
</DocumentFragment>
`;

Vitest のスナップショットのガイドでは、このファイルをコードと一緒にコミットし、コードレビューで確かめるように勧めています。記録がリポジトリに残っていないと、次の実行で比べる相手がありません。

表示が変わると、差分つきでテストが落ちる

コンポーネントのバッジを、<span className="badge">SALE</span> に書き換えて、もう一度 npx vitest run を実行しました。「セール中の表示」が落ち、変わった行が -(記録)と +(今回の描画)で示されます(出力は差分の部分だけを抜き出しています)。

text
 FAIL  src/PriceTag.test.tsx > セール中の表示
Error: Snapshot `セール中の表示 1` mismatched

- Expected
+ Received

@@ -11,11 +11,11 @@
        class="price-tag__price"
      >
        1,480円
      </span>
      <span
-       class="price-tag__badge"
+       class="badge"
      >
-       セール中
+       SALE
      </span>
    </div>
  </DocumentFragment>

バッジを出さない「通常の価格の表示」は、そのまま通りました。終了コードは 1 で、スナップショットのファイルは書き換わっていません。テストが落ちたら、この差分を見て、意図した変更なのか、うっかり変えてしまったのかを判断します。

意図した変更なら -u で記録を更新する

差分が意図どおりなら、-u(--update)を付けて実行すると、記録が今の描画結果に置き換わります。

text
$ npx vitest run -u

 RUN  v5.1.0 <project>


  Snapshots  1 updated 
 Test Files  1 passed (1)
      Tests  2 passed (2)

更新したあとの .snap には class="badge" と SALE が入り、-u なしの実行も通るようになりました。ガイドによると、ウォッチモードでは、ターミナルで u キーを押しても失敗したスナップショットを更新できます。

注意

公式の設定の説明によると、-u は変わったスナップショットをすべて今の描画結果で上書きし、使われなくなった記録も消します。差分を見ないまま付けると、本当に直すべき表示の崩れまで「正しい記録」として残ってしまいます。更新したら、.snap の変更もコミットの前に確かめてください。

CI では、記録がないだけでも落ちる

Vitest は、環境変数 CI が設定されているときは、スナップショットを書き込みません。設定項目 update の説明によると、何も指定しない場合、ローカルでは新しいスナップショットだけを書き、CI では何も書かずに、差分・記録のないスナップショット・使われなくなったスナップショットのどれでも失敗します。

これを確かめるため、新しいテスト「0円の表示」を足し、.snap に記録がない状態で CI=true を付けて実行しました。出力は一部を省いています。

text
$ CI=true npx vitest run

 FAIL  src/PriceTag.test.tsx > 0円の表示
Error: Snapshot `0円の表示 1` mismatched
 ❯ src/PriceTag.test.tsx:17:24

  Snapshots  1 failed
 Test Files  1 failed (1)
      Tests  1 failed | 2 passed (3)

表示が変わったときと同じ mismatched のエラーですが、差分は出ません。.snap にも「0円の表示」は書かれていませんでした。CI を付けずに実行すると「1 written」となって記録されたので、新しいテストを足したら、ローカルで一度実行して .snap もコミットに含めます。

テストを消したら、使われない記録も消す

今度は、足した「0円の表示」のテストを消して実行しました。npx vitest run では、テストは通り、使われなくなった記録(obsolete)があると表示されるだけです(出力は最後の集計の部分です)。

text
  Snapshots  1 obsolete
             ↳ src/PriceTag.test.tsx
               · 0円の表示 1

 Test Files  1 passed (1)
      Tests  2 passed (2)

同じ状態で CI=true を付けると、テストは全部通っているのに、テストファイルが失敗扱いになり、終了コードは 1 でした(エラーの部分だけを抜き出しています)。

text
 FAIL  src/PriceTag.test.tsx [ src/PriceTag.test.tsx ]
Error: Obsolete snapshots found when no snapshot update is expected.
· 0円の表示 1

-u を付けて実行すると「1 removed」と表示され、.snap から「0円の表示」の記録が消えました。テストの名前を変えたときも、古い名前の記録が同じように残ります(ガイドの CI の節に書かれています)。

見たいところだけをインラインスナップショットで記録する

コンポーネント全体を記録すると、関係のない部分の変更でもテストが落ちます。価格の書き方だけを見張りたいなら、その部分だけを toMatchInlineSnapshot() に渡す方法もあります。引数を空にして実行すると、Vitest がテストファイルそのものに記録を書き込みます。

tsx
// src/PriceTagInline.test.tsx(実行する前)
import { render, screen } from '@testing-library/react';
import { expect, test } from 'vitest';
import { PriceTag } from './PriceTag';

test('セール中の価格とバッジ', () => {
  const { container } = render(<PriceTag name="猫用ブラシ" price={1480} onSale />);
  expect(container.querySelector('.price-tag__price')?.textContent).toMatchInlineSnapshot();
  expect(screen.getByText('SALE')).toMatchInlineSnapshot();
});

実行したあとのテストファイルは、次のように書き換わっていました。

tsx
// src/PriceTagInline.test.tsx(実行したあと。import の3行は同じなので省いています)
test('セール中の価格とバッジ', () => {
  const { container } = render(<PriceTag name="猫用ブラシ" price={1480} onSale />);
  expect(container.querySelector('.price-tag__price')?.textContent).toMatchInlineSnapshot(`"1,480円"`);
  expect(screen.getByText('SALE')).toMatchInlineSnapshot(`
    <span
      class="badge"
    >
      SALE
    </span>
  `);
});

この状態で、コンポーネントの価格の書き方を toLocaleString('ja-JP', { style: 'currency', currency: 'JPY' }) に変えると、1つ目の記録で落ちました(エラーの部分だけを抜き出しています)。

text
Error: Snapshot `セール中の価格とバッジ 1` mismatched

Expected: ""1,480円""
Received: ""¥1,480""

期待する値がテストの中に見えるので、別のファイルを開かずに何を確かめているテストなのかが分かります。

useId の値で落ちるときは、シリアライザーで置き換える

useId() でラベルと入力欄を結びつけるコンポーネントを記録すると、.snap に for="_r_0_" や id="_r_0_" のような値が入りました。

tsx
// src/Field.tsx
import { useId } from 'react';

export function EmailField() {
  const id = useId();
  return (
    <p>
      <label htmlFor={id}>メールアドレス</label>
      <input id={id} type="email" />
    </p>
  );
}

困るのは、この値がテストの並びで変わることです。同じテストファイルの、このテストより前に、EmailField を描画するだけの別のテストを足したところ、表示は何も変えていないのに、スナップショットが落ちました(差分の部分だけを抜き出しています)。

text
 FAIL  src/Field.test.tsx > メールアドレスの欄
Error: Snapshot `メールアドレスの欄 1` mismatched

- Expected
+ Received

  <DocumentFragment>
    <p>
      <label
-       for="_r_0_"
+       for="_r_1_"
      >
        メールアドレス
      </label>
      <input
-       id="_r_0_"
+       id="_r_1_"
        type="email"
      />
    </p>
  </DocumentFragment>

こうした「表示の変化ではない差分」は、expect.addSnapshotSerializer() で記録の書き方を変えて取り除けます。次の例では、_r_0_ の形の文字列を、記録するときだけ [useId] に置き換えています。

tsx
// src/Field.test.tsx
import { render } from '@testing-library/react';
import { expect, test } from 'vitest';
import { EmailField } from './Field';

// useId が作る「_r_0_」のような値を、決まった文字に置き換えて記録する
expect.addSnapshotSerializer({
  test: (val) => typeof val === 'string' && /_r_[0-9a-z]+_/.test(val),
  serialize: (val: string) => `"${val.replace(/_r_[0-9a-z]+_/g, '[useId]')}"`,
});

test('メールアドレスの欄', () => {
  const { asFragment } = render(<EmailField />);
  expect(asFragment()).toMatchSnapshot();
});

古い .snap を消してから実行すると、.snap には for="[useId]" と id="[useId]" が入りました。このテストより前に別のテストを足しても、CI=true を付けても、テストは通りました。

スナップショットに記録されるのは DOM の文字列なので、CSS だけの変更には気づけません。コンポーネントで import './PriceTag.css'; と読み込んでいる CSS ファイルを .badge { display: none; } に変え、バッジが見えなくなるようにしても、テストはそのまま通りました。見た目そのものを比べたい場合について、ガイドでは、ブラウザーモードの toMatchScreenshot() で画像を比べる方法を紹介しています。

​Posted by 86