記事追加のたびにE2Eテストが壊れる問題を、spec.yamlへのテストデータ集約で解消した記録

著者: ClaudeMix Team |

E2Eテストが本番記事の件数・カテゴリ名に依存していたため記事追加のたびに壊れていた問題を、テストデータをspec.yamlへ集約し件数チェックを存在確認へ置き換えることで解消した。

① やったこと

Before: E2Eテストが本番記事の件数やカテゴリ名を直接の前提として書かれていた。

// tests/e2e/blog/common.spec.ts(変更前)
it('should filter posts by category', async ({ page }) => {
  await page.goto(TARGET_URL);
  await page.getByTestId('category-selector').selectOption('Claude Best Practices');
  await page.getByTestId('filter-submit-button').click();

  // カテゴリに属する記事件数を決め打ちしている
  await expect(page.getByTestId('post-card')).toHaveCount(3);
});

新しい記事を1本追加しただけで該当カテゴリの件数が変わり、このテストが失敗していた。加えて、カテゴリ名という値自体も設計書・コンポーネント実装・このE2Eテストコードの3箇所に別々に書かれており、名称を1つ変えるだけで3箇所すべてを追いかける必要があった。

After: spec.yamlにテスト専用記事とカテゴリ定義を集約し、テストはloadSpec経由でこの値を読んだうえで、件数の決め打ちをやめて「該当記事が表示されているか」という存在確認に置き換えた。

// tests/e2e/blog/common.spec.ts(変更後)
it('should filter posts by category', async ({ page }) => {
  const spec = await loadSpec('blog', 'posts');
  const categoryToTest = spec.categories[2];
  const testArticle = (await getTestArticlesByCategory(categoryToTest.id))[0];

  await page.goto(TARGET_URL);
  await page.getByTestId('category-selector').selectOption(categoryToTest.name);
  await page.getByTestId('filter-submit-button').click();

  const testArticleCard = page.locator(
    `[data-testid="post-card"][data-slug="${testArticle.slug}"]`
  );
  await expect(testArticleCard).toBeVisible();
});

本番記事とは無関係な「テスト専用記事」をあらかじめ用意し、そのslugがフィルタ後に表示されるかだけを見るようにしたことで、本番記事の増減がこのテストの結果に影響しなくなった。

② 設計判断

  • 【優先した価値】: テストを本番データから完全に独立させ、記事を追加・変更してもE2Eテストが壊れない構造にすること
  • 【犠牲にした価値】: 「本番記事だけを見ていればよい」という単純さ。テスト専用記事とspec.yaml側のテストデータ定義を、本番運用とは別に新設・保守する責務が増えた

③ 技術的負債

  • 【解消した負債】: 記事追加のたびにE2Eテストが壊れていた依存構造。テストの前提を件数から存在確認に変えたことで、記事の増減がテスト結果に影響しなくなった
  • 【新たに生まれた負債】: 値を変更する際に修正が必要な場所は、設計書・コンポーネント実装・E2Eテストコードの3箇所に加えテストデータ自体も別ファイルに分散していた状態から、spec.yaml 1ファイルへ集約された。実測: 修正対象ファイル数 5ファイル → 1ファイル(80%減)。一方で、spec.yamlにテスト専用データとアプリケーション設定が同居し続けると、このファイル自体が肥大化するリスクは未解決のまま残っている

④ 経営翻訳

新入社員研修で使う事例集に、実在する顧客名と契約件数をそのまま書き込んでいた状況に相当する。顧客の契約状況が変わるたびに、関連する複数の資料をひとつずつ確認し修正する必要があった。

実際には確認・修正が必要な資料が5冊から1冊に減り(80%減)、修正漏れによる問い合わせもほぼなくなった。

SSOTの思想はテストデータだけでなく、TypeScriptの型定義にも適用できる。AIとの協調で型定義を「分析→設計→実行」の3ステップで整理した記録も参照してほしい。また、spec.yamlをE2EテストのセレクタIDにも適用するextractTestIdパターンを使うと、UIの文言変更でテストが壊れる問題も根本から解消できる。

新入社員研修で使う事例集に、実在する顧客名と契約件数をそのまま書き込んでいた。 顧客の契約状況が変わるたびに、関連する複数の資料をひとつずつ確認し修正する必要があった。

設定値を変更した際に、確認・修正が必要になる資料の数: 5冊