SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场testing-blocks

testing-blocks

测试与质量

查看项目

更新于 10-15 08:31

技能介绍

Testing Blocks 是一个面向 AEM Edge Delivery Services 项目的测试技能，用于在打开拉取请求之前验证代码改动。它适用于修改或新增区块、修改核心脚本（scripts.js、delayed.js、aem.js）、修改样式（styles.css、lazy-styles.css），以及修改影响功能的配置之后。该技能通常由 building-blocks 技能在测试实现阶段调用。

测试理念 该技能遵循价值与成本权衡的测试理念：当测试带来的价值超过创建和维护成本时，才创建和维护测试。

关键要求 浏览器验证是强制性的。必须提供在真实浏览器环境中进行功能测试的证明，否则不能完成该技能。

相关技能

  • content-driven-development：在 CDD 期间创建的测试内容可作为测试基础。
  • building-blocks：在测试实现阶段调用本技能进行综合测试。
  • block-collection-and-party：可能提供来自类似区块的参考测试模式。

测试工作流 工作流包含四个步骤，需跟踪进度：

  1. 运行 lint 并修复问题
  2. 执行浏览器验证（强制）
  3. 判断是否需要单元测试（可选）
  4. 运行现有测试并确认通过

步骤 1：运行 Linting 先运行 lint 以捕获代码质量问题：

npm run lint

如果 lint 失败：

npm run lint:fix

然后手动修复自动修复无法处理的问题。 成功标准：lint 无错误通过，代码符合项目标准。当 npm run lint 无错误通过时标记完成。

步骤 2：浏览器验证（强制） 必须在真实浏览器中测试并提供证明。

需要测试的内容：

  • 区块/功能正确渲染
  • 响应式行为（移动端、平板、桌面视口）
  • 无控制台错误
  • 视觉外观符合需求/验收标准
  • 交互行为正常（如适用）
  • 所有变体正确渲染（如适用）

测试方法（根据可用工具选择）：

选项 1：浏览器/Playwright MCP（推荐） 如果可用 MCP 浏览器或 Playwright 工具，直接使用：导航到测试内容 URL；获取可访问性快照以检查渲染内容（交互验证首选）；在不同视口截图进行视觉验证；考虑整页截图和被测区块的元素级截图；按需与元素交互。这是有工具访问权限的代理最高效的方式。

选项 2：Playwright 自动化 编写一个或多个临时测试脚本，用 Playwright 验证功能并捕获快照/截图。示例脚本（临时，不要提交）：

// 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：手动浏览器测试 使用标准浏览器和开发者工具：导航到测试内容 http://localhost:3000/path/to/test/content；使用开发者工具的响应式模式测试视口：移动端 <600px（如 375px）、平板 600-900px（如 768px）、桌面 >900px（如 1200px）；在每个视口检查控制台错误；截图作为证明。

对照验收标准验证： 如果提供了验收标准（来自 CDD 步骤 2）：逐条审查标准；测试提到的具体场景；验证所有标准均满足。 如果提供了设计/原型截图：将实现与设计对比；验证视觉一致性；记录任何有意偏离。

测试证明：必须提供浏览器中测试内容的截图（至少一个视口）；确认无控制台错误；确认满足验收标准（如提供）。 成功标准：所有测试内容正确加载和渲染；响应式行为在各视口验证通过；无控制台错误；截图作为证明；验收标准验证通过（如提供）。当浏览器测试完成并有截图证明时标记完成。

步骤 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

如果测试失败：仔细阅读错误信息；运行单个测试隔离问题：npm test -- path/to/test.js；修复代码或更新测试（如果预期已改变）；重新运行完整测试套件。 成功标准：所有现有测试通过；未引入回归。当 npm test 无失败通过时标记完成。

故障排除 详细故障排除指南参见 references/troubleshooting.md。

常见问题：

  • 测试失败：仔细阅读错误信息；运行单个测试 npm test -- path/to/test.js；修复代码或更新测试。
  • Linting 失败：运行 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 技能在测试实现阶段调用本技能。

从 building-blocks 接收的输入：

  • 正在测试的区块名称
  • 测试内容 URL（来自 CDD 步骤 4）
  • 需要测试的变体
  • 用于对照验证的现有实现/设计/原型截图（如提供）
  • 需要验证的验收标准（来自 CDD 步骤 2）

返回给 building-blocks 的预期输出：

  • 确认所有测试步骤完成
  • 浏览器测试截图作为证明
  • 确认 lint 通过
  • 确认测试通过
  • 发现并解决的任何问题