🐺

e2eテストは誰が見ても理解できるように書けているか

2025/03/30に公開

 仕様とE2Eテストの大切さについてチームに新しいメンバーが加わったときのことが、私たちの開発の進め方における大切な気づきのきっかけになりました。

その新メンバーがシステムのe2eを読んだ後でこう話してくれました。
🧑‍💻 「正直なところ、この仕様書を読んでみても、システムが実際に何をしているのか、ユーザーにどんな価値を届けているのか、はっきりとわかりません。全体像が見えてこないです。」
この言葉をきっかけに、私たちは仕様をE2Eテストにうまく落とし込めていないという大事なポイントに気づきました。

本来なら、わかりやすく書かれたE2Eテストを見るだけで、システムの動きや主な機能の流れを直感的に理解できるはずです。
でも実際には、チームメンバーが口頭で説明したり、図を描いて伝えたりしてやっと理解してもらえる状態でした。
つまり、文書にしておくべき大事な「仕様」がきちんと書かれておらず、チーム内での暗黙の了解になっており、継続的な開発の進め方ができていない状態でした。
# 本の購入を示すe2eの例

## 仕様が見えてこない例
* API"/v1/purchase"にボディ<file:fixtures/specs/hoge/request.json>を送る
* ステータスが"201"である
...
* 登録された結果がテーブル<file:fixtures/specs/hoge/assert.csv>である

## 仕様が見えてくる例
* API"/v1/purchase"に以下のリクエストを送る
* リクエストJSONの"$.name"に人の名前を示す"ほげ"を指定する
* リクエストJSONの"$.book.id"に本のID"xxxxxx"を指定する
* ステータスが"201"である
...
* 購入された本"xxxxxx"が登録されていること

 仕様不足がもたらす深刻な問題仕様をきちんと文書にしないと、こんな困りごとが出てきます。
チームの認識がバラバラになる：機能に対する理解が人によって違う
新メンバーが覚えるのに時間がかかる：暗黙の了解が多いと、新しい人が活躍できるようになるまで時間がかかる
知識が特定の人に頼りすぎる：詳しい人がいなくなると、その知識を取り戻すのにとても苦労する
同じ説明の繰り返し：同じ質問や説明が何度も必要になり、本来の開発時間が減ってゆく
テストの質が下がる：仕様があいまいだとテストも不十分になり、大事なバグを見落としやすくなる
これらの問題は時間とともに重なり合って、プロジェクト全体に影響していきます。

 具体的な改善のヒント今回私たちが採用しているgaugeでは、Conceptファイルを活用した仕様の表現がとても役立つことに気づきました。
コンセプトファイルを使うメリット
複数のステップをひとまとめにできるので、ビジネスの考え方や必要な機能を自然な言葉で書きやすい
開発者だけでなく、プロダクトオーナーや関係者のみなさんにも理解しやすい形で共有できる
システムの目的と動きを明確に書けるので、テストが「何をチェックしているのか」もわかりやすくなる
後から手直しもしやすく、変更にも柔軟に対応できる
また、どうしても仕様に落とし込みたいが実装との兼ね合いで落とし込みにくい場合は、ステップの中身はPassだけ書いておく方法も便利です（チームでは「から振り」と呼んでいます。）

 まとめ私たちの経験から学んだのは、「誰がみてもわかる？」というシンプルな問いかけが実は開発の持続可能性を左右するということです。
システムが「何をしているか」だけでなく「なぜそうしているか」も伝えると、誰がみても理解しやすいe2eテストが書けるのではと思いました。
最後に。
継続的な開発をするためにも「このテストは初めて見る人にも価値や目的が伝わるだろうか？」と自問することは大切です。

それ以上に、新しいメンバーからのフィードバックがより客観的で大きな改善のきっかけになることもあります。

チーム内で完結せず、他メンバーにもフィードバックをしてもらうことで、何か改善できる気づきがあるかもしれません。

仕様とE2Eテストの大切さについて

仕様不足がもたらす深刻な問題

具体的な改善のヒント

まとめ

Discussion