「E2Eテストを書いたけど、半年後に読み返したら何をテストしているのかさっぱりわからない…」そんな経験はありませんか？
実はこの悩み、多くの開発チームが抱えている共通の課題です。
E2Eテスト（エンドツーエンドテスト）とは、ユーザーが実際にアプリを操作する流れを自動でシミュレーションするテストのこと。
しかし、テストコードが増えるほど「誰にも読めないブラックボックス」になりがちですよね。
この記事では、E2Eテストを「読めるカタログ」として整理し、チーム全員が仕様書のように活用できる状態にする具体的な方法を解説します。
非エンジニアでもテスト一覧を見れば機能がわかる、そんな状態を目指しましょう。
E2Eテストが「読めないコード」になる原因とは
テスト名が技術用語だらけになっている
E2Eテストが読めなくなる最大の原因は、テスト名のつけ方にあります。
たとえば「test_login_001」「check_submit_form_validation」のような名前を見て、何をテストしているか即座にわかるでしょうか？
開発者本人でさえ、1ヶ月後には「これ何だっけ？」となるケースがほとんどです。
テスト名が技術的なID や略語で書かれていると、チームメンバーはもちろん、ディレクターやQA担当者にはまったく伝わりません。
テスト名は「コードのコメント」ではなく、そのテストが保証している機能を日本語で説明するラベルとして書くべきです。
テストの中身が手続き的で流れが見えない
もう一つの原因は、テストコードの中身が「クリックして、入力して、待って、確認して…」という操作手順の羅列になっていることです。
セレクタの指定やスリープ処理が並ぶコードは、そのテストが「何の価値を検証しているのか」が埋もれてしまいます。
読み手がコードを1行ずつ追わないと意図がわからないテストは、カタログとして機能しません。
操作の詳細は関数やPage Objectに隠蔽し、テスト本体には「意図」だけが残る構造にすることが重要です。
テスト一覧を俯瞰できる仕組みがない
個々のテストが読みやすくても、全体を一覧で俯瞰できなければカタログにはなりません。
テストファイルがフォルダに散らばり、どの機能がカバーされていてどこが抜けているのか把握できない状態は危険です。
「ログイン機能のテストはどこ？」と聞かれてすぐ答えられないなら、テストの管理方法に問題があります。
カタログ化とは、テストを書くことだけでなく、テスト全体を見渡せる地図を作ることでもあるのです。
「読めるカタログ」とは何か ― 目指すべき状態を定義する
カタログ化された E2Eテストの3つの条件
E2Eテストが「読めるカタログ」として機能するには、次の3つの条件を満たす必要があります。
- テスト名だけで「どの機能の何を保証しているか」がわかる
- テスト一覧を出力すると、そのまま機能仕様書として読める
- 非エンジニアでもテストの合否レポートを見て状況を把握できる
この3つが揃ったとき、E2Eテストは単なる品質チェックツールから「生きたドキュメント」へと進化します。
テストが仕様書を兼ねるので、ドキュメントとコードの乖離という問題も解消されます。
カタログ化のメリットを具体的に見てみる
カタログ化がもたらすメリットを、従来のテスト運用と比較してみましょう。
| 観点 | 従来のE2Eテスト | カタログ化されたE2Eテスト |
|---|---|---|
| テスト名 | test_001, login_check | ユーザーがメールアドレスでログインできる |
| 仕様把握 | コードを読む必要あり | テスト一覧で機能が一目瞭然 |
| 新メンバーの理解 | 数日〜数週間かかる | テスト一覧を読めば半日で概要把握 |
| テスト失敗時 | 何が壊れたか調査が必要 | テスト名で影響範囲が即座にわかる |
| 非エンジニアとの共有 | 困難 | レポートをそのまま共有可能 |
テストを書く工数はほぼ変わらないのに、得られる価値が大幅に増えるのがカタログ化の最大の魅力です。
E2Eテストをカタログにする具体的な手順
ステップ1：テスト名を「ユーザー行動」で書き直す
まず着手すべきは、テスト名のリネームです。
ルールはシンプルで、「〇〇が△△できる」「〇〇すると△△になる」という形式で書くだけです。
具体例を見てみましょう。
| Before（技術者向け） | After（カタログ向け） |
|---|---|
| test_login_valid | 登録済みユーザーがメールとパスワードでログインできる |
| test_cart_add | 商品詳細ページからカートに商品を追加できる |
| test_checkout_error | クレジットカード情報が不正な場合にエラーメッセージが表示される |
| test_search_filter | カテゴリで絞り込んだ検索結果が正しく表示される |
Playwrightならtest.describeとtest()の組み合わせで階層的に書けます。
test.describe('商品購入フロー', () => {
test('ログイン済みユーザーが商品をカートに追加できる', async ({ page }) => {
// ...
});
test('カート内の商品数量を変更できる', async ({ page }) => {
// ...
});
});このdescribeのグループ名がカタログの「章」、各testが「項目」になるイメージです。
ステップ2：Page Objectパターンで操作を抽象化する
テスト名を整えたら、次はテスト本体の可読性を上げます。
Page Objectパターンとは、ページごとの操作をクラスにまとめるデザインパターンです。
// LoginPage.ts
export class LoginPage {
constructor(private page: Page) {}
async login(email: string, password: string) {
await this.page.fill('#email', email);
await this.page.fill('#password', password);
await this.page.click('button[type="submit"]');
}
}
// テスト本体
test('登録済みユーザーがログインできる', async ({ page }) => {
const loginPage = new LoginPage(page);
await loginPage.login('user@example.com', 'password123');
await expect(page.locator('.dashboard')).toBeVisible();
});テスト本体に残るのは「ログインする → ダッシュボードが表示される」という意図だけです。
セレクタやクリック操作の詳細はPage Objectに隠れるので、テストを読むだけで仕様がわかるようになります。
ステップ3：テスト一覧をドキュメントとして自動出力する
仕上げに、テスト一覧を人が読めるドキュメントとして出力する仕組みを作りましょう。
Playwrightなら以下のコマンドでテスト名を一覧表示できます。
npx playwright test --list出力結果をMarkdownやHTMLに変換するスクリプトを用意すれば、常に最新の「機能カタログ」が自動生成されます。
たとえば、以下のようなシンプルなスクリプトで実現可能です。
npx playwright test --list 2>&1 | \
sed 's/^/- /' > docs/test-catalog.mdCIに組み込めば、プルリクエストのたびにカタログが更新され、テストとドキュメントが常に同期した状態を保てます。
スポンサードリンク実践で使えるおすすめツールと設定
Playwrightのレポーターでカタログを可視化する
2026年現在、E2Eテストツールとして最も勢いがあるのがPlaywrightです。
Playwrightには複数のレポーター（結果出力形式）が用意されており、カタログ化に最適な設定ができます。
// playwright.config.ts
export default defineConfig({
reporter: [
['html', { open: 'never' }],
['json', { outputFile: 'test-results.json' }],
['list']
],
});htmlレポーターを使えば、テスト結果がブラウザで閲覧できる美しいHTMLページとして出力されます。
テスト名を日本語で書いていれば、このHTMLレポートがそのまま機能カタログとして機能します。jsonレポーターの出力は、社内ツールや Notion に取り込む際に便利です。
Cypressやその他ツールでの対応方法
Cypress を使っている場合も、基本的な考え方は同じです。describeとitの名前を日本語のユーザー行動で書き、mochawesomeレポーターでHTML出力すればカタログ化できます。
// cypress.config.js
module.exports = {
reporter: 'mochawesome',
reporterOptions: {
reportDir: 'docs/catalog',
overwrite: false,
html: true,
json: true
}
};ツールに関わらず重要なのは、テスト名の命名規則とレポートの自動出力の2つです。
この2つさえ押さえれば、どのフレームワークでもカタログ化は実現できます。
チームで運用するためのルール作り
命名規約をREADMEに明文化する
カタログの品質を維持するには、チーム全員が同じルールでテスト名をつける必要があります。
以下のような命名規約をプロジェクトのREADMEやContributing Guideに明記しましょう。
describeには機能領域を書く（例: 「ユーザー認証」「商品検索」）test / itには「〇〇が△△できる」「〇〇すると△△になる」の形式で書く- テスト名に実装の詳細（API名、DB名など）を含めない
- 1つのテストで検証する振る舞いは1つだけにする
ルールが明文化されていれば、コードレビューで「このテスト名、カタログとして読めますか？」という観点でチェックできます。
属人化を防ぎ、誰が書いても同じ品質のカタログが生まれる仕組みを作ることが大切です。
CIでカタログを自動更新し、常に最新を保つ
ルールを決めても、カタログの更新を手動で行っていては必ず陳腐化します。
CI/CDパイプラインにカタログ生成を組み込み、自動化しましょう。
GitHub Actionsでの設定例を紹介します。
# .github/workflows/test-catalog.yml
name: Update Test Catalog
on:
push:
branches: [main]
jobs:
catalog:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- run: npm ci
- run: npx playwright test --list > docs/test-catalog.txt
- run: npx playwright test --reporter=html
- uses: actions/upload-artifact@v4
with:
name: test-catalog
path: playwright-report/mainブランチにマージされるたびにカタログが更新されるので、いつでも最新の機能一覧を確認できます。
生成されたHTMLレポートをGitHub Pagesや社内ポータルにデプロイすれば、エンジニア以外のメンバーもブラウザでカタログを閲覧できるようになります。
レビューで「カタログ品質」を守る
テストのコードレビューでは、ロジックの正しさだけでなく「カタログとしての読みやすさ」も確認しましょう。
具体的には、以下の3つの観点でチェックします。
- テスト名を読むだけで、何の機能が保証されているかわかるか？
- テスト本体を読んだとき、操作の意図が明確か？（セレクタの羅列になっていないか）
- 既存のカタログ構造（describeの階層）と整合性があるか？
このレビュー観点をテンプレート化しておくと、レビューの質が安定します。
テストは書いた瞬間から「未来のチームメンバーへのドキュメント」です。
その意識をチーム全体で共有することが、カタログ運用を成功させる最大のポイントです。
まとめ
E2Eテストを「読めるカタログ」に変えるポイントを振り返りましょう。
- テスト名は「ユーザー行動」で書く ― 「〇〇が△△できる」形式にするだけで可読性が劇的に向上する
- Page Objectパターンで操作を抽象化する ― テスト本体には「意図」だけを残し、詳細は隠蔽する
- テスト一覧をドキュメントとして自動出力する ― PlaywrightやCypressのレポーターを活用し、常に最新のカタログを生成する
- 命名規約を明文化してチームで共有する ― 属人化を防ぎ、誰が書いても同じ品質を保つ
- CIに組み込んで自動更新する ― 手動更新は必ず陳腐化するので、パイプラインで自動化する
E2Eテストは「品質を守る仕組み」であると同時に、「プロダクトの機能を正確に記述したドキュメント」でもあります。
テストをカタログ化することで、開発チームだけでなくビジネスサイドのメンバーとも共通言語を持てるようになります。
まずは今あるテストの名前を1つ、日本語のユーザー行動に書き換えるところから始めてみてください。
