E2Eテストを「文言の呪縛」から解放する：extractTestId による契約の分離

著者: ClaudeMix Team | 2026.02.25

はじめに

getByText("OK") のようなテキストベースのセレクタでE2Eテストを書くと、文言変更のたびにテストが壊れます。spec.yaml のCSSセレクタ（[data-testid='...']）から動的にIDを抽出する extractTestId ユーティリティを経由することで、UIの文言とテストコードを完全に切り離せます。

ボタンの文言を一つ変えるだけで、テストが壊れる恐怖

「ボタンの文言を『OK』から『了解』に変えてもいいですか？」
その一言に、あなたは青ざめます。文言一つを変えるだけで、数十件のE2Eテストが真っ赤に染まり、数時間の修正作業が確定するからです。
テストが品質を守るための盾ではなく、改善を阻む足枷（あかせ）になっていませんか？

この記事をお勧めしない人

UIの文言とテストコードが密結合であることに疑問を感じない方。
文言修正に伴う手動のリテイク作業を厭わない、情熱的な開発者の方。
本質的でない修正よりも、現状の「動いているもの」を守ることを最優先にしたい方。

改善を躊躇わせる「文言の呪縛」

文言の変更がテストの失敗を引き起こす状態を放置すると、開発チームは次第にUIの改善を躊躇するようになります。
「テストが壊れるから」という理由で最適なユーザー体験を諦める逆転現象が起き、プロダクトの成長は鈍化し始めます。
最終的には、形骸化したテストスイートがメンテナンス不能となり、品質保証の最後の砦が崩壊するリスクを孕んでいます。

「不変の契約」がもたらす自由

ラベルが日本語になろうと英語になろうと、あるいは「購入」が「今すぐチェック」になろうと、テストコードは一切変更不要です。
デザイナーは文言のブラッシュアップに集中でき、開発者はビジネスロジックの修正に専念できる環境が手に入ります。
テストは不変の「契約」として、背後で静かに、そして確実に品質を保証し続ける理想的な状態を実現できます。
これは単なる理想論ではなく、ClaudeMixプロジェクトで実証済みの設計パターンです。

ユーティリティ一つで、テストは自由になれる

その魔法の正体は、1つのユーティリティと、スペック中心の設計思想にあります。
この記事では、UIの文言からテストを切り離し、真の意味で「変更に強い」E2Eテストを構築するための extractTestId パターンを公開します。
10分後、あなたのプロジェクトのテストコードは、文言の呪縛から解き放たれる第一歩を踏み出しているでしょう。

開発進捗

Before: E2Eテストにおいて getByText("送信") のような文言ベースの要素特定を行っており、文言変更に弱い状態だった。
Current: extractTestId ユーティリティを導入し、スペックファイルで定義されたテストIDによる要素特定への移行が完了した。
Next: アカウント管理やブログ機能の全コンポーネントにおいて、この「テスト契約」パターンを徹底し、保守性を維持する。

具体的なタスク

Before: CSSセレクタ形式（[data-testid='...']）と、属性値（testid）の二重定義が発生していた。
Current: スペックファイルに定義されたセレクタから ID を動的に抽出する extractTestId 関数を実装し、定義を一元化した。
Next: AIによるコード生成時にもこのスペックを参照させ、実装とテストの「契約」を自動的に守らせる仕組みを強化する。

課題と解決策

従来のE2Eテストでは、ボタンのラベルやタイトルの文言をキーに要素を特定することが一般的でした。
しかし、これはUIの改善（文言のブラッシュアップ）のたびにテストが壊れるという、開発の足枷を生んでいました。

工夫したこと

「スペックをUIとテストの間の契約と定義する」というアプローチを取りました。
共通のスペックファイル（spec.yaml）に UI 要素のセレクタを定義し、コンポーネントの実装側と E2E
テスト側の両方でこの定義を参照するようにしました。

ぶつかった壁

スペックファイル内では、将来のCSS拡張性やPlaywright以外のツールへの対応を見越して、
フルセレクタ形式（例：[data-testid='blog-header']）で記述したいという要望がありました。
しかし、Reactコンポーネントの data-testid 属性には、純粋なID値（例：blog-header）
だけを渡す必要があり、形式の不一致が発生しました。

解決方法

どのような形式のセレクタがスペックに書かれていても、一貫して data-testid
の値だけを正規表現で取り出す extractTestId ユーティリティを作成しました。
これにより、スペックの柔軟性を保ちつつ、実装側では規約に沿ったIDを付与し、
テスト側では契約通りの要素を特定できる仕組みを構築しました。

コード抜粋

実際に ID を抽出するユーティリティ関数の実装です。

// app/lib/blog/common/extractTestId.ts
/**
 * CSSセレクタ形式の文字列から data-testid の値のみを抽出する
 */
export function extractTestId(selector: string): string {
  // [data-testid='...'] または [data-testid="..."] の形式を想定
  const match = selector.match(/data-testid=['"]([^'"]+)['"]/);
  return match ? match[1] : selector;
}

コンポーネントの実装側では、スペックから抽出した ID を data-testid に付与します。

// app/components/blog/common/BlogHeader.tsx
import { extractTestId } from '~/lib/blog/common/extractTestId';

export const BlogHeader = ({ ui_selectors }) => {
  return (
    <header
      data-testid={extractTestId(ui_selectors.header.blog_header)}
    >
      {/* ... */}
    </header>
  );
};

E2Eテスト側でも同じスペックを参照し、同じユーティリティを使って要素を特定します。

// tests/e2e/blog/common.spec.ts
import { extractTestId } from '~/lib/blog/common/extractTestId';
import { data as commonSpec } from '~/generated/specs/blog/common';

test('header is visible', async ({ page }) => {
  const headerId = extractTestId(commonSpec.ui_selectors.header.blog_header);
  await expect(page.getByTestId(headerId)).toBeVisible();
});

ユニットテスト（Vitest / React Testing Library）でも、同様にスペックベースで要素を取得できます。

// app/components/blog/common/BlogHeader.test.tsx
import { render, screen } from '@testing-library/react';
import { extractTestId } from '~/lib/blog/common/extractTestId';
import { data as spec } from '~/generated/specs/blog/common';

test('renders header', () => {
  render(<BlogHeader ui_selectors={spec.ui_selectors} />);
  expect(screen.getByTestId(extractTestId(spec.ui_selectors.header.blog_header))).toBeInTheDocument();
});

今回の学びと感想

テストを「実装のコピー」ではなく「不変の契約」として設計することの重要性を再認識しました。
文言という「変わりやすいもの」からテストを解放することで、デザイナーはユーザー体験の改善に、
開発者は堅牢なロジックの構築に、それぞれ誇りを持って取り組めるようになります。

この extractTestId パターンが機能するのは、spec.yaml が階層的に整備されているからです。3段階の階層型マージによりUI定義を一元管理するSSOT設計の上に成り立つ仕組みです。また、同じ spec.yaml をSSOTとして活用するアプローチとして、ブログ記事のメタデータを自動検証するリントシステムも参照すると、コンテンツ・実装・テストの全レイヤーにわたるSSOT活用の全体像がつかめます。