Bunのbun testでスナップショットテストを書く方法

​​Bun​TypeScript,テスト

関数が返す大きなオブジェクトや、画面に出す文字列を、1項目ずつ expect で書かずにまとめて確かめたいときは、スナップショットテストが使えます。Bun の bun test では toMatchSnapshot() を呼ぶだけで、1回目の結果がファイルに保存され、2回目からはその内容と比べられます。リファクタリングの前後で出力が変わっていないかを確かめる、いわゆる回帰テストに向いています。

検証環境で動かすと、--update-snapshots の付け方しだいで、ほかのテストの記録が消えることもありました。その様子も載せています。

補足

検証環境は Ubuntu 24.04(x86_64)、Bun 1.4.4 です。フォルダには TypeScript のファイルだけを置き、package.json も設定ファイルもない状態で動かしました。React などのコンポーネントのスナップショット、--parallel、Windows と macOS は試していません。Bun の公式ドキュメントは、検証に使った版(タグ bun-v1.4.4)の元ファイルを GitHub で確認し、リンクもそこに張っています。

toMatchSnapshot() で、結果をファイルに保存する

テストする関数は、カートの中身から明細の行と合計を作る summarize です(src/order.ts)。

ts
export type Item = { name: string; price: number; qty: number };

// カートの中身から、明細の行と合計を作る
export function summarize(items: Item[]) {
  const subtotal = items.reduce((sum, i) => sum + i.price * i.qty, 0);
  const tax = Math.floor(subtotal * 0.1);
  return {
    lines: items.map((i) => `${i.name} × ${i.qty}  ${i.price * i.qty}円`),
    subtotal,
    tax,
    total: subtotal + tax,
  };
}

テストでは、確かめたい値を expect() に渡し、toMatchSnapshot() を呼びます。期待する値は書きません。2つ目のテストでは、1つのテストの中で2回呼んでいます。

ts
import { describe, expect, test } from "bun:test";
import { summarize } from "./order";

describe("summarize", () => {
  test("2つの商品の明細と合計", () => {
    const result = summarize([
      { name: "ノート", price: 180, qty: 3 },
      { name: "ボールペン", price: 120, qty: 2 },
    ]);
    expect(result).toMatchSnapshot();
  });

  test("空のカート", () => {
    expect(summarize([])).toMatchSnapshot();
    expect(summarize([]).lines).toMatchSnapshot();
  });
});

1回目の bun test では、比べる相手がまだないので、どのテストも通ります。集計の行に snapshots: +3 added と出て、3つのスナップショットが保存されたことが分かります。

text
$ bun test ./src/order.test.ts
bun test v1.4.4 (38afee6c8)

src/order.test.ts:
(pass) summarize > 2つの商品の明細と合計 [0.72ms]
(pass) summarize > 空のカート [0.10ms]

 2 pass
 0 fail
snapshots: +3 added
 3 expect() calls
Ran 2 tests across 1 file. [5.00ms]

保存先は、テストファイルと同じフォルダに作られた __snapshots__/order.test.ts.snap です。中身はこうなっていました。

text
// Bun Snapshot v1, https://bun.sh/docs/test/snapshots

exports[`summarize 2つの商品の明細と合計 1`] = `
{
  "lines": [
    "ノート × 3  540円",
    "ボールペン × 2  240円",
  ],
  "subtotal": 780,
  "tax": 78,
  "total": 858,
}
`;

exports[`summarize 空のカート 1`] = `
{
  "lines": [],
  "subtotal": 0,
  "tax": 0,
  "total": 0,
}
`;

exports[`summarize 空のカート 2`] = `[]`;

それぞれの記録は、describe の名前とテストの名前に、そのテストの中で何回目の toMatchSnapshot() かを表す番号を付けた名前で保存されます。空のカート では、1回目の呼び出しが 空のカート 1、2回目が 空のカート 2 になりました。

2回目の bun test では、保存した内容と比べます。集計の行は 3 snapshots に変わりました。

text
 2 pass
 0 fail
 3 snapshots, 3 expect() calls
Ran 2 tests across 1 file. [5.00ms]

