00 はじめに（全体像）

このハンズオンのゴール

テストがあると、ゴチャついたシステムでも安心して機能追加・修正できる——これを手を動かして体感する。

テストの書き方を暗記するのが目的ではありません。「テストが無いと何が怖いのか」「テストがあると何が変わるのか」を、実際に壊れる Web アプリを触りながら体験することが目的です。

対象読者・前提

JavaScript を読み書きしたことがある人
「テストは大事と聞くけど、何が嬉しいのか腹落ちしていない」人
必要なもの: Docker Desktop（Compose 込み）と、好きなエディタ
Node.js を直接使う方法も補足しますが、基本は Docker で進めます

学びの流れ（物語）

このハンズオンは、1つの物語に沿って進みます。

ゴチャゴチャしたシステムは機能追加が怖い 消費税まわりの設定を変えただけで、別の画面の集計が静かに壊れる。テストが無いので、誰も気づかないまま本番へ。
テストがあれば壊れた瞬間に分かる 同じ変更をしても、テストが即座に赤くなり、どこが壊れたかを指し示してくれる。安心して直せる。
自動テストの基本 なぜ動いたのか。テストランナー・アサーション・AAA（準備・実行・検証）といった基礎を学ぶ。
テストを自分で設計する 正常系・異常系・境界値。消費税の題材で「どんなケースを試すべきか」を自分で洗い出す。

章構成の地図

章	内容	ひとこと
00 はじめに	全体像	いまここ
01 環境構築	Docker で動かす準備	まず動かす
02 テストコードの体験	壊れる体験 → テストで救われる体験	本編の山場
03 自動テストの基本	node:test の基礎	なぜ動くのか
04 テストの設計	ケースの洗い出し	自分で考える

題材になるシステム

小さな EC サイト（顧客向け）と、その管理画面です。商品を検索して買い物かごに入れ、購入する。管理画面では売上（課税売上・非課税売上）と注文数を集計します。

このシステムには、現実によくある「事故のタネ」が仕込まれています。

顧客画面は新しい実装、管理画面は古い実装で、「その売上が課税か非課税か」の判定ロジックが食い違っている。

消費税が 10% のうちは両者の答えが一致するので、誰も食い違いに気づきません。ところが消費税を 0% にした瞬間、課税の商品が管理画面では「非課税売上」に化けて集計され、経理が狂います。詳しくは 02 章で。

技術スタック

種類	採用	理由
言語	JavaScript（Node.js / ESM）	広く使われている
Web フレームワーク	Hono + サーバーサイド HTML	PHP のようにページを返す素朴な構成
データベース	SQLite（better-sqlite3）	「DB を開いて税率を `UPDATE`」を体験するため
テスト基盤	node:test（Node 標準）	追加ライブラリ不要。特定フレームワークに依存しない
実行環境	Docker / Docker Compose	手元の環境差を吸収する

テストアプリはあえて Hono + HTML だけで作り、クライアント側 JavaScript フレームワークは使いません。フォーム送信とページ遷移だけで完結する、PHP のような素朴な動きにしています。複雑さを足さず、テストの本質に集中するためです。

リポジトリ構成

automated-test-hands-on/
├── docs/                  … このドキュメント群（章ごとの解説・手順）
│   ├── 00_overview.md
│   ├── 01_environment.md
│   ├── 02_experiments.md
│   ├── 03_basic.md
│   └── 04_test-plan.md
├── docs-site/             … ドキュメントサイト（Astro）※後続で整備
└── sections/              … 動くハンズオン教材（1レクチャー = 1アプリ）
    ├── 01-environment/    … 環境構築の確認用
    ├── 02-experience/     … 壊れる体験 / テストで救われる体験
    │   ├── 01-messy-no-test/
    │   └── 02-with-test/
    ├── 03-test-basics/    … node:test の基礎
    └── 04-test-design/    … テスト設計の演習

docs/ は読み物、sections/ は実際に動かすコード、という役割分担です。本ドキュメントを読みながら sections/ のアプリを動かして進めます。

次へ: 01 環境構築 →