testing-blocks

测试区块

本技能将指导你在 AEM Edge Delivery Services 项目中测试代码变更。测试遵循价值与成本相权衡的理念：只有当测试带来的价值超过创建和维护测试的成本时，才创建并维护测试。

重要：必须进行浏览器验证。若无法提供在真实浏览器环境中进行功能测试的证明，就无法完成本技能。

相关技能

• content-driven-development：CDD 期间创建的内容可作为测试依据
• building-blocks：在第 5 步中调用本技能，以进行全面测试
• block-collection-and-party：可能会提供类似区块的参考测试模式

何时使用本技能

在以下情况下使用本技能：

• ✅ 实现或修改区块后
• ✅ 更改核心脚本（scripts.js、delayed.js、aem.js）后
• ✅ 更改样式（styles.css、lazy-styles.css）后
• ✅ 更改会影响功能的配置后
• ✅ 提交任何包含代码变更的拉取请求前

本技能通常由 building-blocks 技能在第 5 步（测试实现）中调用。

测试工作流

跟踪进度：

• 第 1 步：运行 lint 并修复问题
• 第 2 步：执行浏览器验证（必须）
• 第 3 步：确定是否需要单元测试（可选）
• 第 4 步：运行现有测试并确认通过

第 1 步：运行 Lint

先运行 lint，以发现代码质量问题：

npm run lint

如果 lint 失败：

npm run lint:fix

手动修复自动修复无法处理的剩余问题。

成功标准：

• ✅ Lint 通过且无错误
• ✅ 代码符合项目规范

完成条件：npm run lint 通过且无错误

---

第 2 步：浏览器验证（必须）

重要：必须在真实浏览器中进行测试，并提供证明。

测试内容

在浏览器中加载测试内容 URL，并验证：

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

测试方法

根据你可用的工具，选择最合适的方法：

选项 1：浏览器/Playwright MCP（推荐）

如果你有可用的 MCP 浏览器或 Playwright 工具，请直接使用：

• 导航到测试内容 URL
• 获取无障碍快照，以检查渲染后的内容（交互测试优先使用此方法）
• 在不同视口下截取屏幕截图，进行视觉验证
  • 考虑同时截取整页截图和被测区块的元素专属截图
• 根据需要与元素交互
• 对于可使用工具的 Agent，此方法效率最高

选项 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：手动浏览器测试

使用标准网页浏览器和开发者工具：

1. 导航到测试内容：http://localhost:3000/path/to/test/content
2. 使用浏览器开发者工具的响应式模式测试不同视口：
   • 移动端：<600px（例如 375px）
   • 平板端：600-900px（例如 768px）
   • 桌面端：>900px（例如 1200px）
3. 检查每种视口下的控制台是否有错误
4. 截取屏幕截图作为证明（使用浏览器截图工具或开发者工具）

根据验收标准进行验证

如果提供了验收标准（来自 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

如果测试失败：

1. 仔细阅读错误消息
2. 运行单个测试以定位问题：npm test -- path/to/test.js
3. 修复代码，或在预期结果发生变化时更新测试
4. 重新运行完整测试套件

成功标准：

• ✅ 所有现有测试均通过
• ✅ 未引入回归问题

完成条件： npm test 通过且没有失败项

故障排除

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

常见问题：

测试失败

• 仔细阅读错误消息
• 运行单个测试：npm test -- path/to/test.js
• 修复代码或更新测试

代码检查失败

• 运行 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 技能会在第 5 步（测试实现）期间调用此技能。

从 building-blocks 接收的输入：

• 正在测试的区块名称
• 测试内容 URL（来自 CDD 第 4 步）
• 需要测试的任何变体
• 用于对照验证的现有实现、设计或模型截图（如有）
• 需要验证的验收标准（来自 CDD 第 2 步）

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

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