この .snap ファイルは、テストファイルと一緒に Git にコミットしておくものです。公式ドキュメントにある、スナップショットの変更を見直してコミットする手順でも、更新したスナップショットを git add してコミットしています。

出力が変わると、差分を出して失敗する

明細の行の書き方を「ノート × 3 540円」から「ノート(3点)540円」に変えてみます。src/order.ts の lines の行を、次のように書き換えました。

ts

lines: items.map((i) => `${i.name}(${i.qty}点)${i.price * i.qty}円`),

もう一度 bun test を動かすと、1件が失敗し、保存した内容(-)と今回の値(+)の差分が出ました。

text
$ bun test ./src/order.test.ts
bun test v1.4.4 (38afee6c8)

src/order.test.ts:
(ソースコードの抜粋は省略)
error: expect(received).toMatchSnapshot(expected)

  
  {
    "lines": [
-     "ノート × 3  540円",
-     "ボールペン × 2  240円",
+     "ノート(3点)540円",
+     "ボールペン(2点)240円",
    ],
    "subtotal": 780,
    "tax": 78,
    "total": 858,
  }
  

- Expected  - 2
+ Received  + 2

      at <anonymous> (/path/to/snap-app/src/order.test.ts:10:20)
(fail) summarize > 2つの商品の明細と合計 [0.56ms]
(pass) summarize > 空のカート [0.05ms]

 1 pass
 1 fail
snapshots: 2 passed, 1 failed
 3 expect() calls
Ran 2 tests across 1 file. [4.00ms]

(at の行のフォルダのパスは、検証環境のものを /path/to/ に置き換えています)

失敗しても、.snap ファイルは書き換わりません。変わったのが意図した変更なら、--update-snapshots(短く書くと -u)を付けて動かし、保存した内容を今回の値で書き直します。

text
$ bun test --update-snapshots ./src/order.test.ts
bun test v1.4.4 (38afee6c8)

src/order.test.ts:
(pass) summarize > 2つの商品の明細と合計 [0.50ms]
(pass) summarize > 空のカート [0.04ms]

 2 pass
 0 fail
snapshots: +3 added
 3 expect() calls
Ran 2 tests across 1 file. [4.00ms]

変わったのは1件だけですが、集計には +3 added と出ました。書き直す前の .snap ファイルと diff で比べると、実際に変わったのは、明細の2行だけでした。

text
$ diff ../old.snap src/__snapshots__/order.test.ts.snap
6,7c6,7
<     "ノート × 3  540円",
<     "ボールペン × 2  240円",
---
>     "ノート(3点)540円",
>     "ボールペン(2点)240円",

--update-snapshots は、差分が意図したものかを確かめてから付けます。思っていない変更だったなら、直すのは .snap ではなくコードの側です。

インラインスナップショットは、テストファイルに書き込まれる

短い文字列や小さな配列なら、toMatchInlineSnapshot() を使うと、保存した値がテストファイルの中に書き込まれます。別のファイルを開かずに、期待する値をテストの横で読めます。投げられたエラーのメッセージを保存するときは、toThrowErrorMatchingInlineSnapshot() を使います。

金額を3桁ごとに区切る関数 yen(src/price.ts)で試しました。

ts
// 金額を3桁ごとに区切って「円」を付ける
export const yen = (n: number) => `${n.toLocaleString("ja-JP")}円`;

テストでは、toMatchInlineSnapshot() も toThrowErrorMatchingInlineSnapshot() も、引数なしで呼びます。

ts
import { expect, test } from "bun:test";
import { yen } from "./price";

test("3桁ごとに区切る", () => {
  expect(yen(1234567)).toMatchInlineSnapshot();
  expect([yen(0), yen(999), yen(1000)]).toMatchInlineSnapshot();
});

test("負の金額はエラー", () => {
  expect(() => {
    throw new Error("金額が負です: -1");
  }).toThrowErrorMatchingInlineSnapshot();
});

bun test ./src/price.test.ts を1回動かすと、2件とも通り、snapshots: +3 added と出ました。テストファイルは、次のように書き換わっていました(動かす前のファイルとの diff -u)。

