qe-testability-scoring

テスト容易性スコアリング

<default_to_action> テスト容易性を評価する際は、次の手順を実行します。

1. 対象 URL に対して評価を実行します
2. 10 個すべての原則を自動的に分析します
3. レーダーチャート付きの HTML レポートを生成します
4. 影響度と工数に基づいて改善項目に優先順位を付けます
5. 全体像を把握するため、QX Partner と連携します

クイック評価：

# Run assessment on any URL
TEST_URL='https://example.com/' npx playwright test tests/testability-scoring/testability-scoring.spec.js --project=chromium --workers=1

# Or use shell script wrapper
.claude/skills/testability-scoring/scripts/run-assessment.sh https://example.com/

10 の原則の概要：

原則	重み	主な質問
可観測性	15%	何が起きているか確認できますか？
制御性	15%	アプリケーションを制御できますか？
アルゴリズムの単純性	10%	動作を予測できますか？
アルゴリズムの透明性	10%	何をするのか理解できますか？
アルゴリズムの安定性	10%	動作は一貫していますか？
説明可能性	10%	インターフェースは理解しやすいですか？
不具合の少なさ	10%	エラーはどの程度少ないですか？
小規模性	10%	コンポーネントのサイズは適切ですか？
分解可能性	5%	各部分を個別にテストできますか？
類似性	5%	技術スタックに馴染みがありますか？

評価尺度：

• A（90-100）：テスト容易性が非常に高い
• B（80-89）：テスト容易性が高い
• C（70-79）：テスト容易性が十分
• D（60-69）：平均を下回る
• F（0-59）：テスト容易性が低い </default_to_action>

クイックリファレンスカード

評価の実行

方法	コマンド	使用する場面
シェルスクリプト	./scripts/run-assessment.sh URL	1 回限りの評価
ENV の上書き	TEST_URL='URL' npx playwright test...	CI/CD との連携
設定ファイル	tests/testability-scoring/config.js を更新	繰り返し実行

原則の詳細

高い重み（各 15%）

原則	測定項目	指標
可観測性	状態の可視性、ログ、モニタリング	コンソール出力、ネットワーク追跡、エラーの可視性
制御性	入力制御、状態操作	API アクセス、テストデータの注入、決定性

中程度の重み（各 10%）

原則	測定項目	指標
単純性	予測可能な動作	明確な入出力の関係、低い複雑性
透明性	システムの動作の理解	可視化されたプロセス、読みやすいコード
安定性	一貫した動作	変更への耐性、保守性
説明可能性	インターフェースの理解	優れたドキュメント、意味的な構造、ヘルプテキスト
不具合の少なさ	エラーのない動作	コンソールエラー、警告、実行時の問題
小規模性	コンポーネントのサイズ	要素数、スクリプトの肥大化、ページの複雑性

低い重み（各 5%）

原則	測定項目	指標
分解可能性	分離テスト	コンポーネントの分離、モジュール設計
類似性	技術への馴染みやすさ	標準的なフレームワーク、既知のパターン

---

評価ワークフロー

1. Navigate to URL → 2. Collect Metrics → 3. Score Principles
                                              ↓
4. Generate JSON ← 5. Calculate Grades ← 6. Apply Weights
         ↓
7. Generate HTML Report with Radar Chart
         ↓
8. Open in Browser (auto-opens)

出力ファイル

tests/reports/
├── testability-results-<timestamp>.json  # Raw data
├── testability-report-<timestamp>.html   # Visual report
└── latest.json                           # Symlink

---

連携の例

CI/CD との連携

# GitHub Actions
- name: Testability Assessment
  run: |
    timeout 180 .claude/skills/testability-scoring/scripts/run-assessment.sh ${{ env.APP_URL }}

- name: Upload Reports
  uses: actions/upload-artifact@v3
  with:
    name: testability-reports
    path: tests/reports/testability-*.html

QX Partner との連携

// Combine testability with QX analysis
const qxAnalysis = await Task("QX Analysis", {
  target: 'https://example.com',
  integrateTestability: true
}, "qx-partner");

// Returns combined insights:
// - QX Score: 78/100
// - Testability Integration: Observability 72/100
// - Combined Insight: Low observability may mask UX issues

プログラムからの利用

import { runTestabilityAssessment } from './testability';

const results = await runTestabilityAssessment('https://example.com');
console.log(`Overall: ${results.overallScore}/100 (${results.grade})`);
console.log('Recommendations:', results.recommendations);

---

エージェントとの連携

// Run testability assessment
const assessment = await Task("Testability Assessment", {
  url: 'https://example.com',
  generateReport: true,
  openBrowser: true
}, "qe-quality-analyzer");

// Use with QX Partner for holistic analysis
const qxReport = await Task("Full QX Analysis", {
  target: 'https://example.com',
  integrateTestability: true,
  detectOracleProblems: true
}, "qx-partner");

---

Vibium との連携（任意）

概要

Vibium のブラウザー自動化を Playwright と併用して、テスト容易性評価を強化できます。Playwright が引き続き主要なエンジンですが、Vibium は一部の指標に対して補完的な機能を提供します。

インストール：

claude mcp add vibium -- npx -y vibium

Vibium によって強化される指標

