argon-theme/tests/test-mermaid-wait-mechanism.md

Mermaid 库加载等待机制测试

测试目标

验证任务 2.1 的实现：Mermaid 库加载等待机制

实现的功能

1. waitForMermaid() 函数

• ✅ 返回 Promise
• ✅ 检查 Mermaid 库是否已加载
• ✅ 如果已加载，立即返回 true
• ✅ 如果未加载，使用轮询机制等待（每 100ms 检查一次）
• ✅ 设置超时机制（默认 5000ms）
• ✅ 超时后返回 false
• ✅ 记录加载时间和状态日志

2. 集成到渲染流程

• ✅ renderAllCharts() 改为 async 函数
• ✅ 渲染前调用 waitForMermaid() 等待库加载
• ✅ 库加载失败时记录错误并停止渲染
• ✅ init() 函数改为 async 函数
• ✅ 初始化时使用 waitForMermaid() 替代原来的 setInterval

测试场景

场景 1: 库已加载

步骤：

1. 确保 Mermaid 库已加载
2. 调用 waitForMermaid()
3. 验证立即返回 true

预期结果：

• 函数立即返回 true
• 日志显示 "Mermaid 库已加载"

场景 2: 库延迟加载

步骤：

1. 页面加载时 Mermaid 库未加载
2. 调用 waitForMermaid()
3. 500ms 后加载 Mermaid 库
4. 验证函数等待并返回 true

预期结果：

• 函数等待库加载
• 库加载后返回 true
• 日志显示加载耗时（约 500ms）

场景 3: 库加载超时

步骤：

1. 页面加载时 Mermaid 库未加载
2. 调用 waitForMermaid(2000) 设置 2 秒超时
3. 2 秒内库未加载
4. 验证函数超时返回 false

预期结果：

• 函数等待 2 秒后返回 false
• 日志显示 "Mermaid 库加载超时（2000ms）"

场景 4: PJAX 页面切换

步骤：

1. 通过 PJAX 跳转到包含 Mermaid 图表的页面
2. renderAllCharts() 被调用
3. 验证等待库加载后再渲染

预期结果：

• 等待库加载完成
• 成功渲染所有图表
• 不显示原始代码

代码规范检查

✅ JSDoc 注释

/**
 * 等待 Mermaid 库加载
 * 需求 2.6: 清除缓存后首次加载时等待 Mermaid 库完全加载
 * 需求 4.1: 开始渲染前检查 Mermaid 库是否已加载
 * 需求 4.2: Mermaid 库未加载时等待库加载或显示错误提示
 * @param {number} timeout - 超时时间（毫秒），默认 5000ms
 * @returns {Promise<boolean>} 是否加载成功
 */

✅ 代码风格

• Tab 缩进
• 单引号字符串
• 严格相等 (===)
• 语句末尾分号
• 使用 const/let（不使用 var）

✅ 错误处理

• 超时时记录错误日志
• 加载失败时停止渲染
• 提供友好的错误提示

性能考虑

轮询间隔

• 每 100ms 检查一次（平衡响应速度和性能）
• 避免过于频繁的检查

超时设置

• 默认 5000ms（5 秒）
• 可自定义超时时间
• 防止无限等待

日志记录

• 记录加载耗时
• 便于性能分析和调试

需求映射

需求 ID	需求描述	实现状态
2.6	清除缓存后首次加载时等待 Mermaid 库完全加载	✅
4.1	开始渲染前检查 Mermaid 库是否已加载	✅
4.2	Mermaid 库未加载时等待库加载或显示错误提示	✅

下一步

任务 2.1 已完成，可以继续：

• 任务 2.2: 优化 Mermaid 初始化配置
• 任务 2.3: 添加语法错误处理和友好提示
• 任务 2.4: 测试各种图表类型