diff
 test("3桁ごとに区切る", () => {
-  expect(yen(1234567)).toMatchInlineSnapshot();
-  expect([yen(0), yen(999), yen(1000)]).toMatchInlineSnapshot();
+  expect(yen(1234567)).toMatchInlineSnapshot(`"1,234,567円"`);
+  expect([yen(0), yen(999), yen(1000)]).toMatchInlineSnapshot(`
+    [
+      "0円",
+      "999円",
+      "1,000円",
+    ]
+  `);
 });
 
 test("負の金額はエラー", () => {
   expect(() => {
     throw new Error("金額が負です: -1");
-  }).toThrowErrorMatchingInlineSnapshot();
+  }).toThrowErrorMatchingInlineSnapshot(`"金額が負です: -1"`);
 });

文字列はダブルクォートで囲まれた形で、複数行の値はインデントを付けた形で入ります。もう一度動かすと、書き込まれた値と比べて、2件とも通りました。

公式ドキュメントの、スナップショットの使い方のおすすめでは、スナップショットを小さく保つことが勧められています。ページ全体のように何千行にもなるスナップショットは、変わったときに見直すのが難しいためです。

毎回変わる ID や日時は、プロパティのマッチャーで値の形だけ確かめる

注文を作る createOrder(src/order-id.ts)は、呼ぶたびに違う id と作成日時を返します。

ts
// 注文を作る。id と作成日時は呼ぶたびに変わる
export function createOrder(customer: string) {
  return {
    id: crypto.randomUUID(),
    customer,
    status: "受付",
    createdAt: new Date().toISOString(),
  };
}

戻り値をそのままスナップショットにするテスト(そのまま撮る)と、toMatchSnapshot() にプロパティのマッチャーを渡すテストを並べました。マッチャーを渡した項目は、値そのものではなく、expect.any(String)(文字列であること)や expect.stringMatching()(正規表現に合うこと)で比べます。

ts
import { expect, test } from "bun:test";
import { createOrder } from "./order-id";

test("そのまま撮る", () => {
  expect(createOrder("山田")).toMatchSnapshot();
});

test("変わる値は型だけを確かめる", () => {
  expect(createOrder("山田")).toMatchSnapshot({
    id: expect.any(String),
    createdAt: expect.stringMatching(/^\d{4}-\d{2}-\d{2}T/),
  });
});

1回目に保存された .snap ファイルでは、マッチャーを渡した項目だけ、値の代わりに Any<String> や StringMatching が入っていました。

text
exports[`そのまま撮る 1`] = `
{
  "createdAt": "2026-11-15T08:13:17.186Z",
  "customer": "山田",
  "id": "6d205929-bfa5-4209-bcdd-46aad3155c45",
  "status": "受付",
}
`;

exports[`変わる値は型だけを確かめる 1`] = `
{
  "createdAt": StringMatching /^\\d{4}-\\d{2}-\\d{2}T/,
  "customer": "山田",
  "id": Any<String>,
  "status": "受付",
}
`;

2回目を動かすと、そのまま撮る のテストは id と createdAt が前回と違うので失敗し、マッチャーを渡したほうは通りました。

text
$ bun test ./src/order-id.test.ts
(ソースコードの抜粋と集計の行は省略)
error: expect(received).toMatchSnapshot(expected)

  
  {
-   "createdAt": "2026-11-15T08:13:17.186Z",
+   "createdAt": "2026-11-15T08:13:17.195Z",
    "customer": "山田",
-   "id": "6d205929-bfa5-4209-bcdd-46aad3155c45",
+   "id": "0ace7f39-c260-43e7-b409-535f70409013",
    "status": "受付",
  }
  

- Expected  - 2
+ Received  + 2

      at <anonymous> (/path/to/snap-app/src/order-id.test.ts:5:29)
(fail) そのまま撮る [0.63ms]
(pass) 変わる値は型だけを確かめる [0.24ms]

マッチャーを渡したほうでも、customer と status は値がそのまま保存されています。

CI では、新しいスナップショットを作らずに失敗する

ここまでのように、手元で動かすと、比べる相手のない toMatchSnapshot() は値を保存して通ります。公式ドキュメントの、スナップショットの更新についての説明によると、CI の環境では --update-snapshots を付けない限り、新しいスナップショットを書き込みません。

src/order.test.ts に 1つの商品 というテストを足し、.snap に記録がない状態で、環境変数 CI=true を付けて動かしました。

