Reactのテストは、見た目のクラス名ではなく利用者に見えるもので書きます。Vitestで要素の取得方法と、テストの分け方を決めます。
前回: /tasks/3 を直接開くと404 — ルーティング 作業場所はVMの中(Ubuntu)です。前回まで作ってきた
~/react-demo/の続きです。この記事では、ブラウザを1度も開きません。
CI/CDの回で、こういう状態を作りました。
push すると、GitHub が勝手にテストを走らせて、通ったか教えてくれる。
ただし、あれはバックエンド(~/server)の話でした。node:test でテストを5本書いて、npm test で走らせて、GitHub Actions に載せました。
一方、~/react-demo/ にはテストが1本もありません。
そして、たぶんあなたは、それを不自然だと思っていません。 フロントはブラウザを開けば見えてしまうからです。追加ボタンを押して、行が増えれば、それで確認は終わりです。
この記事は、まずそこ(なぜフロントのテストは後回しになるのか)から始めます。 そのうえで、「何をテストすると割に合うのか」を決めて、割に合うものだけを2本書きます。
全部はやりません。 テストには3つの種類があり、この回で扱うのは真ん中の1つだけです。やらないものについては、やらない理由を書きます。
似たタイトルの記事があります。役割が違います。 この記事はテストを1本目から書くを扱います。Reactのテストの書き方|実装変更で壊れないテストにする は書いたテストが実装変更で落ちるようになったときの直し方を扱います。
対象レベル: 初級 / 区分: 必修
この記事でわかること
- フロントのテストが後回しになるのは、怠けているからではないこと。見た目には「正解」が無く、変化も速いので、素直に書くと壊れやすいテストばかりが増える
classNameや内部の状態でテストしてはいけないこと。実装を変えただけで落ちるテストは、直すことが仕事になり、そのうちテストごと消される- Jest ではなく Vitest を選ぶ理由。Vite の設定をそのまま使えるので、設定ファイルが増えない。JSXの変換方法を2回書かずに済む
node --testとvitestが別物なのは、道具の好みではなく、動く場所が違うからだということ。Node にはそもそもdocumentが無い- E2E(Playwright など)を今この段階で入れると、何が起きるか。繋ぐ先がまだ無い
この記事でやること
- Vitest と React Testing Library を
~/react-demo/に入れ、vite.config.jsに4行だけ足す - コンポーネントのテストを2本書く(追加すると一覧に増える / 空では追加できない)
- アプリをわざと壊して、テストが落ちることと、失敗したときの出力の読み方を確かめる
- watch モードで、保存するたびに自動で走る状態にする
- CIで、バックエンドとフロントの両方を走らせる書き方を用意する
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| テストランナー | テストのファイルを探して、実行して、結果をまとめるプログラム。node --test や vitest がこれ |
| アサーション | 「こうなっているはずだ」と書いて、違ったら失敗にする1行。assert や expect |
| ユニットテスト | 関数1つを、単体で試す |
| コンポーネントテスト | 画面の部品を実際に描画して、操作して、見えるものを確かめる |
| E2Eテスト | 本物のブラウザで、本物のサーバー相手に、端から端まで通して試す |
| jsdom | Node.js の中に、ブラウザのDOMだけを真似して作るライブラリ。画面は出ない |
| Vitest | Vite の設定をそのまま使えるテストランナー |
| React Testing Library(RTL) | 「利用者から見える形」でコンポーネントを触るための道具。役割や文字で要素を探す |
| クエリ | RTL で要素を探す関数。getByRole getByText など |
| ロール(role) | その要素が何であるか。ボタン、入力欄、見出し、リスト項目など |
| アクセシブルな名前 | その要素が、支援技術から何と呼ばれるか。ボタンなら普通は書いてある文字 |
| cleanup | 1本のテストが終わったら、描画したものを片づけること。しないと次のテストに残る |
| watch モード | ファイルを保存するたびに、関係するテストだけ自動で走り直す状態 |
① なぜ、フロントのテストは後回しになるのか
まず、正直に理由を並べます。 「テストは大事です」で始まる記事は、ここを飛ばします。飛ばすと、書いたテストが1か月で邪魔になります。
| 理由 | 中身 |
|---|---|
| 見た目には「正解」が無い | normalizeTitle(" 牛乳 ") の正解は "牛乳" の1つだけ。「ボタンは青がよい」に正解はありません |
| 変化が速い | デザインの変更は毎週起きます。見た目に紐づけたテストは、そのたびに全部落ちます |
| 目で見えてしまう | ブラウザを開けば分かるので、書かなくても今日は困りません |
| 書き方を覚えることが多い | DOM を用意して、描画して、クリックを真似して…と、バックエンドより一手間多い |
バックエンドのテストが書きやすかったのは、対象が「入れたら出てくる」関数だったからです。CI/CDの回で、こう書きました。
テストが書きにくいコードは、たいてい「1つの関数が、いろいろやりすぎている」だけです。
フロントでは、それに加えて「そもそもテストする価値が薄いもの」が大量にあります。 そこを見分けるのが、この節です。
何をテストすると割に合うのか
判断基準は1つです。
「それが壊れたとき、自分は気づけるか」
気づけるものは、書かなくていい。気づけないものだけ書く。
| 割に合う | 割に合わない |
|---|---|
| 条件分岐(空なら追加できない、0件なら別の文言が出る) | 色・余白・フォント(見れば分かる。そして毎週変わる) |
| 計算(残り件数、合計金額、税) | 静的な文言だけの部分(変えていないなら壊れない) |
| 一度壊れた場所(同じ壊れ方は必ず再発する) | ライブラリ自体の動作(React が動くことは React の仕事) |
| 間違えると取り返しがつかない操作(削除、支払い) | useState を使っていること(実装の詳細) |
表の右側の共通点は、「実装を変えただけで落ちる」ものです。
表の左側の共通点は、「利用者が困る」ものです。空のタスクが増えてしまったら、利用者は困ります。 ボタンの余白が2px変わっても、誰も困りません。
この記事で書くテストは2本だけです。少ないと思うかもしれませんが、
~/react-demo/に「利用者が困る条件分岐」は、いまそれくらいしかありません。 数を目標にした瞬間に、割に合わないテストが混ざり始めます。
② テストの種類を、先に分ける
「テストを書く」と言ったとき、指しているものが3つあります。 混ぜたまま入門記事を読むと、必要のない道具まで入れることになります。
| 種類 | 何を試すか | 動く場所 | 速さ | 壊れやすさ | 道具 |
|---|---|---|---|---|---|
| ユニット | 関数1つ。外に触らないもの | Node の中 | とても速い(ミリ秒) | 壊れにくい | node:test / Vitest |
| コンポーネント | 部品や画面を描画して、操作する | Node の中(DOMは偽物) | 速い(数百ミリ秒) | ふつう | Vitest + RTL |
| E2E | 本物のブラウザで、サーバーも動かして通す | 本物のブラウザ | 遅い(数秒〜数十秒) | 壊れやすい | Playwright / Cypress |
上から下へ行くほど、「本物に近い」代わりに「遅く、壊れやすく、原因が分かりにくい」です。
だから、数のバランスはこうなります。
E2E ← 数本。一番大事な流れだけ
コンポーネント ← ここが厚い
ユニットテスト ← 一番多い。速いので何本あってもいい
この記事で扱うのは、真ん中だけです。
- ユニットは、もうやりました。 CI/CDの回の
normalizeTitleがそれです。やり方は同じです - E2Eは入れません。 理由は⑨に書きます。「難しいから」ではなく、「繋ぐ先がまだ無いから」です
「コンポーネントテスト」と「ユニットテスト」の境目は、実はあいまいです。 人によっては、コンポーネント1つのテストも「ユニットテスト」と呼びます。 言葉の争いに意味はありません。大事なのは「DOMが要るか、要らないか」で、そこが道具の分かれ目になります。
③ Vitest を入れる — なぜ Jest ではないのか
フロントのテストといえば Jest、というのは長いあいだ本当でした。いまでも動きますし、書き方もほとんど同じです。
それでもこの記事が Vitest を選ぶ理由は、1つだけです。
設定ファイルが増えないから。
何が問題なのか
~/react-demo/ のコードは、そのままでは Node.js が読めません。
return <li>{task.title}</li>;
これは JavaScript ではありません。 ビルドツールの回でやったとおり、JSX は変換して初めて動きます。 その変換をやっているのが Vite です。
つまり、テストを走らせる側も「JSXを変換する方法」を知っている必要があります。
| Jest | Vitest | |
|---|---|---|
| JSXの変換 | babel か SWC の設定を、自分でもう一度書く | vite.config.js をそのまま使う |
| 設定ファイル | jest.config.js が1つ増える | 増えない。既存のファイルに数行足すだけ |
import の書き方 | 歴史的に CommonJS 前提で、ESM は追加設定が要ることがある | 最初から ESM |
| エイリアスや環境変数 | Jest 側にも同じ設定を書く | Vite に書いたものがそのまま効く |
書き方(describe / expect) | — | ほぼ同じ。Jest の記事がそのまま読める |
問題は「2回書く」ことです。 Vite 側と Jest 側で、変換の設定が2箇所に分かれます。 そして片方だけ直したときに、「開発では動くのにテストだけ落ちる」が起きます。
Jest が悪いわけではありません。 Jest は Vite より前からあり、Vite を使っていないプロジェクトも山ほどあります。 ここでの判断は「すでに Vite があるなら、同じことを2回書く理由がない」というだけです。道具は、いま持っているものに合わせて選びます。
入れる
VMの中で、~/react-demo/ に入ります。
README.md eslint.config.js index.html node_modules package.json package-lock.json public src vite.config.js
vite.config.js があることを確認してください。 これがこの先の主役です。
5〜6個も入れることになったので、1つずつ何なのか書きます。
| 入れたもの | 役割 |
|---|---|
vitest | テストランナー本体 |
jsdom | Node の中に、DOM だけを作る。 これが無いと document が存在しません |
@testing-library/react | React を描画して、RTL のクエリで触れるようにする |
@testing-library/dom | クエリの本体。上のものが別パッケージとして要求するので、明示的に入れます |
@testing-library/jest-dom | toBeInTheDocument() のような、DOM向けの expect を足す |
@testing-library/user-event | 人の操作を真似る(クリック、入力)。後述しますが fireEvent より本物に近い |
-Dは--save-devの略です。 npmの回でやった「開発のときだけ要るもの」です。利用者に配るdist/には1バイトも入りません。
入ったことを確認します。
vitest/3.2.4 linux-x64 node-v22.14.0
数字は違って構いません。 3 系が入っていれば、この記事のとおりに進みます。
vite.config.js(丸ごと置き換え)
いまの中身は、Vite が作ったこれだけのはずです。
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
// https://vite.dev/config/
export default defineConfig({
plugins: [react()],
})
丸ごと、こう置き換えます。
import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react";
export default defineConfig({
plugins: [react()],
test: {
environment: "jsdom",
globals: true,
setupFiles: "./src/setupTests.js",
},
});
変わったのは2箇所だけです。
from "vite"をfrom "vitest/config"に変えたtest: { ... }を足した
| 書いたもの | 意味 |
|---|---|
from "vitest/config" | test: を書けるようにする版の defineConfig。 中身は Vite のものと同じで、テスト用の設定を受け付けるようになるだけ |
environment: "jsdom" | テストの間だけ、Node の中に偽物のDOMを用意する。 これが無いと document is not defined で落ちます |
globals: true | test や expect を、import せずに使えるようにする |
setupFiles | 各テストファイルの前に、必ず読み込むファイル |
plugins: [react()]は消さないでください。 JSXを変換しているのはこれです。テストのときも同じプラグインが使われます。 「設定を2回書かなくていい」というのは、具体的にはこの1行のことです。
globals: trueは、ただの手抜きではありません。 React Testing Library は、afterEachが使える環境なら、テストが終わるたびに自動で片づけ(cleanup)をします。globals: trueにしておくと、それが有効になります。falseのままだと、1本目のテストで描画したものが2本目にも残り、「同じ要素が2つ見つかる」という不可解な失敗が起きます。⑩に実際の症状を書きました。
src/setupTests.js(新規)
import "@testing-library/jest-dom/vitest";
1行です。 これで expect(...).toBeInTheDocument() のような書き方ができるようになります。
素の Vitest の expect は、DOM のことを知りません。 「この要素は画面にあるか」「このボタンは押せない状態か」といった判定は、このライブラリが後付けしています。
ファイル名に
.test.を含めないでください。setupTests.jsはテストファイルではありません。 Vitest がテストとして拾うのは*.test.js/*.test.jsx(や.spec.)という形の名前だけです。setup.test.jsなどにすると、中身が空のテストファイルとして実行され、「テストが0件」と怒られます。
package.json の scripts
"scripts" の中を、こうします。
"scripts": {
"dev": "vite",
"build": "vite build",
"lint": "eslint .",
"preview": "vite preview",
"test": "vitest run",
"test:watch": "vitest"
},
dev から lint までは元からあったものです。 足したのは下の2行だけです。
testがvitestではなくvitest runになっているのが、この記事で一番間違えやすいところです。vitestは、走り終わったあとも終了せず、ファイルの変更を待ち続けます(watch モード)。便利ですが、CIで実行すると永遠に終わりません。vitest runは、1回走って、結果を返して、終わります。 CI/CDの回で「ワークフローにはnpm testとだけ書く」としたのは、こういう変更をワークフロー側に波及させないためでした。
④ React Testing Library — 何を変える道具なのか
テストを書く前に、ここを読んでください。 この節を飛ばすと、動くけれど無価値なテストが書けてしまいます。
まず、書いてはいけない書き方を見る
~/react-demo/ の TaskItem には className={task.done ? "done" : ""} があります。 これを使ったテストは、こう書けてしまいます。
// ❌ こう書いてはいけない
const { container } = render(<App />);
expect(container.querySelectorAll("li")).toHaveLength(1);
expect(container.querySelector(".done")).not.toBeNull();
動きます。通ります。 それでも、これは書いてはいけません。
| このテストが落ちる場面 | 利用者は困るか |
|---|---|
className を done から completed に変えた | 困らない(見た目は同じ) |
| CSSフレームワークに乗り換えて、クラス名が全部変わった | 困らない |
<li> を <div role="listitem"> に変えた | 困らない |
利用者が1ミリも困っていないのに、テストだけが落ちます。
これが「実装の詳細をテストする」ということです。 落ちたテストは、直さなければなりません。 ですが直しても、何も良くなりません。 アプリは最初から壊れていないからです。 こうしたテストが増えると、「テストを直すこと」が仕事になります。 そして最後には、「このテスト、いつも落ちるから消そう」になります。テストが1本も無い状態より悪いのは、ここに時間を使ってしまったぶんです。
内部の状態も同じです。 「useState の値が true になっているか」を確かめるテストを書くと、前回やったように useState を useReducer に置き換えた瞬間に落ちます。 画面の動きは1ミリも変わっていないのに、です。
RTL の考え方
React Testing Library は、この1文のために作られています。
The more your tests resemble the way your software is used, the more confidence they can give you. (テストが、実際の使われ方に似ているほど、そのテストは信頼できる)
利用者は className を見ません。 利用者が見るのは、「追加」と書かれたボタンと、画面に出ている文字です。
だから RTL のクエリは、「役割」と「見えている文字」で探します。
| 優先順位 | クエリ | 何で探すか |
|---|---|---|
| 1 | getByRole | 役割と名前。getByRole("button", { name: "追加" }) |
| 2 | getByLabelText | ラベルの文字(フォームの入力欄) |
| 3 | getByPlaceholderText | プレースホルダ |
| 4 | getByText | 画面に出ている文字そのもの |
| 最後の手段 | getByTestId | data-testid 属性。他に手が無いときだけ |
上ほど「利用者の見え方」に近く、下ほど「実装の都合」に近いです。
getByRoleが最優先なのは、それがHTMLの回の回収になっているからです。 「タグは意味を与えるもの」と書きました。<button>を使っていればrole="button"、<li>ならlistitem、<h1>ならheadingが、何も書かなくても付いています。 逆に、<div onClick={...}>でボタンを作っていると、getByRole("button")では見つかりません。 これはテストの都合ではなく、キーボードや読み上げソフトでも操作できないという実害です。 テストが書きにくいときは、たいていアクセシビリティが足りていません。
getBy / queryBy / findBy の違い
同じ「探す」でも、3種類あります。ここは必ず混乱します。
| 前置き | 見つからなかったら | 使う場面 |
|---|---|---|
getBy... | その場でエラーにする | あるはずのものを探す(ほとんどこれ) |
queryBy... | null を返す(エラーにしない) | 「無いこと」を確かめるときだけ |
findBy... | しばらく待つ(Promise を返す) | 通信のあとなど、遅れて出てくるもの |
「無いことを確かめたい」ときに getBy を使うと、探した時点でエラーになって終わります。 そこだけは queryBy です。
findBy は await が要ります。 いまは使いませんが、fetch を画面に繋いだときに必ず出てきます。
user-event と fireEvent
クリックを起こす方法も2つあります。
| 何をするか | |
|---|---|
fireEvent.click(要素) | click イベントを1つ、直接ぶつける |
userEvent.click(要素) | 人がやることを順番になぞる(ポインタを移動し、mousedown、focus、mouseup、click…) |
この記事では user-event を使います。 fireEvent だと、「実際には押せないボタン」でも押せてしまうからです。
user-event は await が要ります。 忘れると、入力していないのに次の行へ進みます。
⑤ 1本目 — タスクを追加すると、一覧に増える
src/App.test.jsx を作ります。
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import App from "./App.jsx";
test("タスクを追加すると、一覧に増える", async () => {
const user = userEvent.setup();
render(<App />);
await user.type(screen.getByRole("textbox"), "牛乳を買う");
await user.click(screen.getByRole("button", { name: "追加" }));
expect(screen.getByText("牛乳を買う")).toBeInTheDocument();
});
1行ずつ読みます。
| 書いたもの | 意味 |
|---|---|
render(<App />) | App を、jsdom の中に実際に描画する。 画面には何も出ません |
screen | 描画されたもの全体。ここからクエリで探します |
userEvent.setup() | 操作する「人」を1人用意する。 テストごとに毎回呼びます |
user.type(要素, "文字") | 1文字ずつ打ち込む。 本物のキー入力と同じ順で onChange が起きます |
getByRole("textbox") | 入力欄を、役割で探す |
getByRole("button", { name: "追加" }) | 「追加」と書かれたボタンを探す |
toBeInTheDocument() | その要素が画面にあること |
async と await が付いているのは、user.type と user.click が非同期だからです(非同期処理の回)。
{ name: "追加" }は、完全一致です。Appには「追加」「削除」「全部完了にする」「完了したものを消す」「使う人を切り替える」と、ボタンが5種類あります。 名前を付けずにgetByRole("button")と書くと、「複数見つかった」というエラーで落ちます。
getByRole("textbox")が使えているのは、TaskFormが<input type="text">だからです。 本来なら<label>を付けてgetByLabelText("やること")で探すのが正解です。ラベルが無い入力欄は、読み上げソフトでは「編集テキスト」としか読まれません。 いまは入力欄が1つしかないのでtextboxで足りていますが、2つに増えた瞬間に「複数見つかった」で落ちます。 そのとき直すのはテストではなく、<label>が無いHTMLのほうです。
走らせる
RUN v3.2.4 /home/user/react-demo
✓ src/App.test.jsx (1 test) 312ms
✓ タスクを追加すると、一覧に増える 310ms
Test Files 1 passed (1)
Tests 1 passed (1)
Start at 16:04:11
Duration 1.42s
1 passed が出れば通っています。
ブラウザは開いていません。 npm run dev も動いていません。 それでも「入力してボタンを押すと行が増える」ことが確かめられました。
⑥ 2本目 — 空のままでは追加できない
1本目は「動くこと」を確かめました。 2本目は「動かないこと」を確かめます。
TaskForm.jsx には、この1行があります。
if (text === "") return;
これは、この画面のたった1つの「決まりごと」です。そして、消しても画面は普通に動いてしまいます。 空のタスクが1件増えるだけです。気づかない可能性があるので、テストを書く価値があります。
src/App.test.jsx を、丸ごと置き換えます。
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import App from "./App.jsx";
test("タスクを追加すると、一覧に増える", async () => {
const user = userEvent.setup();
render(<App />);
await user.type(screen.getByRole("textbox"), "牛乳を買う");
await user.click(screen.getByRole("button", { name: "追加" }));
expect(screen.getByText("牛乳を買う")).toBeInTheDocument();
});
test("空のまま「追加」を押しても、増えない", async () => {
const user = userEvent.setup();
render(<App />);
await user.click(screen.getByRole("button", { name: "追加" }));
expect(
screen.getByText("まだ何もありません。上の欄から追加してください。")
).toBeInTheDocument();
expect(screen.queryAllByRole("listitem")).toHaveLength(0);
});
2本目で確かめているのは2つです。
- 「まだ何もありません」の文言が、まだ出ていること
- リストの項目(
<li>)が0個であること
queryAllByRole を使っているのは、「無いこと」を確かめているからです。getAllByRole だと、0個の時点でエラーになります。
RUN v3.2.4 /home/user/react-demo
✓ src/App.test.jsx (2 tests) 486ms
✓ タスクを追加すると、一覧に増える 311ms
✓ 空のまま「追加」を押しても、増えない 174ms
Test Files 1 passed (1)
Tests 2 passed (2)
[スクリーンショット: 01_vitest_pass.png] VMのターミナルで npm test を実行し、2本とも ✓ になっている画面を撮ってください。
テストの名前は日本語で構いません。 CI/CDの回と同じ理由です。失敗したときに読むのは自分です。
⑦ わざと落とす
通ったテストは、まだ信用できません。
一度も失敗させていないテストは、「実は何も確かめていない」可能性があります。
今回は、テストではなくアプリのほうを壊します。 そのほうが本番に近いからです。「うっかり消してしまった」を再現します。
if (text === "") return; の行を、削除してください。
❯ src/App.test.jsx (2 tests | 1 failed) 501ms
✓ タスクを追加すると、一覧に増える 318ms
× 空のまま「追加」を押しても、増えない 178ms
→ Unable to find an element with the text: まだ何もありません。上の欄から追加してください。
This could be because the text is broken up by multiple elements.
FAIL src/App.test.jsx > 空のまま「追加」を押しても、増えない
TestingLibraryElementError: Unable to find an element with the text: まだ何もありません。上の欄から追加してください。
Ignored nodes: comments, script, style
<body>
<div>
<div class="app">
<header class="header">
<h1>やること</h1>
<p class="who">ログイン中: たろう</p>
</header>
<div class="board">
<form>
<input placeholder="何か入力" type="text" value="" />
<button type="submit">追加</button>
</form>
<p>残り 1 件 / 全 1 件</p>
<ul>
<li>
<span class="" />
<button>削除</button>
<span class="meta">担当: たろう / 登録 16:12:44</span>
</li>
</ul>
...
</div>
</div>
</div>
</body>
❯ src/App.test.jsx:22:12
Test Files 1 failed (1)
Tests 1 failed | 1 passed (2)
この出力の読み方
上から順に、読む場所は5つです。
| 場所 | 読み取れること |
|---|---|
× テスト名 | どのテストが落ちたか。 通ったほうには ✓ が付いています |
| エラーの種類 | TestingLibraryElementError = 要素が見つからなかった。AssertionError = 見つかったが値が違った |
Unable to find an element with the text: ... | 何を探して、見つからなかったか |
<body> から始まるDOM | ⭐ 一番重要。 そのとき画面に何が出ていたか、そのもの |
❯ src/App.test.jsx:22:12 | テストファイルの何行目で落ちたか |
この失敗では、DOMを見れば一発です。
<p>残り 1 件 / 全 1 件</p>
<ul>
<li>
<span class="" />
タイトルが空っぽの <li> が1件、増えています。 「まだ何もありません」が消えたのは、その結果です。
RTL が失敗時にDOMを丸ごと出すのは、親切ではなく設計です。 「探したものが無い」と言われても、それだけでは原因が分かりません。 「代わりに何が出ていたのか」が分かって、初めて直せます。
console.logを足す前に、この出力を読んでください。 ほとんどの場合、答えはここに書いてあります。
[スクリーンショット: 02_vitest_fail.png] if (text === "") return; を消した状態で npm test を実行し、× の行と、その下のDOMが見えている画面を撮ってください。
戻す
消した1行を、TaskForm.jsx に戻してください。
if (text === "") return;
2 passed に戻れば、確認完了です。
いま起きたことを、言葉にしておきます。 「1行消しただけで、画面は普通に動いていた。」 ブラウザで見ても、たぶん気づきません。 それを、機械が0.5秒で見つけました。 これがテストを書く理由の全部です。
watch モードにしておく
開発中は、保存のたびに走らせるほうが早いです。
✓ src/App.test.jsx (2 tests) 470ms
Test Files 1 passed (1)
Tests 2 passed (2)
PASS Waiting for file changes...
press h to show help, press q to quit
Waiting for file changes... のまま待機します。 この状態で TaskForm.jsx を保存すると、関係するテストだけが自動で走り直します。
[スクリーンショット: 03_watch_mode.png] npm run test:watch を実行し、Waiting for file changes... が出ている画面を撮ってください。
止め方は q を押すか、Ctrl + C です。
⑧ node --test と vitest は、なぜ別なのか
ここで、バックエンドと繋ぎます。
~/server では node --test、~/react-demo では vitest。 道具が2つになりました。 好みで分けたのではありません。
node --test(~/server) | vitest(~/react-demo) | |
|---|---|---|
| 動く場所 | Node.js | Node.js(中に jsdom を立てる) |
document は | 存在しない | jsdom が用意する(偽物) |
| JSX は | 読めない(構文エラー) | Vite のプラグインが変換する |
| 追加のインストール | 無し(Node に同梱) | 6個 |
理由は2つです。
- Node.js には DOM がありません。 DOM操作の回でやった
document.querySelectorは、ブラウザが用意しているものです。Node の中で打つとdocument is not definedになります。だから jsdom で偽物を立てます - Node.js は JSX を読めません。
<li>を見た時点で構文エラーです。変換が要り、その設定はすでに Vite にあります
逆に言うと、DOM も JSX も出てこないコードなら、どちらでも試せます。
前回、tasksReducer.js についてこう書きました。
reducer は React も DOM も知らない、ただの関数。だから読みやすく、後でテストもしやすい
その回収です。 tasksReducer は、理屈のうえでは node --test でも試せます。
ですが、やりません。
1つのプロジェクトに、テストランナーを2つ置く理由がありません。
~/react-demoのテストは全部vitestに寄せます。 reducer のテストを書くときもvitestです。書き方は⑤とほとんど同じで、renderが要らなくなるだけです。node --testとvitestが分かれているのは「プロジェクトが別だから」であって、1つのプロジェクトの中で使い分けるものではありません。
CIで、両方走らせる
CI/CDの回で作った ci.yml は、~/server のテストしか走らせていません。
先に、正直に前提を書きます。
~/react-demo/は、まだ GitHub に上がっていません。 GitHubの回で上げたのは~/serverだけです。 だから、この節のワークフローは「上げたときにこう書く」という形です。リポジトリを分けるなら、それぞれにci.ymlを1本ずつ置くだけで、内容は前回のものと同じです。
1つのリポジトリにまとめる場合(~/server の直下に web/ としてフロントを置く形)、ci.yml はこうなります。
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
server-test:
runs-on: ubuntu-latest
steps:
- name: コードを取得する
uses: actions/checkout@v4
- name: Node.js を用意する
uses: actions/setup-node@v4
with:
node-version: '22'
- name: 依存を入れる
run: npm ci
- name: テストを走らせる
run: npm test
web-test:
runs-on: ubuntu-latest
defaults:
run:
working-directory: web
steps:
- name: コードを取得する
uses: actions/checkout@v4
- name: Node.js を用意する
uses: actions/setup-node@v4
with:
node-version: '22'
- name: 依存を入れる
run: npm ci
- name: テストを走らせる
run: npm test
前回との違いは3つです。
| 変えたところ | 意味 |
|---|---|
jobs: の下が2つになった | server-test と web-test は、別々のマシンで、同時に走ります |
defaults: run: working-directory: web | そのジョブの run: を、全部 web/ の中で実行する。ステップごとに cd web と書かなくて済みます |
| ジョブに名前を付けた | どちらが落ちたか、一覧で分かる |
2つに分けた理由は、片方が落ちても、もう片方の結果が見えるからです。 1つのジョブに詰め込むと、サーバー側のテストで落ちた時点で止まり、フロント側は「走ってすらいない」状態になります。「両方直す必要があるのか、片方だけか」が分かりません。
注意が2つあります。
working-directoryが効くのはrun:だけです。uses:には効きません。actions/checkoutは常にリポジトリの一番上に取ってきますnpm ciはpackage-lock.jsonが無いと動きません(前回の回)。web/package-lock.jsonも、必ずコミットしてください
そして、npm test が vitest run になっていることを、もう一度確認してください。 vitest(watch モード)のままだと、CIのジョブが終わらず、そのまま時間切れになります。
⑨ E2E(Playwright など)を、いまは入れない
名前と役割だけ、置いておきます。
| 道具 | 何をするか |
|---|---|
| Playwright | 本物の Chromium / Firefox / WebKit を起動して、実際にクリックして回る。Microsoft 製 |
| Cypress | 同じくブラウザで通しのテストをする。ブラウザの中で動くのが特徴 |
E2E が確かめるのは、jsdom では絶対に確かめられないものです。
- 本物のCSSが適用された状態で、ボタンが他の要素に隠れていないか
- フロントとサーバーの通信が、実際に成立するか
- ログインしてから、注文して、完了画面が出るまで、全部通るか
それでも、いまは入れません。理由は3つです。
1. 繋ぐ先がありません
~/react-demo/ は、まだサーバーを1度も呼んでいません。 前回の最後に書いたとおり、タスクはブラウザの中だけで生まれて、再読み込みで消えます。
E2E の価値は、「フロント・API・DBが揃って初めて分かること」を確かめる点にあります。サーバーを見ていない画面に E2E を書いても、⑤で書いたものと同じことを、20倍遅く確かめるだけです。
2. VMにブラウザがありません
Ubuntu Server には画面(GUI)がありません。 Playwright を動かすには、ブラウザ本体と、それが必要とするライブラリを大量に入れることになります。
入りますし、動きます。 ですが、そこで1時間使って学べるのは「Linuxに依存パッケージを入れる方法」であって、テストの考え方ではありません。
3. 一番壊れやすいものから始めることになります
②の表のとおり、E2E は一番壊れやすいです。
落ちたときに、原因の候補が多すぎます。 アプリのバグか、サーバーが起動していないのか、待ち時間が足りなかっただけか、ネットワークが遅かっただけか。「たまに落ちるテスト」は、そのうち誰も見なくなります。
E2E は「最後に、数本だけ」書きます。 一番大事な流れ(ログインできる、注文できる)だけです。細かい条件分岐は、コンポーネントのテストで確かめたほうが、速くて、原因も分かります。 フロントとサーバーを繋いだあとに、必要になってから入れます。
⑩ つまずいたところ
ReferenceError: document is not defined → vite.config.js に environment: "jsdom" が無いか、jsdom を入れていません。③に戻ってください。設定を直したら、watch モードは一度 q で止めて起動し直します。 設定ファイルの変更は自動で反映されないことがあります。
Invalid Chai property: toBeInTheDocument → src/setupTests.js が読み込まれていません。 vite.config.js の setupFiles のパス(./src/setupTests.js)と、実際のファイルの場所が合っているか確認してください。~/react-demo/ から見た相対パスです。
Failed to parse source for import analysis ... you can use JSX syntax only in .jsx files → テストファイルの拡張子が .js になっています。 App.test.js ではなく App.test.jsx です。中に <App /> と書いた時点で、JSXのファイルです。
Found multiple elements with the role "button" → getByRole("button") に名前を付けていません。 App にはボタンが5種類あります。{ name: "追加" } を足してください。 エラーメッセージの下に、見つかった全部の候補が並んでいるので、そこから名前を選べます。
Found multiple elements with the text: 牛乳を買う(2本目以降で) → cleanup が効いていません。 1本目で描画した App が、そのまま残っています。 vite.config.js の globals: true を確認してください。false にして import { test, expect } from "vitest" と書いた場合、RTL は afterEach を見つけられず、自動の片づけをしません。 その書き方をしたいときは、setupTests.js に自分で書きます。
import "@testing-library/jest-dom/vitest";
import { cleanup } from "@testing-library/react";
import { afterEach } from "vitest";
afterEach(() => {
cleanup();
});
入力したはずなのに、値が空のまま → await の書き忘れです。user.type(...) は Promise を返します。 await を付けないと、打ち終わる前に次の行へ進みます。 テスト関数の頭に async が付いているかも確認してください。
Error: Not implemented: HTMLFormElement.prototype.requestSubmit → TaskForm の e.preventDefault() が消えています。 jsdom には本物のページ遷移がないので、そこで止まります。前々回で「消すと画面が真っ白に戻る」と書いた動作が、テストではこの形で出ます。
getByText が「無い」と言うが、画面には出ている → 文字が複数の要素にまたがっています。 エラーメッセージにも This could be because the text is broken up by multiple elements. と出ています。 <p>残り <span>1</span> 件</p> のような形だと、getByText("残り 1 件") は見つけられません。 要素を分けずに書くか、探す範囲を狭めてください。
npm test が終わらない → package.json の "test" が "vitest" のままです。 "vitest run" にしてください。③の警告のとおりです。CIでこれをやると、ジョブが時間切れまで動き続けます。
Warning: An update to App inside a test was not wrapped in act(...) → user-event を使っていれば、普通は出ません。 出るときは、await を付け忘れているか、fireEvent を直接使っています。 user.click / user.type に統一してください。
後片づけ
この記事では、ポートを1つも開けていません。 ブラウザを開かなかったからです。 ufw は触らなくて構いません。
watch モードを起動したままなら、止めます。
入れたものを全部外したいときは、こうです。
そのうえで vite.config.js を、元の全文に戻します。
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
// https://vite.dev/config/
export default defineConfig({
plugins: [react()],
})
package.json の scripts から、足した2行を消します。
"scripts": {
"dev": "vite",
"build": "vite build",
"lint": "eslint .",
"preview": "vite preview"
},
残しておく場合の、最終的な構成はこうです。
/home/user/react-demo/src:
App.css App.jsx App.test.jsx assets components contexts index.css main.jsx setupTests.js tasksReducer.js
/home/user/react-demo/src/components:
Board.jsx Header.jsx TaskForm.jsx TaskItem.jsx TaskList.jsx TaskMeta.jsx TaskSummary.jsx
/home/user/react-demo/src/contexts:
UserContext.js
~/react-demo/ は、この先でも使うので残してください。
全部やり直したいときは:
まとめ
- フロントのテストが後回しになるのは、怠けているからではない。 見た目に正解が無く、変化が速く、目で見えてしまうから
- 判断基準は「それが壊れたとき、自分は気づけるか」。 気づけるものは書かなくていい
- 割に合うのは、条件分岐・計算・一度壊れた場所・取り返しがつかない操作。割に合わないのは、色や余白、実装の詳細
- テストには3種類あり、全部はやらない。 ユニット / コンポーネント / E2E。この回はコンポーネントだけ
- 上(ユニット)ほど速くて壊れにくく、下(E2E)ほど本物に近いが遅くて壊れやすい
- Vitest を選ぶ理由は1つ。設定ファイルが増えないから。 JSXの変換方法を、Vite と Jest に2回書かずに済む
vite.config.jsに足すのは4行だけ。environment/globals/setupFilesnpm testはvitestではなくvitest run。vitestは終わらない(watch モード)。CIが時間切れになるclassNameや内部の状態でテストしない。 利用者が困っていないのに落ちるテストは、直すのが仕事になり、最後は消される- RTL は「役割」と「見えている文字」で探す。
getByRoleが最優先で、getByTestIdは最後の手段 getByRoleが使えるのは、正しいタグを使っているから。<div onClick>で作ったボタンは見つからない。 テストが書きにくいのは、アクセシビリティが足りないサインgetByは無ければエラー、queryByはnull、findByは待つ。 「無いこと」を確かめるときだけqueryByuser-eventはawaitが要る。 忘れると、入力していないのに次へ進む- 一度は必ず、アプリのほうを壊してみる。 1行消しただけの変化は、ブラウザで見ても気づけない
- 失敗したら、まずDOMの出力を読む。 「何が無かったか」より「代わりに何が出ていたか」が答えを持っている
node --testとvitestが別なのは、動く場所が違うから。 Node にdocumentは無く、JSX も読めない- 1つのプロジェクトにテストランナーは1つ。 reducer のテストも
vitestで書く - CIでは2つのジョブに分ける。 片方が落ちても、もう片方の結果が見える
defaults: run: working-directory:はrun:にだけ効く。uses:には効かない- E2E はいま入れない。 繋ぐ先が無く、VMにブラウザも無く、一番壊れやすいから。最後に、数本だけ
これで、フロントにも「壊れたら教えてくれる仕組み」ができました。 ただし、いま確かめているのは画面の中だけです。サーバーと繋がったときに何が起きるかは、まだ誰も試していません。そこは繋いだあとの話です。
参考リンク
- Vitest 公式
- Vitest — Getting Started
- Vitest — 設定リファレンス
- Vitest — Comparisons with Other Test Runners
- Testing Library — Guiding Principles
- React Testing Library — Intro
- Testing Library — クエリの優先順位
- Testing Library — user-event
- jest-dom(
toBeInTheDocumentなどの一覧) - jsdom(GitHub)
- Playwright 公式
- GitHub Actions ドキュメント(日本語)
- roadmap.sh — React(Testing の項目)
- roadmap.sh — Frontend
次に読む
この記事は 【第4段階】フロントエンド の 5 / 15 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
- Vitest
- React Testing Library
- ユニット / コンポーネント / E2E の切り分け
この記事は、上の項目を実際に手を動かして確かめる回です。

コメント