Playwright E2Eテスト：保守性を極めるアーキテクチャ設計の全貌

現場のエンジニアなら誰もが一度は経験する「テストコードのスパゲッティ化」。特に業務系WebアプリケーションのE2Eテストにおいて、従来のPage Object Model（POM）をそのまま適用すると、テストコードは瞬く間にメンテナンス不能な負債へと変貌します。ページ単位でクラスを分割したはずが、複数ステップにまたがる複雑な申込フローを記述するうちに、メソッドの呼び出し順序が暗黙の了解となり、どのページでどの操作が有効なのかがコード上から読み取れなくなるのです。これは、まるでデッドロックが発生したマルチスレッド処理をデバッグするような徒労感に似ています。

今回紹介するアーキテクチャの核心は、単なるPOMの拡張ではなく、Screen Object ModelとFluent Chainingの統合にあります。従来のPOMでは各メソッドがvoidを返し、ページ遷移のたびにインスタンスを再生成するロジックがテストスクリプト側に漏れ出ていました。しかし、各メソッドがPromise<OrderPortal>を返し、自分自身のインスタンスを次々と繋いでいくFluent Chainingを採用することで、テストコードは「仕様書」としての可読性を獲得します。これにより、中間変数の乱立を防ぎ、各ステップが独立した状態を持つことで、非同期処理の複雑さをカプセル化することに成功しています。

また、TypeScriptのUnicode識別子をフル活用し、メソッド名を日本語化するというアプローチは、一見すると異端に見えるかもしれません。しかし、QAチームのメンバーがUI上で見ている「申込数量を選択する」といった日本語ラベルと、コード上のメソッド名が1対1で対応していることは、ドメイン知識と実装の乖離を埋める強力な武器となります。メンタルマッピングのコストを極限まで下げるこの設計は、技術的な制約よりも「誰がコードを読み、誰が保守するのか」という人間中心のエンジニアリングの視点から見れば、極めて合理的な選択であると私は確信しています。

E2Eテストにおける最大の敵は、動的に生成されるDOM要素と、非同期に発生するポップアップウィンドウです。多くのエンジニアが、セレクタ文字列を定数として管理するだけの単純な実装で挫折します。しかし、本アーキテクチャでは「ロケーター関数辞書」というパターンを採用しています。これは、ロケーターを単なる文字列ではなく、Pageオブジェクトを引数に取る関数として定義する手法です。これにより、辞書定義時点ではPageが存在しなくても、実行時にコンテキストを注入できる「遅延評価」が可能になります。

特に、ポップアップウィンドウのキャッチにおいて、多くの開発者が陥る罠が「クリック後にwaitForEventを呼ぶ」という順序の誤りです。クリックが完了した瞬間にイベントは過去のものとなり、テストはタイムアウトという無限ループのような待ち状態に陥ります。これを解決するために、ファクトリメソッド内でPromiseを先に取得し、アクションを実行した後にawaitするという「リスナー先行登録」のパターンを封じ込める設計は、非常に洗練されています。これにより、呼び出し側のテストコードはポップアップの存在を意識することなく、直感的なフローを記述できるのです。

以下の表は、本アーキテクチャで採用されているロケーター戦略の優先順位と、その選定理由をまとめたものです。この戦略は、テストの安定性を担保するための「防波堤」として機能します。

このように、ロケーター戦略を辞書として一元管理し、かつ戦略の優先順位を明確にすることで、テストの堅牢性は飛躍的に向上します。環境切り替えにおいても、String Literal Union型を用いることで、コンパイル時に環境指定ミスを検知できる仕組みを構築しています。これは、実行時エラーをコンパイル時エラーへとシフトさせる、TypeScriptの恩恵を最大限に引き出した設計と言えるでしょう。

ここまで詳細なアーキテクチャを解説してきましたが、我々エンジニアが真に直面している課題は、単なる「テストコードの書き方」ではありません。自動化されたテストが、開発のスピードを加速させるのか、それとも保守コストという名の重い足枷となるのか。その分水嶺は、今回紹介したような「仕様とコードの同期」をどれだけ高い解像度で実現できるかにかかっています。日本語メソッド名やFluent Chainingは、あくまでそのための手段に過ぎません。

皆さんのプロジェクトでは、テストコードが「書かれた当時のまま放置された遺物」になっていないでしょうか。もしそうなら、それはテストが仕様を語っていないからです。今回提示したアーキテクチャは、テストコードを「実行可能な仕様書」へと昇華させるための実践的な処方箋です。明日から皆さんが取るべき対策は、まず既存のPage Objectを見直し、メソッドが何を返し、どのページコンテキストを操作しているのかを可視化することから始めてください。そして、テストランナーの機能に依存しすぎず、純粋なTypeScriptの型システムを駆使して、環境や状態の不整合をコンパイル時に排除する設計へと舵を切るべきです。

最後に、私はあえて問いかけたい。自動化の目的は「テストをパスさせること」なのか、それとも「アプリケーションの変更に対する恐怖を払拭すること」なのか。もし後者であるならば、テストコードの可読性と保守性は、プロダクトコードと同等、あるいはそれ以上に重要視されるべき資産です。あなたの書いているそのテストは、半年後のチームメンバーが読んだときに、仕様書として機能するでしょうか。それとも、解読不能な暗号として、再び深夜の障害対応を招く引き金になるのでしょうか。技術の進化を追うだけでなく、その技術をどう「運用」し「継承」していくか。その問いに対する答えこそが、シニアエンジニアとしての真価を問うものだと私は考えます。