UIの文言からE2Eテストを切り離す:extractTestIdによる契約分離
getByText("OK")のような文言ベースのセレクタでE2Eテストを書くと、文言変更のたびにテストが壊れる。spec.yamlのCSSセレクタ形式の定義からdata-testidの値だけを動的に抽出するextractTestIdユーティリティを経由することで、UIの文言とテストコードを分離した。
① やったこと
Before: E2EテストがgetByText("送信")のような文言ベースの要素特定に依存しており、ボタンの文言を1つ変えるだけで関連する複数のテストが失敗していた。
// tests/e2e/blog/common.spec.ts(変更前)
test('submits the form', async ({ page }) => {
await page.getByText('送信').click();
});After: spec.yamlにCSSセレクタ形式([data-testid='...'])で要素定義を集約し、この文字列からdata-testidの値だけを正規表現で取り出すextractTestIdユーティリティを実装した。コンポーネント実装とE2Eテストの両方が、同じspec.yamlの同じ定義を経由して要素を特定する。
// app/lib/blog/common/extractTestId.ts
export function extractTestId(selector: string): string {
const match = selector.match(/data-testid=['"]([^'"]+)['"]/);
return match ? match[1] : selector;
}// app/components/blog/common/BlogHeader.tsx
export const BlogHeader = ({ ui_selectors }) => (
<header data-testid={extractTestId(ui_selectors.header.blog_header)}>
{/* ... */}
</header>
);// tests/e2e/blog/common.spec.ts(変更後)
test('header is visible', async ({ page }) => {
const headerId = extractTestId(commonSpec.ui_selectors.header.blog_header);
await expect(page.getByTestId(headerId)).toBeVisible();
});文言が「送信」から「今すぐ送る」に変わっても、spec.yaml側のセレクタ定義とテストコードは一切変更不要になった。
② 設計判断
- 【優先した価値】: UIの文言変更にテストコードが追従しなくてよい、「不変の契約」としての独立性
- 【犠牲にした価値】:
spec.yamlに書けるのは素のID値ではなく、フルCSSセレクタ形式の文字列という一段抽象的な記法になった。値を直接読みたいときも、必ずextractTestIdという変換レイヤーを経由する必要がある
③ 技術的負債
- 【解消した負債】: UIの文言をキーにした要素特定への依存。文言をどれだけ変更してもテストコードの修正が不要になった
- 【新たに生まれた負債】: セレクタ文字列から値を抜き出す正規表現ベースの変換レイヤー(
extractTestId)自体が単一障害点になった。ここでの抽出ロジックが壊れると、これを経由する全コンポーネント・全テストが同時に影響を受ける
④ 経営翻訳
契約書の文面が日本語から英語に変わっても、契約IDだけ参照していれば同じ契約だと分かる社内システムに相当する。文面の言い回しは担当者が自由に変更できるが、システム側は文面ではなくIDだけを見て処理を続ける。
この分離が成立するのは、社内システムが参照する「契約ID台帳」そのものが整備されているからだ。3段階の階層型マージによりUI定義を一元管理するSSOT設計の上に成り立つ仕組みである。また、同じspec.yamlをSSOTとして活用するアプローチとして、ブログ記事のメタデータを自動検証するリントシステムも参照すると、コンテンツ・実装・テストの全レイヤーにわたるSSOT活用の全体像がつかめる。