Bunのbun testでスナップショットテストを書く方法
関数が返す大きなオブジェクトや、画面に出す文字列を、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)。
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回呼んでいます。
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つのスナップショットが保存されたことが分かります。
$ 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 です。中身はこうなっていました。
// 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 に変わりました。
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 の行を、次のように書き換えました。
lines: items.map((i) => `${i.name}(${i.qty}点)${i.price * i.qty}円`),
もう一度 bun test を動かすと、1件が失敗し、保存した内容(-)と今回の値(+)の差分が出ました。
$ 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)を付けて動かし、保存した内容を今回の値で書き直します。
$ 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行だけでした。
$ 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)で試しました。
// 金額を3桁ごとに区切って「円」を付ける
export const yen = (n: number) => `${n.toLocaleString("ja-JP")}円`;
テストでは、toMatchInlineSnapshot() も toThrowErrorMatchingInlineSnapshot() も、引数なしで呼びます。
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)。
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 と作成日時を返します。
// 注文を作る。id と作成日時は呼ぶたびに変わる
export function createOrder(customer: string) {
return {
id: crypto.randomUUID(),
customer,
status: "受付",
createdAt: new Date().toISOString(),
};
}
戻り値をそのままスナップショットにするテスト(そのまま撮る)と、toMatchSnapshot() にプロパティのマッチャーを渡すテストを並べました。マッチャーを渡した項目は、値そのものではなく、expect.any(String)(文字列であること)や expect.stringMatching()(正規表現に合うこと)で比べます。
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 が入っていました。
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 が前回と違うので失敗し、マッチャーを渡したほうは通りました。
$ 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 を付けて動かしました。
$ 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 ファイルの中には、古い名前の記録も残っていました。
$ 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 の記録は消えました。
$ 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 を付けて動かしました。
$ 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]
$ 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 の変化を確かめるのが安全です。





