testability-scoring

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

ブラウザーエンジン

主要なブラウザーエンジンとして、qe-browser フリートスキル（.claude/skills/qe-browser/）を使用します。Vibium は aqe init によってインストールされます。従来の scripts/run-assessment.sh ＋ Playwright の経路は、チームですでに Playwright のテストスイートが構成されている場合のフォールバックとして引き続き利用できますが、新しい実行では次を優先してください。

vibium go "$TARGET_URL"
vibium wait load
vibium a11y-tree --json > /tmp/testability/tree.json
vibium eval --stdin --json <<'EOF' > /tmp/testability/signals.json
JSON.stringify({
  headings: document.querySelectorAll('h1,h2,h3,h4,h5,h6').length,
  testIds: document.querySelectorAll('[data-testid]').length,
  forms: document.querySelectorAll('form').length,
  ariaLabels: document.querySelectorAll('[aria-label]').length,
  links: document.querySelectorAll('a[href]').length,
});
EOF
node .claude/skills/qe-browser/scripts/assert.js --checks '[
  {"kind": "no_console_errors"},
  {"kind": "no_failed_requests"}
]'

<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%）

原則	評価対象	指標
単純さ	予測可能な振る舞い	明確な I/O 関係、低い複雑性
透明性	システムの動作の理解	可視化されたプロセス、読みやすいコード
安定性	一貫した振る舞い	変更への耐性、保守性
説明可能性	インターフェースの理解	優れたドキュメント、セマンティックな構造、ヘルプテキスト
バグの少なさ	エラーのない動作	コンソールエラー、警告、実行時の問題
小ささ	コンポーネントのサイズ	要素数、スクリプトの肥大化、ページの複雑さ

低い重み（各 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 秒、ポーリング間隔 100 ms）
制御可能性	要素の操作成功率	MCP を介して自動化の準備状況を検証します
安定性	スクリーンショットの一貫性	レイアウトの安定性を視覚的なリグレッション検出によって確認します
説明可能性	要素属性の抽出	ARIA ラベル、セマンティック HTML の検証

Vibium を使用する場面

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

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

❌ 次の場合は 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 は任意です。Vibium がなくても評価を実行できます

---

関連スキル

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

---

クレジットと参考資料

フレームワークの出典

• James Bach と Michael Bolton による ソフトウェアのテスト容易性に関するヒューリスティクス
• 入手先：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 が作成

---

覚えておきましょう

テスト容易性は、後回しにするものではなく、投資すべきものです。

テスト容易性を高めると：

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

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