text
$ CI=true bun test ./src/order.test.ts
bun test v1.4.4 (38afee6c8)

src/order.test.ts:
(pass) summarize > 2つの商品の明細と合計 [0.63ms]
(pass) summarize > 空のカート [0.05ms]
(ソースコードの抜粋は省略)
error: Snapshot creation is disabled in CI environments unless --update-snapshots is used
To override, set the environment variable CI=false.

Snapshot name: "1つの商品 1"
Received: 
{
  "lines": [
    "消しゴム(1点)80円",
  ],
  "subtotal": 80,
  "tax": 8,
  "total": 88,
}

      at <anonymous> (/path/to/snap-app/src/order.test.ts:20:60)
(fail) 1つの商品 [0.25ms]

 2 pass
 1 fail
 4 snapshots, 4 expect() calls
Ran 3 tests across 1 file. [5.00ms]

足したテストは失敗し、.snap ファイルは動かす前と同じままでした。CI の代わりに GITHUB_ACTIONS=true を付けたときも、同じエラーで失敗しました。インラインスナップショットも同じで、CI=true では Inline snapshot creation is disabled in CI environments というエラーになり、テストファイルは書き換わりませんでした。CI=true を付けたままでも、--update-snapshots を付けると、記録が書き込まれて通りました。

環境変数 CI=true が設定される CI では、手元で作ったスナップショットをコミットし忘れると、このように落ちます。新しいテストを足したら、.snap ファイルや書き換わったテストファイルも一緒にコミットします。

テストの名前を変えると、古い記録が残る

スナップショットは名前で探すので、テストの名前を変えると、新しい名前で記録が作り直されます。1つの商品 を 商品が1つ に変えて動かしたところ、snapshots: 3 passed, 1 added と出て、テストはすべて通りました。ところが .snap ファイルの中には、古い名前の記録も残っていました。

text
$ grep -n '^exports' src/__snapshots__/order.test.ts.snap
3:exports[`summarize 2つの商品の明細と合計 1`] = `
15:exports[`summarize 空のカート 1`] = `
24:exports[`summarize 空のカート 2`] = `[]`;
26:exports[`1つの商品 1`] = `
37:exports[`商品が1つ 1`] = `

使われなくなった記録があることを知らせる表示は、出力にはありませんでした。--update-snapshots を付けて動かすと、ファイル全体が書き直され、1つの商品 1 の記録は消えました。

text
$ grep -n '^exports' src/__snapshots__/order.test.ts.snap
3:exports[`summarize 2つの商品の明細と合計 1`] = `
15:exports[`summarize 空のカート 1`] = `
24:exports[`summarize 空のカート 2`] = `[]`;
26:exports[`商品が1つ 1`] = `

-t で絞って更新すると、動かさなかったテストの記録が消える

--update-snapshots がファイル全体を書き直すことは、テストを絞って動かすときに困ることがあります。-t(テスト名で絞り込むオプション)で 空のカート だけを選び、--update-snapshots を付けて動かしました。

text
$ bun test --update-snapshots -t 空のカート ./src/order.test.ts
bun test v1.4.4 (38afee6c8)

src/order.test.ts:
(pass) summarize > 空のカート [0.35ms]

 1 pass
 2 filtered out
 0 fail
snapshots: +2 added
 2 expect() calls
Ran 1 test across 1 file. [4.00ms]
text
$ grep -n '^exports' src/__snapshots__/order.test.ts.snap
3:exports[`summarize 空のカート 1`] = `
12:exports[`summarize 空のカート 2`] = `[]`;

続けて何も付けずに bun test を動かすと、snapshots: 2 passed, 2 added と出て、消えた2件は今の結果で記録し直され、テストは通りました。

注意

-t で絞って --update-snapshots を付けると、絞り込みで外れたテスト(ここでは 2つの商品の明細と合計 と 商品が1つ)の記録は、.snap ファイルから消えます。次に手元で動かすまでに出力が変わっていても、失敗にはならず、新しい記録として保存されます。更新するときは、ファイル単位で全部のテストを動かしてから、git diff で .snap の変化を確かめるのが安全です。

​Posted by 86