qe-visual-accessibility

QE 视觉无障碍

用途

指导使用 v3 的视觉与无障碍测试功能，包括截图比较、响应式设计验证以及 WCAG 2.2 合规性验证。

激活条件

• 测试视觉外观时
• 验证响应式设计时
• 检查无障碍合规性时
• 检测视觉回归时
• 测试跨浏览器渲染时

快速入门

# Visual regression test
aqe visual test --baseline production --current staging

# Responsive design test
aqe visual responsive --url https://example.com --viewports all

# Accessibility audit
aqe a11y audit --url https://example.com --standard wcag22-aa

# Cross-browser test
aqe visual cross-browser --url https://example.com --browsers chrome,firefox,safari

Agent 工作流

// Visual regression testing
Task("Run visual regression", `
  Compare staging against production:
  - Capture screenshots of key pages
  - Detect pixel differences
  - Flag significant visual changes
  - Generate visual diff report
`, "qe-visual-tester")

// Accessibility audit
Task("Audit accessibility", `
  Run WCAG 2.2 AA compliance audit:
  - Check color contrast ratios
  - Verify keyboard navigation
  - Test screen reader compatibility
  - Validate ARIA labels
  Generate compliance report with fix suggestions.
`, "qe-accessibility-agent")

浏览器引擎

此技能中的所有浏览器自动化均使用 qe-browser fleet 技能（Vibium 引擎）。请参阅 .claude/skills/qe-browser/SKILL.md。vibium 二进制文件由 aqe init 安装。

视觉测试操作

1. 视觉回归（通过 qe-browser）

# Establish baselines for the pages we care about
for path in / /login /dashboard /settings; do
  slug=$(echo "$path" | tr '/' '_' | sed 's/^_//' || echo root)
  vibium go "https://production.example.com$path" && vibium wait load
  node .claude/skills/qe-browser/scripts/visual-diff.js --name "baseline_${slug:-root}"
done

# Compare staging against those baselines
for path in / /login /dashboard /settings; do
  slug=$(echo "$path" | tr '/' '_' | sed 's/^_//' || echo root)
  vibium go "https://staging.example.com$path" && vibium wait load
  node .claude/skills/qe-browser/scripts/visual-diff.js \
    --name "baseline_${slug:-root}" --threshold 0.001  # 0.1% pixel diff
done

通过将差异比较范围限定为排除动态区域（时间戳、实时计数）的选择器来忽略这些区域：

node .claude/skills/qe-browser/scripts/visual-diff.js \
  --name hero --selector "main > .content"

传统的编程式 TypeScript API（仍可用于偏好使用它而非通过 shell 调用的测试）：

await visualTester.compareScreenshots({
  baseline: {
    source: 'production',
    pages: ['/', '/login', '/dashboard', '/settings']
  },
  current: {
    source: 'staging',
    pages: ['/', '/login', '/dashboard', '/settings']
  },
  comparison: {
    threshold: 0.1,  // 0.1% pixel difference
    antialiasing: true,
    ignoreRegions: ['#dynamic-content', '.timestamp']
  }
});

2. 响应式测试

await responsiveTester.test({
  url: 'https://example.com',
  viewports: [
    { name: 'mobile', width: 375, height: 667 },
    { name: 'tablet', width: 768, height: 1024 },
    { name: 'desktop', width: 1920, height: 1080 }
  ],
  checks: {
    layoutShift: true,
    contentOverflow: true,
    touchTargets: true,
    fontScaling: true
  }
});

3. 无障碍审计

await accessibilityAgent.audit({
  url: 'https://example.com',
  standard: 'WCAG22-AA',
  checks: {
    perceivable: {
      colorContrast: true,
      textAlternatives: true,
      captions: true
    },
    operable: {
      keyboardAccessible: true,
      noTimingIssues: true,
      navigable: true
    },
    understandable: {
      readable: true,
      predictable: true,
      inputAssistance: true
    },
    robust: {
      compatible: true,
      parseErrors: true
    }
  }
});

4. 跨浏览器测试

await visualTester.crossBrowser({
  url: 'https://example.com',
  browsers: ['chrome', 'firefox', 'safari', 'edge'],
  versions: 'latest-2',
  comparisons: {
    betweenBrowsers: true,
    betweenVersions: true,
    againstBaseline: true
  }
});

WCAG 2.2 检查清单

级别	标准	可自动测试
A	非文本内容	✅
A	信息和关系	部分
A	颜色对比度（4.5:1）	✅
A	键盘可访问	✅
A	焦点可见	✅
AA	重排	✅
AA	文本间距	✅
AAA	增强对比度（7:1）	✅

视觉测试报告

interface VisualReport {
  summary: {
    pagesCompared: number;
    differencesFound: number;
    passRate: number;
  };
  comparisons: {
    page: string;
    viewport: string;
    baseline: string;
    current: string;
    diff: string;
    diffPercentage: number;
    status: 'pass' | 'fail' | 'review';
  }[];
  accessibility: {
    violations: A11yViolation[];
    passes: number;
    incomplete: number;
    score: number;
  };
  responsive: {
    viewport: string;
    issues: ResponsiveIssue[];
  }[];
}

无障碍报告

interface AccessibilityReport {
  summary: {
    score: number;
    violations: number;
    warnings: number;
    passes: number;
  };
  violations: {
    id: string;
    impact: 'critical' | 'serious' | 'moderate' | 'minor';
    description: string;
    wcag: string[];
    elements: {
      selector: string;
      html: string;
      issue: string;
      fix: string;
    }[];
  }[];
  compliance: {
    wcagLevel: 'A' | 'AA' | 'AAA';
    criteriasMet: number;
    criteriasTotal: number;
  };
}

CI/CD 集成

visual_testing:
  on_pr:
    - capture_screenshots
    - compare_to_baseline
    - run_a11y_audit

  thresholds:
    visual_diff: 0.1
    a11y_violations: 0

  artifacts:
    - screenshots/
    - diffs/
    - a11y-report.html

协作

主要 Agent：qe-visual-tester、qe-accessibility-agent、qe-responsive-tester 协调者：qe-visual-coordinator 相关技能：qe-test-execution、qe-quality-assessment