argon-theme/tests/test-pjax-mermaid-rendering.md

PJAX Mermaid 渲染测试报告

测试目标

验证 PJAX 页面切换后 Mermaid 代码块能被正确检测和渲染。

测试环境

• 测试日期: 2024-01-22
• 主题版本: Argon
• 浏览器: Chrome/Firefox/Safari
• 测试文件: argontheme.js (行 3247-3255, 4786-5400)

测试用例

测试用例 1: PJAX 页面切换后的代码块检测

需求: 1.1, 1.2, 3.1-3.5

测试步骤:

1. 在首页点击包含 Mermaid 图表的文章卡片
2. 等待 PJAX 加载完成
3. 检查控制台日志，确认检测到 Mermaid 代码块
4. 检查页面 DOM，确认代码块被正确识别

预期结果:

• ✅ PJAX complete 事件触发后调用 MermaidRenderer.renderAllCharts()
• ✅ 控制台显示: 检测到 X 个未渲染的 Mermaid 代码块
• ✅ 代码块元素被正确识别（<pre><code class="language-mermaid"> 或 <pre><code class="mermaid">）
• ✅ 已渲染的代码块被过滤（不会重复渲染）

实际结果:

状态: ⏳ 待测试

---

测试用例 2: PJAX 页面切换后的图表渲染

需求: 1.3, 1.4, 4.1-4.6

测试步骤:

1. 在首页点击包含 Mermaid 图表的文章卡片
2. 等待 PJAX 加载完成
3. 观察页面上的 Mermaid 代码块
4. 检查是否显示为 SVG 图表而不是原始文本

预期结果:

• ✅ 代码块被替换为 .mermaid-container 容器
• ✅ 容器内包含渲染后的 SVG 图表
• ✅ 图表正常显示，不是原始文本
• ✅ 控制台显示: 准备渲染图表: mermaid-chart-xxx
• ✅ 控制台显示: 图表渲染成功: mermaid-chart-xxx

实际结果:

状态: ⏳ 待测试

---

测试用例 3: 多次 PJAX 跳转不会重复渲染

需求: 1.3, 3.5, 16.1-16.5

测试步骤:

1. 从首页跳转到文章 A（包含 Mermaid 图表）
2. 从文章 A 跳转到文章 B（包含 Mermaid 图表）
3. 从文章 B 返回文章 A
4. 检查图表是否重复渲染

预期结果:

• ✅ 每次跳转前调用 cleanupMermaidInstances() 清理旧实例
• ✅ 控制台显示: Mermaid 实例已清理
• ✅ 每次跳转后重新渲染图表
• ✅ 不会出现重复的图表或错误
• ✅ 渲染状态标记正确更新（data-mermaid-rendered）

实际结果:

状态: ⏳ 待测试

---

测试用例 4: PJAX 加载失败的降级处理

需求: 7.1-7.4

测试步骤:

1. 模拟 PJAX 加载失败（网络错误或超时）
2. 观察页面行为
3. 检查错误提示

预期结果:

• ✅ 页面回退到传统的页面跳转
• ✅ Mermaid 图表在新页面正常渲染
• ✅ 控制台记录错误信息
• ✅ 用户体验不受影响

实际结果:

状态: ⏳ 待测试

---

测试用例 5: 不同格式的 Mermaid 代码块

需求: 3.1-3.4

测试步骤:

1. 创建包含不同格式 Mermaid 代码块的测试页面:
   • <pre><code class="language-mermaid">
   • <pre><code class="mermaid">
   • <div class="mermaid-from-codeblock">
2. 通过 PJAX 跳转到测试页面
3. 检查所有格式的代码块是否都被检测和渲染

预期结果:

• ✅ 所有格式的代码块都被检测到
• ✅ 所有格式的代码块都被正确渲染
• ✅ 控制台显示检测到的代码块数量正确

实际结果:

状态: ⏳ 待测试

---

测试用例 6: 页面刷新后的渲染

需求: 1.5

测试步骤:

1. 通过 PJAX 跳转到包含 Mermaid 图表的文章
2. 刷新页面（F5 或 Ctrl+R）
3. 观察图表是否正常渲染

预期结果:

• ✅ 页面刷新后图表正常渲染
• ✅ 渲染效果与 PJAX 跳转一致
• ✅ 没有重复渲染或错误

实际结果:

状态: ⏳ 待测试

---

代码审查

PJAX 集成代码 (argontheme.js 行 3247-3255)

// Mermaid 图表渲染（需求 3.6: 页面切换时重新渲染）
try {
	if (typeof MermaidRenderer !== 'undefined' && MermaidRenderer.renderAllCharts) {
		MermaidRenderer.renderAllCharts();
	}
} catch (err) {
	ArgonDebug.error('MermaidRenderer.renderAllCharts failed:', err);
}

审查结果:

• ✅ 正确检查 MermaidRenderer 是否存在
• ✅ 正确检查 renderAllCharts 方法是否存在
• ✅ 使用 try-catch 包裹，避免错误阻塞其他功能
• ✅ 错误日志记录完整

---

清理代码 (argontheme.js 行 2883-2915)

function cleanupMermaidInstances() {
	try {
		// 清理已渲染的图表记录
		if (typeof MermaidRenderer !== 'undefined' && MermaidRenderer.rendered) {
			const count = MermaidRenderer.rendered.size;
			MermaidRenderer.rendered.clear();
			if (count > 0) {
				ArgonDebug.log(`已清理 ${count} 个 Mermaid 图表记录`);
			}
		}
		
		// 移除 Mermaid 容器的事件监听器
		document.querySelectorAll('.mermaid-container').forEach(function(container) {
			// 移除工具栏事件监听器
			const toolbar = container.querySelector('.mermaid-toolbar');
			if (toolbar) {
				// 克隆节点以移除所有事件监听器
				// ...
			}
		});
		
		ArgonDebug.log('Mermaid 实例已清理');
	} catch(e) {
		ArgonDebug.warn('清理 Mermaid 实例失败:', e);
	}
}

