testing-blocks

ブロックのテスト

このスキルでは、AEM Edge Delivery Services プロジェクトのコード変更をテストする方法を説明します。テストは、価値とコストのバランスを重視します。テストの作成と保守にかかるコストを上回る価値が得られる場合に、テストを作成して保守してください。

重要：ブラウザーでの検証は必須です。実際のブラウザー環境で機能テストを行った証拠を提示しなければ、このスキルを完了できません。

関連するスキル

• content-driven-development：CDD 中に作成されたコンテンツは、テストの基礎になります
• building-blocks：ステップ 5 でこのスキルを呼び出し、包括的なテストを実施します
• block-collection-and-party：類似ブロックのテストパターンを参照できる場合があります

このスキルを使用するタイミング

次の場合にこのスキルを使用します。

• ✅ ブロックを実装または変更した後
• ✅ コアスクリプト（scripts.js、delayed.js、aem.js）を変更した後
• ✅ スタイル（styles.css、lazy-styles.css）を変更した後
• ✅ 機能に影響する設定を変更した後
• ✅ コード変更を含むプルリクエストを作成する前

通常、このスキルはbuilding-blocksスキルのステップ 5（実装のテスト）で呼び出されます。

テストのワークフロー

進捗を記録してください。

• ステップ 1：リンティングを実行して問題を修正する
• ステップ 2：ブラウザーで検証する（必須）
• ステップ 3：単体テストが必要か判断する（任意）
• ステップ 4：既存のテストを実行し、成功することを確認する

ステップ 1：リンティングを実行する

コード品質の問題を見つけるため、最初にリンティングを実行してください。

npm run lint

リンティングに失敗した場合：

npm run lint:fix

自動修正で対応できなかった問題は、手動で修正してください。

成功基準：

• ✅ エラーなしでリンティングが成功する
• ✅ コードがプロジェクトの規約に準拠している

完了の基準： npm run lint がエラーなしで成功すること

---

ステップ 2：ブラウザーでの検証（必須）

重要：実際のブラウザーでテストし、証拠を提示してください。

テスト対象

テスト用コンテンツの URL をブラウザーで読み込み、次の項目を検証します。

• ✅ ブロック／機能が正しく表示される
• ✅ レスポンシブ動作（モバイル、タブレット、デスクトップのビューポート）
• ✅ コンソールエラーがない
• ✅ 要件／受け入れ基準に沿った見た目である
• ✅ インタラクティブな動作が機能する（該当する場合）
• ✅ すべてのバリエーションが正しく表示される（該当する場合）

テスト方法

利用可能なツールに応じて、最適な方法を選択してください。

オプション 1：Browser／Playwright MCP（推奨）

MCP ブラウザーまたは Playwright ツールを利用できる場合は、直接使用してください。

• テスト用コンテンツの URL に移動する
• アクセシビリティスナップショットを取得して、表示されたコンテンツを確認する（インタラクションの確認に推奨）
• ビューポートを変えてスクリーンショットを取得し、見た目を検証する
  • ページ全体のスクリーンショットと、テスト対象ブロックの要素単位のスクリーンショットの両方を検討する
• 必要に応じて要素を操作する
• ツールを利用できるエージェントにとって、最も効率的です

オプション 2：Playwright による自動化

Playwright を使って機能を検証し、確認と検証に使うスナップショットやスクリーンショットを取得する一時的なテストスクリプトを 1 つ以上作成します。

// test-my-block.js (temporary - don't commit)
import { chromium } from 'playwright';

async function test() {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  // Navigate and wait for block
  await page.goto('http://localhost:3000/path/to/test');
  await page.waitForSelector('.my-block');

  // Inspect accessibility tree (useful for validating structure)
  const accessibilityTree = await page.accessibility.snapshot();
  console.log('Accessibility tree:', JSON.stringify(accessibilityTree, null, 2));
  
  // Optionally save to file for easier analysis
  await require('fs').promises.writeFile(
    'accessibility-tree.json',
    JSON.stringify(accessibilityTree, null, 2)
  );

  // Test viewports and take screenshots
  await page.setViewportSize({ width: 375, height: 667 });
  await page.screenshot({ path: 'mobile.png', fullPage: true });
  await page.locator('.my-block').screenshot({ path: 'mobile-block.png' });

  await page.setViewportSize({ width: 768, height: 1024 });
  await page.screenshot({ path: 'tablet.png', fullPage: true });
  await page.locator('.my-block').screenshot({ path: 'tablet-block.png' });

  await page.setViewportSize({ width: 1200, height: 800 });
  await page.screenshot({ path: 'desktop.png', fullPage: true });
  await page.locator('.my-block').screenshot({ path: 'desktop-block.png' });

  // Check for console errors
  page.on('console', msg => console.log('Browser:', msg.text()));

  await browser.close();
}

test().catch(console.error);

実行：node test-my-block.js を実行してから、スクリプトを削除し、生成された成果物を分析します。

オプション 3：ブラウザーによる手動テスト

開発者ツールが使える一般的な Web ブラウザーを使用します。

1. テスト用コンテンツに移動します：http://localhost:3000/path/to/test/content
2. ブラウザーの開発者ツールのレスポンシブモードで、各ビューポートをテストします。
   • モバイル：<600px（例：375px）
   • タブレット：600-900px（例：768px）
   • デスクトップ：>900px（例：1200px）