原則	Vibium による強化	メリット
可観測性	自動待機時間の追跡	DOM の安定性を測定します（タイムアウト 30 秒、ポーリング 100ms）
制御性	要素の操作成功率	MCP 経由で自動化の準備状況を検証します
安定性	スクリーンショットの一貫性	レイアウトの安定性を視覚的なリグレッション検出によって確認します
説明可能性	要素の属性抽出	ARIA ラベル、セマンティック HTML の検証

Vibium を使用する場合

✅ 次の場合は Vibium を使用してください：

• 要素の安定性指標（自動待機時間の分析）
• 視覚的一貫性の確認（スクリーンショットの比較）
• MCP ネイティブの AI エージェント統合
• 軽量な Docker イメージ（400MB 対 1.2GB）

❌ 次の場合は Playwright を使用してください：

• コンソールエラーの検出（Vibium V1 にはコンソール API がありません）
• ネットワークパフォーマンス指標（BiDi ネットワーク API は V2 で提供予定です）
• 包括的なブラウザー対応（Firefox、Safari）
• 実績のある本番環境での安定性（Vibium V1 は 2024 年 12 月にリリース）

ハイブリッド評価の例

// Testability assessment using both engines
const assessment = {
  // Playwright: Comprehensive metrics
  playwright: await runPlaywrightAssessment(url),

  // Vibium: Stability metrics
  vibium: {
    elementStability: await measureAutoWaitDuration(url),
    visualConsistency: await compareScreenshots(url),
    accessibilityAttributes: await extractARIALabels(url)
  }
};

// Enhanced Observability Score
const observability =
  (assessment.playwright.consoleErrors * 0.6) +
  (assessment.vibium.elementStability * 0.4);

テスト容易性を測定する Vibium MCP ツール

// 1. Element Stability Measurement
const browser = await browser_launch();
await browser_navigate({ url });
const startTime = Date.now();
const element = await browser_find({ selector: ".critical-element" });
const autoWaitDuration = Date.now() - startTime;
// Lower duration = better stability

// 2. Visual Consistency Check
const screenshot1 = await browser_screenshot();
await browser_navigate({ url }); // Reload
const screenshot2 = await browser_screenshot();
const visualDiff = compareImages(screenshot1.png, screenshot2.png);
// Lower diff = better stability

// 3. Accessibility Attribute Extraction
const elements = await browser_find({ selector: "button, a, input" });
const ariaLabels = elements.map(el => el.attributes["aria-label"]);
const semanticScore = (ariaLabels.filter(Boolean).length / elements.length) * 100;

移行戦略

現在（V2.2）： ハイブリッド方式

• Playwright：10 の原則すべてに対応する主要エンジン
• Vibium：安定性指標の測定を任意で強化

今後（V3.0）： Vibium V2 のリリース後

• 次の条件を満たす場合、Vibium を主要エンジンとして評価します：
  • コンソール／ネットワーク API が利用可能
  • 本番環境での安定性が実証済み
  • コミュニティでの採用が拡大

エージェント連携のヒント

メモリの名前空間

aqe/testability/
├── assessments/*       - Assessment results by URL
├── historical/*        - Historical scores for trend analysis
├── recommendations/*   - Improvement recommendations
├── integration/*       - QX integration data
└── vibium/*           - Vibium-specific metrics (optional)

フリート連携

const testabilityFleet = await FleetManager.coordinate({
  strategy: 'testability-assessment',
  agents: [
    'qe-quality-analyzer',  // Primary assessment
    'qx-partner',           // UX integration
    'qe-visual-tester'      // Visual validation
  ],
  topology: 'sequential'
});

---

よくある問題と解決策

問題	解決策
テストがタイムアウトする	タイムアウトを延長します：timeout 300 ./scripts/run-assessment.sh URL
結果が一部しか表示されない	コンソールエラーを確認し、ネットワークのタイムアウトを延長します
レポートが開かない	AUTO_OPEN=false を使用し、手動で開きます
設定が更新されない	代わりに TEST_URL 環境変数を使用します
Vibium が利用できない	claude mcp add vibium -- npx -y vibium でインストールします（任意）
ハイブリッドモードでエラーが発生する	Vibium は任意です。なくても評価を実行できます

---

関連スキル

• アクセシビリティテスト - WCAG 準拠性（説明可能性と重複します）
• 高度なビジュアルテスト - UI の一貫性
• パフォーマンステスト - 読み込み時間の指標

---

クレジットと参考資料

フレームワークの起源

• James Bach と Michael Bolton による Heuristics for Software Testability
• 入手先：https://www.satisfice.com/download/heuristics-of-software-testability

実装

• https://github.com/fndlalit/testability-scorer をベースにしています（@fndlalit による貢献）
• AI 機能を備えた Playwright v1.49.0+（主要エンジン）
• MCP 統合を備えた Vibium v1.0+（任意の機能強化）
• レーダーチャートの可視化に Chart.js を使用

Vibium のリソース

• GitHub：https://github.com/VibiumDev/vibium
• MCP 統合：claude mcp add vibium -- npx -y vibium
• Selenium/Appium の開発者である Jason Huggins が作成

---

覚えておいてください

テスト容易性への取り組みは、後回しにするものではなく、投資です。

テスト容易性が高いと：

• デバッグ時間を短縮できます
• フィードバックループを高速化できます
• 欠陥を見つけやすくなります
• 継続的なテストを支援します

スコアが低いほどリスクは高くなります。重み × 影響度を基準に改善の優先順位を決めてください。