この記事では、複数のプロジェクトでE2Eテストの構築に関わった経験から、自分が設計したE2Eテストを、メンバーがスムーズに使えるように意識していることを紹介します。
※この記事は、技術的な事実ではなく私の主観を述べているため、他の記事とは表現を変えています。
結論: やることの全体像
- テストの目的とゴールを共有する
- なぜ、テストをやるのか、テストのゴールは何かを説明する
- なぜ、そのゴール設定なのかを説明する
- 採用したツールの概要と採用理由を説明する
- テスト手順（ドキュメント）の作成と共有
- ドキュメントには「仕組みの解説」を入れる
- 手順を示すだけでなく、学びの要素を入れる
- テスト手順（ドキュメント）の改善
- ドキュメントの更新はメンバーがやる
テストの目的とゴールを共有する
テスト設計と構築が終わったら、
各メンバーがテストを実装できるように共有する必要があります。
そのためにまずやるべきことは、
「テストの目的とゴール」を共有することです。
このステップでは、
「チームメンバーが共通認識を持っている状態」をゴールにします。
一番大切なステップなので、具体的に説明します。
テストの説明をする際、
「テストをやります。手順はこうです。」
という方法論だけの説明は、チームメンバーの混乱を生みます。
どこに向かえばいいか、わからないからです。
例えば人材の採用において、いきなり事業内容を説明する前に、まずは「理念」や「実現したい未来」を共有すると思います。そして共感した人が「御社で働きたい」と応募してきます。
それと同じように、E2Eテストにおいても「テストで実現したいこと」「なぜやるのか」をまず共有することが重要です。このステップをやらないと、「テストを書くのはわかったが、どこに向かっているのかわからない。」という状態になり、結果的にテストコードの品質はバラバラになってしまう可能性があります。
なぜ、テストをやるのかを説明する
これはソフトウェア開発に限った話ではありませんが、
結果が出るチームは、メンバーが同じ方向を向いています。
常に、共通認識を持てているからです。
では、メンバーに共通認識を持たせるために大切なことは何か。
それは、「なぜ、やるのか」をしっかり説明することだと私は考えています。
- なぜ、今までテストをやらなかったのか
- テストをやらなかったことで、どのような問題が起きていたのか
- なぜ、テストが必要だと思ったのか
- テストを通じて、どのような状態を実現したいのか
これらをしっかりと説明し、
チームメンバーが納得できる状態にすることが、ファーストステップです。
マネージャーが説明しないなら、チームメンバーが明らかにする努力も必要です。
なぜ、そのゴール設定なのかを説明する
次に説明すべきことは、ゴール設定の理由です。
ゴールを共有しただけでは、
メンバーが理解はできても、納得はできていないからです。
チームメンバーが共通認識を持つために、
「なぜ、そのゴール設定なのか」を説明します。
テストのゴールは、現場によって異なります。
例えば、
- コードの品質を担保するためにテストを導入する
もしくは、
- 検証チームのコスト削減のためにテストを導入する
など様々です。
そして、ここにも「なぜ」という観点を入れて、
- なぜ、コードの品質を担保する必要があるのか
- なぜ、検証チームのコストを削減したいのか
を説明します。
ここまでやることで、チームメンバーがテストの目的と背景を理解し、どの粒度でテストを構築するべきか、具体的なイメージを持てるようになります。
私は、以下のような型を使っています。
## テストの目的とゴール設定
ここでは、テストの目的とゴールを共有する。
過去〜現在に至るまでの問題点やテストが必要になった経緯を説明し、
最終的にテストを通じてどのような状態になっていることが望ましいかを説明する。
### なぜ、テストをやるのか
テストが必要になった背景を説明する。
### テストのゴールは何か
テストをプロジェクトに導入した結果、
どのような未来を実現できれば嬉しいか。
具体的なゴールを記載する。
### なぜ、そのゴールを設定したか
ゴールを設定した理由を書く。採用したツールの概要と採用理由を説明する
ここでは、特に意識することはありません。
採用したツールの概要と、採用理由を簡潔に説明するだけです。
私は、以下のような型を使っています。
## playwrightの概要と採用理由
### playwrightとは
概要を2~3行で簡潔に説明し、公式ドキュメントのリンクを貼る
[公式ドキュメント](https://playwright.dev/)
### playwrightを採用した理由
なぜ、playwrightを採用したのか。
その理由を記載する。
他のテストツールとの比較を交えて、
「こういう利点があるからplaywrightを採用した」
ということがわかれば良い。あとは、メンバーが勝手に公式ドキュメントで学ぶので、
ツールについて詳細に説明する必要はありません。
テスト手順（ドキュメント）の作成と共有
次に、メンバーがテストを実装できるように具体的な手順を書いていきます。
ドキュメントの構成は以下の通りです。
- インストールからテスト実行までの流れ
- 基本的な設計の共有
- ディレクトリ構成
- ファイルの命名
- テストの書き方 など
- 共通処理の解説
- レアケースやトラブルシューティングの説明
すでにテストの目的やゴールをメンバーは理解しているので、
ここでは「やり方」にフォーカスします。
一般的な手順書の書き方に沿っていますが、
私が意識しているのは以下の2つです。
- 共通処理の解説
- レアケースやトラブルシューティングの説明
共通処理の解説をする
playwrightを例にしますが、テストを構築する過程でテスト用の共通関数が必要になります。Reactだとhooks、VueだとComposableのようなイメージです。
例えば、
- テストの認証自動化
- DOM操作の共通関数
など、「メンバーがコピペして使う」であろう共通処理が、
どのような仕組みで動いているのかを解説します。
私は、以下のような型を使っています。
## 共通処理について
共通処理はコピペすれば使えるが、どのような仕組みで動いているのかを解説する。
### 認証自動化の仕組み
...解説
### DOM動作の共通関数について
#### clickAllToggleButtons: ドロップダウンをまとめて展開する
...解説仕組みを解説することで、どのような原理でテストが動いているのかをメンバーが理解できます。テストの設計者がひと手間かけることで、メンバーのスキル向上にも寄与します。
レアケースやトラブルシューティングの説明をする
テスト設計〜構築をする過程で、
ハマりやすいポイントについてもノウハウがたまってきます。
それらもドキュメントにして、メンバーに共有しましょう。
例えば、以下のような型を使うとわかりやすいと思います。
## トラブルシューティング
### （エラー内容）
このエラーが出た時は以下のような対応を試す。
的な説明を記載する。
### 環境間で挙動に差異がある場合のモック活用法
開発環境では再現しないが、本番環境のみでエラーが発生する場合、
以下のようにモックを使用して本番環境の現象を再現できる。
... 具体的な手順を書くメンバーがテストを実装する過程で、新たに遭遇する問題もあるでしょう。
それらを追記していくことで、ドキュメントの品質を継続的に高めることができます。
テスト手順（ドキュメント）を改善する
このステップを忘れている開発現場は多いのではないでしょうか。
要は、作って終わりではダメだということです。
ここでは、
- なぜ、ドキュメントを改善する必要があるのか
- 「メンバー」がドキュメントを改善するべき理由
を解説してきます。
ドキュメントを改善すべき理由としては、
- テストツールの仕様が変更されている場合、
新メンバーが手順通りにやってもエラーが発生することがある - メンバーがテストを実装する過程で、
新たに遭遇する問題やその解決法を蓄積できる - 既存の実装よりも効率的な処理をメンバーが見つけた場合、
それをスタンダードにできる
などが挙げられます。
そして私は、「メンバーにドキュメントを更新してもらう」ことを意識しています。
メンバーにドキュメントを更新してもらう
初期のドキュメントが完成した時点では、それは設計者の頭の中を形にしたものに過ぎません。
加えて、設計者はすでにテストを実装して知識もある状態なので、
初心者が躓くポイントを見逃している可能性もあります。
設計者が見逃しているポイントを、メンバーが補う。
これも、ドキュメントを改善する上では大切です。
具体的には、
- テスト構築の過程で、記載した方がいいと思うことを加筆してもらう
- 記載通りに実行したが、エラーになった場合の解決策を加筆してもらう。
もしくは、修正してもらう。
などです。
私が現在参画している現場でも、
メンバーにテストドキュメントを更新してもらっています。
こうすることで、設計者が見落としている観点を補うことができ、
新しくその現場にジョインした人も、スムーズにテストの実装ができるようになります。
まとめ
では、記事の内容をまとめます。
- テストの目的とゴールを「なぜ」を前提に共有し、メンバーの共通認識を形成する
- 採用したツールの概要と採用理由を説明する。
- テスト手順（ドキュメント）の作成と共有を行う。ドキュメントには「仕組みの解説」を入れ、手順を示すだけでなく、学びの要素を入れる。
- テスト手順（ドキュメント）の改善をする。改善作業は、メンバーの仕事。
少しでも参考になることがあれば幸いです。
コメント