3. 各ビューポートでコンソールにエラーがないか確認します
4. 証拠としてスクリーンショットを撮影します（ブラウザーのスクリーンショットツールまたは開発者ツールを使用）

受け入れ基準に照らした検証

受け入れ基準が提示されている場合（CDD ステップ 2 より）：

• 各基準を確認する
• 記載された具体的なシナリオをテストする
• すべての基準を満たしていることを確認する

デザイン／モックアップのスクリーンショットが提示されている場合：

• 実装とデザインを比較する
• 見た目が一致していることを確認する
• 意図的に異なる箇所があれば記録する

テストの証明

以下を提出してください：

• ✅ ブラウザーでテスト用コンテンツを表示したスクリーンショット（少なくとも1つのビューポート）
• ✅ コンソールエラーがないことの確認
• ✅ 受け入れ条件を満たしていることの確認（提示されている場合）

成功基準：

• ✅ すべてのテスト用コンテンツが正しく読み込まれ、表示される
• ✅ ビューポートを変えてレスポンシブ動作を検証している
• ✅ コンソールエラーがない
• ✅ 証明用のスクリーンショットを撮影している
• ✅ 受け入れ条件を検証している（提示されている場合）

完了とする条件： ブラウザーテストが完了し、証明用のスクリーンショットがあること

---

ステップ 3：ユニットテスト（任意）

この変更でユニットテストが必要かどうかを判断します。

次の場合はユニットテストを作成します：

• ✅ ロジックが複雑な関数（計算、変換）
• ✅ 複数のブロックで使用されるユーティリティ関数
• ✅ データ処理または API 連携
• ✅ 複雑なビジネスロジック

次の場合はユニットテストを省略します：

• ❌ シンプルな DOM 操作
• ❌ CSS のみの変更
• ❌ 単純な装飾ロジック
• ❌ ブラウザーで簡単に検証できる変更

テスト対象に関するガイダンス： references/testing-philosophy.md を参照してください。

ユニットテストが必要な場合：

# Verify test setup (see references/vitest-setup.md if not configured)
npm test

# Write test for utility function
# test/utils/my-utility.test.js
import { describe, it, expect } from 'vitest';
import { myUtility } from '../../scripts/utils/my-utility.js';

describe('myUtility', () => {
  it('should transform input correctly', () => {
    expect(myUtility('input')).toBe('OUTPUT');
  });
});

ユニットテストの詳細なガイダンス： references/unit-testing.md を参照してください。

成功基準：

• ✅ ロジックが複雑なコードのユニットテストを作成している
• ✅ テストに合格する：npm test
• ✅ または、ユニットテストが不要と判断している

完了とする条件： ユニットテストを作成して合格している、または不要と判断していること

---

ステップ 4：既存のテストを実行する

変更によって既存の機能が損なわれていないことを確認します：

npm test

テストが失敗した場合：

1. エラーメッセージを注意深く読みます
2. 単一のテストを実行して原因を特定します：npm test -- path/to/test.js
3. コードを修正するか、期待値が変わった場合はテストを更新します
4. テストスイート全体を再実行します

成功基準：

• ✅ 既存のテストがすべて合格する
• ✅ リグレッションが発生していない

完了とする条件： npm test が失敗なく完了すること

トラブルシューティング

詳細なトラブルシューティングガイドについては、references/troubleshooting.md を参照してください。

よくある問題：

テストが失敗する

• エラーメッセージを注意深く読みます
• 単一のテストを実行します：npm test -- path/to/test.js
• コードを修正するか、テストを更新します

リントに失敗する

• npm run lint:fix を実行します
• 残った問題を手動で修正します

ブラウザーテストが失敗する

• 開発サーバーが起動していることを確認します：aem up --html-folder drafts
• テスト用コンテンツが drafts/tmp/ に存在することを確認します
• URL が /tmp/ パスを使用していることを確認します：http://localhost:3000/drafts/tmp/my-block
• 待機処理を追加します：await page.waitForSelector('.block')

リソース

• ユニットテスト： references/unit-testing.md - ユニットテストの作成と保守に関する完全ガイド
• トラブルシューティング： references/troubleshooting.md - よくあるテストの問題への対処法
• Vitest のセットアップ： references/vitest-setup.md - 一度限りの設定ガイド
• テストの考え方： references/testing-philosophy.md - テスト対象と方法に関するガイド

Building Blocks スキルとの連携

building-blocks スキルは、ステップ 5（テストの実装）でこのスキルを呼び出します。

building-blocks から受け取る入力：

• テスト対象のブロック名
• テスト用コンテンツの URL（CDD ステップ 4 から）
• テストが必要なバリアント
• 照合用の既存の実装、デザイン、モックアップのスクリーンショット（提示されている場合）
• 検証する受け入れ条件（CDD ステップ 2 から）

building-blocks に返す想定の出力：

• ✅ すべてのテスト手順が完了したことの確認
• ✅ 証明用のブラウザーテストのスクリーンショット
• ✅ リントに合格したことの確認
• ✅ テストに合格したことの確認
• ✅ 発見し、解決した問題