testability-scoring

可测试性评分

浏览器引擎

主要使用 qe-browser 机群技能（.claude/skills/qe-browser/）作为浏览器引擎。aqe init 会安装 Vibium。当团队已配置 Playwright 测试套件时，旧版 scripts/run-assessment.sh + 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>

快速参考卡

运行评估

方法	命令	使用时机
Shell 脚本	./scripts/run-assessment.sh URL	一次性评估
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);

---

Agent 集成

// 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 稳定性（30s 超时，100ms 轮询）
可控性	元素交互成功率	通过 MCP 验证自动化就绪情况
稳定性	截图一致性	检测视觉回归，确保布局稳定
可解释性	元素属性提取	验证 ARIA 标签和语义化 HTML

何时使用 Vibium

✅ 在以下情况下使用 Vibium：

• 元素稳定性指标（自动等待时长分析）
• 视觉一致性检查（截图比较）
• 原生支持 MCP 的 AI Agent 集成
• 轻量级 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
  • 生产环境稳定性得到验证
  • 社区采用率提高

Agent 协作提示

记忆命名空间

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 贡献）
• Playwright v1.49.0+，具备 AI 能力（主要引擎）
• Vibium v1.0+，集成 MCP（可选增强功能）
• 使用 Chart.js 绘制雷达图

Vibium 资源

• GitHub：https://github.com/VibiumDev/vibium
• MCP 集成：claude mcp add vibium -- npx -y vibium
• 由 Jason Huggins（Selenium／Appium 的创作者）创建

---

请记住

可测试性是一项投资，而非事后考虑。

良好的可测试性可以：

• 减少调试时间
• 加快反馈循环
• 让缺陷更容易被发现
• 支持持续测试

低分 = 高风险。请根据权重 × 影响优先安排改进。