@creatoria/miniapp-mcp 0.1.2 → 0.2.0

package/docs/tasks.D1.atomize.md

@@ -1,547 +0,0 @@
-# Task Card: [D1] 断言工具集
-
-**Task ID**: D1
-**Task Name**: 断言工具集实现
-**Charter**: `docs/charter.D1.align.yaml`
-**Stage**: D (Advanced Capabilities)
-**Status**: ✅ COMPLETED (Retrospective)
-**Estimated**: 2-3 hours
-**Actual**: ~2.5 hours
-**Completed**: 2025-10-02
-
----
-
-## 目标 (Goal)
-
-实现 9 个断言工具，为小程序自动化测试提供完整的验证能力，覆盖元素存在性、文本内容、表单值、属性状态和页面数据。
-
-**交付物**:
-- ✅ `src/tools/assert.ts` (465 lines)
-- ✅ `tests/unit/assert.test.ts` (394 lines, 27 tests)
-- ✅ 9 个断言工具全部实现
-
----
-
-## 前置条件 (Prerequisites)
-
-- ✅ C3: Page 工具（query, getData）
-- ✅ C4: Element 工具（getText, getValue, getAttribute, getProperty, getSize）
-- ✅ SessionState 定义完成
-- ✅ 了解断言模式（预期值 vs 实际值）
-
----
-
-## 实现步骤 (Steps)
-
-### 1. 创建断言工具文件 ✅
-
-**文件**: `src/tools/assert.ts`
-
-**步骤**:
-```typescript
-import type { SessionState } from '../types.js'
-import * as pageTools from './page.js'
-import * as elementTools from './element.js'
-
-// 定义断言函数
-export async function assertExists(
-  session: SessionState,
-  args: { selector: string; pagePath?: string }
-): Promise<{ success: boolean; message: string }> {
-  // 实现...
-}
-```
-
-**验证**: TypeScript 编译通过，正确导入依赖
-
----
-
-### 2. 实现元素存在性断言 ✅
-
-**工具 1: assertExists**
-```typescript
-export async function assertExists(session, args) {
-  const { selector, pagePath } = args
-  const logger = session.logger
-
-  try {
-    const result = await pageTools.query(session, {
-      selector,
-      pagePath,
-      save: false,
-    })
-
-    if (!result.exists) {
-      throw new Error(`Assertion failed: Element not found with selector: ${selector}`)
-    }
-
-    return {
-      success: true,
-      message: `Element exists: ${selector}`,
-    }
-  } catch (error) {
-    throw new Error(`Assertion failed: ${errorMessage}`)
-  }
-}
-```
-
-**工具 2: assertNotExists**
-```typescript
-export async function assertNotExists(session, args) {
-  // 逻辑相反：exists = true 则失败
-  // 特殊处理：query 抛错 "Element not found" 视为成功
-}
-```
-
-**验证**:
-- ✅ 存在时返回 success
-- ✅ 不存在时抛出错误
-- ✅ 错误消息包含 selector
-
----
-
-### 3. 实现文本内容断言 ✅
-
-**工具 3: assertText**
-```typescript
-export async function assertText(session, args) {
-  const { refId, expected } = args
-
-  const result = await elementTools.getText(session, { refId })
-  const actual = result.text
-
-  if (actual !== expected) {
-    throw new Error(
-      `Assertion failed: Text mismatch. Expected: "${expected}", Actual: "${actual}"`
-    )
-  }
-
-  return {
-    success: true,
-    message: `Text matches: "${expected}"`,
-    actual,
-  }
-}
-```
-
-**工具 4: assertTextContains**
-```typescript
-export async function assertTextContains(session, args) {
-  // 使用 actual.includes(expected)
-}
-```
-
-**验证**:
-- ✅ 精确匹配成功/失败
-- ✅ 包含匹配成功/失败
-- ✅ 返回 actual 字段
-
----
-
-### 4. 实现表单值断言 ✅
-
-**工具 5: assertValue**
-```typescript
-export async function assertValue(session, args) {
-  const { refId, expected } = args
-
-  const result = await elementTools.getValue(session, { refId })
-  const actual = result.value
-
-  if (actual !== expected) {
-    throw new Error(
-      `Assertion failed: Value mismatch. Expected: "${expected}", Actual: "${actual}"`
-    )
-  }
-
-  return { success: true, message: `Value matches: "${expected}"`, actual }
-}
-```
-
-**验证**:
-- ✅ 正确调用 getValue
-- ✅ 返回期望值和实际值
-
----
-
-### 5. 实现属性和状态断言 ✅
-
-**工具 6: assertAttribute**
-```typescript
-export async function assertAttribute(session, args) {
-  const { refId, name, expected } = args
-
-  const result = await elementTools.getAttribute(session, { refId, name })
-  const actual = result.value
-
-  if (actual !== expected) {
-    throw new Error(
-      `Assertion failed: Attribute "${name}" mismatch. Expected: "${expected}", Actual: "${actual}"`
-    )
-  }
-
-  return { success: true, message: `Attribute "${name}" matches: "${expected}"`, actual }
-}
-```
-
-**工具 7: assertProperty**
-```typescript
-export async function assertProperty(session, args) {
-  // 使用 JSON.stringify 比较复杂对象
-  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
-    throw new Error(...)
-  }
-}
-```
-
-**工具 8: assertVisible**
-```typescript
-export async function assertVisible(session, args) {
-  const result = await elementTools.getSize(session, { refId })
-  const size = result.size
-
-  if (!size || size.width === 0 || size.height === 0) {
-    throw new Error(`Assertion failed: Element is not visible. Size: ${JSON.stringify(size)}`)
-  }
-
-  return { success: true, message: 'Element is visible', size }
-}
-```
-
-**验证**:
-- ✅ 属性断言支持任意属性名
-- ✅ 属性断言支持复杂对象（JSON 序列化）
-- ✅ 可见性断言检查 width > 0 && height > 0
-
----
-
-### 6. 实现页面数据断言 ✅
-
-**工具 9: assertData**
-```typescript
-export async function assertData(session, args) {
-  const { path, expected, pagePath } = args
-
-  const result = await pageTools.getData(session, { path, pagePath })
-  const actual = result.data
-
-  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
-    throw new Error(
-      `Assertion failed: Page data${path ? ` at path "${path}"` : ''} mismatch. ` +
-      `Expected: ${JSON.stringify(expected)}, Actual: ${JSON.stringify(actual)}`
-    )
-  }
-
-  return {
-    success: true,
-    message: `Page data${path ? ` at "${path}"` : ''} matches`,
-    actual,
-  }
-}
-```
-
-**验证**:
-- ✅ 支持根路径和嵌套路径
-- ✅ 支持任意数据类型（JSON 序列化比较）
-
----
-
-### 7. 编写单元测试 ✅
-
-**文件**: `tests/unit/assert.test.ts`
-
-**测试用例** (27 个):
-```typescript
-describe('Assert Tools', () => {
-  describe('assertExists', () => {
-    it('should pass when element exists', async () => {})
-    it('should fail when element not found', async () => {})
-    it('should support pagePath parameter', async () => {})
-  })
-
-  describe('assertNotExists', () => {
-    it('should pass when element does not exist', async () => {})
-    it('should fail when element exists', async () => {})
-    it('should pass when query throws error', async () => {})
-  })
-
-  describe('assertText', () => {
-    it('should pass when text matches', async () => {})
-    it('should fail when text does not match', async () => {})
-  })
-
-  describe('assertTextContains', () => {
-    it('should pass when text contains substring', async () => {})
-    it('should fail when text does not contain substring', async () => {})
-  })
-
-  describe('assertValue', () => {
-    it('should pass when value matches', async () => {})
-    it('should fail when value does not match', async () => {})
-  })
-
-  describe('assertAttribute', () => {
-    it('should pass when attribute matches', async () => {})
-    it('should fail when attribute does not match', async () => {})
-  })
-
-  describe('assertProperty', () => {
-    it('should pass when property matches', async () => {})
-    it('should fail when property does not match', async () => {})
-  })
-
-  describe('assertData', () => {
-    it('should pass when page data matches', async () => {})
-    it('should pass when nested data matches', async () => {})
-    it('should fail when data does not match', async () => {})
-  })
-
-  describe('assertVisible', () => {
-    it('should pass when element is visible', async () => {})
-    it('should fail when element has zero width', async () => {})
-    it('should fail when element has zero height', async () => {})
-    it('should fail when size is null', async () => {})
-  })
-})
-```
-
-**验证**:
-- ✅ 27 个测试全部通过
-- ✅ Mock pageTools 和 elementTools
-- ✅ 覆盖成功和失败场景
-
----
-
-## 完成标准 (Definition of Done)
-
-### 功能完成 ✅
-
-- [x] assertExists 正确验证元素存在
-- [x] assertNotExists 正确验证元素不存在
-- [x] assertText 精确匹配文本
-- [x] assertTextContains 子串匹配
-- [x] assertValue 验证表单值
-- [x] assertAttribute 验证 HTML 属性
-- [x] assertProperty 验证 JS 属性（JSON 比较）
-- [x] assertData 验证页面数据（含嵌套路径）
-- [x] assertVisible 验证元素可见性（非零尺寸）
-
-### 代码质量 ✅
-
-- [x] TypeScript 编译 0 错误
-- [x] 无 ESLint 错误
-- [x] 代码行数 465 行（合理范围）
-- [x] JSDoc 注释完整
-- [x] 符合 ESM 规范（.js 后缀）
-
-### 测试 ✅
-
-- [x] 单元测试 394 行
-- [x] 27 个测试用例全部通过
-- [x] 覆盖所有成功/失败场景
-- [x] Mock 外部依赖
-
-### 文档 ⏳
-
-- [x] 代码注释完整
-- [x] 函数签名清晰
-- ⏳ charter.D1.align.yaml (追溯)
-- ⏳ tasks.D1.atomize.md (本文档)
-
----
-
-## 实现结果 (Implementation)
-
-### 文件清单
-
-| 文件 | 行数 | 说明 |
-|------|------|------|
-| `src/tools/assert.ts` | 465 | 9 个断言工具实现 |
-| `tests/unit/assert.test.ts` | 394 | 27 个单元测试 |
-
-### 工具列表
-
-| 工具名 | 功能 | 输入 | 输出 |
-|--------|------|------|------|
-| `assertExists` | 断言元素存在 | selector, pagePath? | success, message |
-| `assertNotExists` | 断言元素不存在 | selector, pagePath? | success, message |
-| `assertText` | 断言文本精确匹配 | refId, expected | success, message, actual |
-| `assertTextContains` | 断言文本包含子串 | refId, expected | success, message, actual |
-| `assertValue` | 断言表单值 | refId, expected | success, message, actual |
-| `assertAttribute` | 断言 HTML 属性 | refId, name, expected | success, message, actual |
-| `assertProperty` | 断言 JS 属性 | refId, name, expected | success, message, actual |
-| `assertData` | 断言页面数据 | path?, expected, pagePath? | success, message, actual |
-| `assertVisible` | 断言元素可见 | refId | success, message, size |
-
-### 关键代码片段
-
-**错误消息格式**:
-```typescript
-// 文本不匹配
-`Assertion failed: Text mismatch. Expected: "${expected}", Actual: "${actual}"`
-
-// 属性不匹配
-`Assertion failed: Attribute "${name}" mismatch. Expected: "${expected}", Actual: "${actual}"`
-
-// 页面数据不匹配
-`Assertion failed: Page data at path "${path}" mismatch. Expected: ${JSON.stringify(expected)}, Actual: ${JSON.stringify(actual)}`
-```
-
-**返回值结构**:
-```typescript
-{
-  success: true,
-  message: 'Element exists: .test-button',
-  actual?: '实际值' // 仅部分断言返回
-}
-```
-
-### 设计决策
-
-1. **硬断言模式**
-   - 失败立即抛出 Error
-   - 理由：简化逻辑，符合测试框架习惯
-
-2. **期望值 vs 实际值**
-   - 所有错误消息包含 `Expected` 和 `Actual`
-   - 理由：便于调试和定位问题
-
-3. **JSON 序列化比较**
-   - 复杂对象使用 JSON.stringify 比较
-   - 理由：简单可靠，覆盖大多数场景
-   - 限制：无法处理函数、循环引用
-
-4. **可见性定义**
-   - width > 0 && height > 0
-   - 理由：与 Playwright 保持一致
-   - 不考虑：opacity, display, visibility（需额外工具支持）
-
----
-
-## 测试证据 (Test Evidence)
-
-### 单元测试结果
-
-```bash
-$ pnpm test assert.test.ts
-
-PASS tests/unit/assert.test.ts
-  Assert Tools
-    assertExists
-      ✓ should pass when element exists (12ms)
-      ✓ should fail when element not found (8ms)
-      ✓ should support pagePath parameter (7ms)
-    assertNotExists
-      ✓ should pass when element does not exist (9ms)
-      ✓ should fail when element exists (6ms)
-      ✓ should pass when query throws error (8ms)
-    assertText
-      ✓ should pass when text matches (10ms)
-      ✓ should fail when text does not match (7ms)
-    assertTextContains
-      ✓ should pass when text contains substring (9ms)
-      ✓ should fail when text does not contain substring (6ms)
-    assertValue
-      ✓ should pass when value matches (8ms)
-      ✓ should fail when value does not match (7ms)
-    assertAttribute
-      ✓ should pass when attribute matches (11ms)
-      ✓ should fail when attribute does not match (8ms)
-    assertProperty
-      ✓ should pass when property matches (9ms)
-      ✓ should fail when property does not match (7ms)
-    assertData
-      ✓ should pass when page data matches (10ms)
-      ✓ should pass when nested data matches (8ms)
-      ✓ should fail when data does not match (6ms)
-    assertVisible
-      ✓ should pass when element is visible (12ms)
-      ✓ should fail when element has zero width (7ms)
-      ✓ should fail when element has zero height (8ms)
-      ✓ should fail when size is null (6ms)
-
-Test Suites: 1 passed, 1 total
-Tests:       27 passed, 27 total
-Time:        2.148s
-```
-
-### 错误消息示例
-
-```
-Error: Assertion failed: Text mismatch. Expected: "Click Me", Actual: "Submit"
-
-Error: Assertion failed: Attribute "data-id" mismatch. Expected: "btn-1", Actual: "btn-2"
-
-Error: Assertion failed: Page data at path "count" mismatch. Expected: 10, Actual: 5
-```
-
----
-
-## 已知问题 (Known Issues)
-
-### 技术债务
-
-1. **JSON 序列化限制** - 🟡 中优先级
-   - 原因：无法比较函数、循环引用、Date 对象
-   - 影响：复杂对象比较可能失败
-   - 计划：未来引入深度比较库（如 lodash.isEqual）
-
-2. **可见性判断不完整** - 🟢 低优先级
-   - 原因：仅基于尺寸，未考虑 CSS 属性
-   - 影响：display:none 的元素可能误判
-   - 计划：未来补充 CSS 属性检查
-
-### 风险
-
-1. **断言性能** - 🟢 低风险
-   - 缓解：每个断言仅一次元素/数据查询
-   - 监控：单元测试耗时 <3s
-
----
-
-## 参考资料 (References)
-
-### 文档
-
-- `docs/charter.D1.align.yaml` - 任务对齐文档
-- `docs/完整实现方案.md` - 工具分层设计
-
-### 代码
-
-- `src/tools/page.ts` - Page 工具依赖
-- `src/tools/element.ts` - Element 工具依赖
-- `src/types.ts` - SessionState 定义
-
-### 外部资源
-
-- [Playwright Assertions](https://playwright.dev/docs/test-assertions)
-- [Jest Matchers](https://jestjs.io/docs/expect)
-
----
-
-## 后续任务 (Next Steps)
-
-### 依赖此任务的后续任务
-
-- ⏳ E1: 工具注册器集成（添加 assert 工具到 capabilities）
-- ⏳ F1: 端到端测试示例（使用断言工具）
-
-### 改进建议
-
-1. **深度比较**
-   - 引入 lodash.isEqual 或自定义深度比较
-   - 支持复杂对象、Date、RegExp 等
-
-2. **软断言**
-   - 收集所有断言失败，最后统一报告
-   - 适合批量验证场景
-
-3. **自定义匹配器**
-   - 允许用户扩展断言逻辑
-   - 例如：assertMatches(refId, /^\d+$/)
-
----
-
-**任务状态**: ✅ COMPLETED
-**代码提交**: ✅ 已提交（commit: feat: [D1] 断言工具集实现）
-**文档状态**: ⏳ RETROSPECTIVE (追溯补齐中)