审查结果:

• ✅ 正确清理渲染记录（MermaidRenderer.rendered.clear()）
• ✅ 移除事件监听器，避免内存泄漏
• ✅ 使用 try-catch 包裹，避免清理失败影响其他功能
• ✅ 日志记录完整

---

检测代码 (argontheme.js 行 4890-4930)

detectMermaidBlocks() {
	const blocks = [];
	
	// 需求 3.1: 扫描所有 <pre><code> 元素
	// 需求 3.2: 识别 language-mermaid 类名
	document.querySelectorAll('pre code.language-mermaid').forEach(code => {
		// 需求 3.5: 过滤已渲染的代码块
		if (!this.isRendered(code)) {
			blocks.push(code);
		}
	});
	
	// 需求 3.3: 识别 mermaid 类名
	document.querySelectorAll('pre code.mermaid').forEach(code => {
		// 需求 3.5: 过滤已渲染的代码块
		if (!this.isRendered(code)) {
			blocks.push(code);
		}
	});
	
	this.logDebug(`检测到 ${blocks.length} 个未渲染的 Mermaid 代码块`);
	return blocks;
}

审查结果:

• ✅ 正确扫描 <pre><code> 元素
• ✅ 正确识别 language-mermaid 和 mermaid 类名
• ✅ 正确过滤已渲染的代码块
• ✅ 日志记录完整
• ✅ 符合需求 3.1-3.5

---

渲染状态检查 (argontheme.js 行 4932-4948)

isRendered(element) {
	// 检查元素是否有渲染标记
	if (element.hasAttribute('data-mermaid-rendered')) {
		return true;
	}
	
	// 检查元素是否在 mermaid-container 容器中
	if (element.closest('.mermaid-container') !== null) {
		return true;
	}
	
	return false;
}

审查结果:

• ✅ 正确检查 data-mermaid-rendered 属性
• ✅ 正确检查是否在 .mermaid-container 容器中
• ✅ 避免重复渲染
• ✅ 符合需求 3.5

---

测试执行计划

阶段 1: 手动测试（推荐）

1. 准备测试环境:

   • 在 WordPress 后台创建测试文章
   • 在文章中添加 Mermaid 代码块
   • 发布文章

2. 执行测试:

   • 打开浏览器开发者工具（F12）
   • 切换到 Console 标签
   • 从首页点击文章卡片
   • 观察控制台日志和页面渲染效果
   • 记录测试结果

3. 测试不同场景:

   • 测试多次 PJAX 跳转
   • 测试页面刷新
   • 测试不同格式的代码块
   • 测试错误处理

阶段 2: 自动化测试（可选）

如果需要自动化测试，可以使用以下工具:

• Selenium WebDriver
• Puppeteer
• Playwright

---

已知问题

问题 1: 代码块格式不统一

描述: 不同的 Markdown 编辑器可能生成不同格式的代码块

影响: 可能导致某些格式的代码块无法被检测

解决方案:

• 已在 detectMermaidBlocks() 中支持多种格式
• 需要测试验证所有格式都能正常工作

---

问题 2: PJAX 加载时机

描述: PJAX complete 事件触发时，DOM 可能还未完全更新

影响: 可能导致检测不到代码块

解决方案:

• 已在 PJAX complete 事件中调用渲染
• 如果仍有问题，可以添加延迟或使用 MutationObserver

---

测试结论

总体评估: ⏳ 待测试

通过的测试用例: 0/6

失败的测试用例: 0/6

待测试的用例: 6/6

---

下一步行动

1. ✅ 代码审查完成 - 代码实现符合需求
2. ⏳ 执行手动测试 - 验证实际效果
3. ⏳ 记录测试结果 - 更新本文档
4. ⏳ 修复发现的问题 - 如果有
5. ⏳ 更新任务状态 - 标记为完成

---

测试检查清单

• 测试用例 1: PJAX 页面切换后的代码块检测
• 测试用例 2: PJAX 页面切换后的图表渲染
• 测试用例 3: 多次 PJAX 跳转不会重复渲染
• 测试用例 4: PJAX 加载失败的降级处理
• 测试用例 5: 不同格式的 Mermaid 代码块
• 测试用例 6: 页面刷新后的渲染
• 代码审查: PJAX 集成代码
• 代码审查: 清理代码
• 代码审查: 检测代码
• 代码审查: 渲染状态检查

---

附录: 测试数据

测试用的 Mermaid 代码

流程图 (Flowchart)

flowchart TD
    A[开始] --> B{是否登录?}
    B -->|是| C[显示主页]
    B -->|否| D[跳转登录页]
    C --> E[结束]
    D --> E

时序图 (Sequence Diagram)

sequenceDiagram
    participant 用户
    participant 浏览器
    participant 服务器
    用户->>浏览器: 点击文章
    浏览器->>服务器: PJAX 请求
    服务器-->>浏览器: 返回 HTML
    浏览器->>浏览器: 渲染 Mermaid

ER 图 (Entity Relationship Diagram)

erDiagram
    USER ||--o{ POST : writes
    USER {
        int id
        string name
        string email
    }
    POST {
        int id
        string title
        text content
    }

---

文档版本: 1.0
最后更新: 2024-01-22
测试负责人: Kiro AI Agent