skillhub/docs/prds/file-preview-syntax-highlighting-supplements/05-test-plan.md

name	description	type
文件预览语法高亮测试计划	单元测试、集成测试、性能测试的详细计划和覆盖率矩阵	test-plan

测试计划：文件预览语法高亮

1. 单元测试

测试类：CodeRenderer.test.tsx

位置：web/src/features/skill/__tests__/code-renderer.test.tsx

测试方法	覆盖用例	描述
renders Python code with syntax highlighting	AC-P-001	验证 Python 代码正确渲染，关键字着色
renders Shell script with syntax highlighting	AC-P-002	验证 Shell 脚本正确渲染，命令着色
renders JSON with syntax highlighting	AC-P-003	验证 JSON 正确渲染，键值着色
renders YAML with syntax highlighting	AC-P-004	验证 YAML 正确渲染，结构清晰
falls back to plain text for unknown language	AC-E-001	验证无法识别语言时降级到纯文本
handles empty code gracefully	AC-E-005	验证空内容不报错
handles Unicode characters correctly	AC-B-006	验证 Unicode 字符（中文）正确显示
escapes HTML tags to prevent XSS	AC-S-001	验证 HTML 标签被转义
applies correct CSS classes for theming	AC-P-007	验证 CSS 类名与 Markdown 一致

测试数据：

const pythonCode = `def hello():\n    print("Hello, World!")`
const shellCode = `#!/bin/bash\necho "Hello"`
const jsonCode = `{"key": "value", "number": 123}`
const yamlCode = `key: value\nnumber: 123`
const xssCode = `<script>alert('XSS')</script>`

---

测试类：file-type-utils.test.ts

位置：web/src/features/skill/__tests__/file-type-utils.test.ts

测试方法	覆盖用例	描述
getLanguageForHighlight returns correct language for .py	AC-P-006	验证 .py → python
getLanguageForHighlight returns correct language for .sh	AC-P-006	验证 .sh → bash
getLanguageForHighlight returns correct language for .json	AC-P-006	验证 .json → json
getLanguageForHighlight returns correct language for .yaml	AC-P-006	验证 .yaml → yaml
getLanguageForHighlight returns null for unknown extension	AC-E-001	验证 .custom → null
getLanguageForHighlight handles case-insensitive extensions	-	验证 .PY → python
getLanguageForHighlight handles multiple extensions for same language	-	验证 .yml 和 .yaml 都映射到 yaml

测试数据：

const testCases = [
  { ext: '.py', expected: 'python' },
  { ext: '.sh', expected: 'bash' },
  { ext: '.bash', expected: 'bash' },
  { ext: '.json', expected: 'json' },
  { ext: '.yaml', expected: 'yaml' },
  { ext: '.yml', expected: 'yaml' },
  { ext: '.custom', expected: null },
]

---

2. 集成测试

测试类：file-preview-dialog.test.tsx

位置：web/src/features/skill/__tests__/file-preview-dialog.test.tsx

测试方法	覆盖用例	描述
renders CodeRenderer for Python files under 500KB	AC-P-001, AC-B-001	验证小文件使用语法高亮
renders plain text for files over 500KB	AC-B-002	验证大文件降级到纯文本
shows download-only for files over 1MB	AC-B-004	验证超大文件只显示下载
renders MarkdownRenderer for .md files	AC-P-005	验证 Markdown 文件使用现有渲染器
switches renderer when file changes	AC-P-005	验证切换文件时渲染器正确切换
shows loading state while fetching file	-	验证 loading 状态显示
handles network error gracefully	AC-E-004	验证网络错误显示提示
copy button works correctly	AC-P-009	验证复制功能
download button works correctly	AC-P-010	验证下载功能

测试数据：

const smallPythonFile = { path: 'main.py', size: 10240, content: '...' }
const largePythonFile = { path: 'large.py', size: 512000, content: '...' }
const hugePythonFile = { path: 'huge.py', size: 1100000, content: '...' }
const markdownFile = { path: 'README.md', size: 5000, content: '...' }

---

测试类：skill-detail-page.test.tsx（扩展现有测试）

位置：web/src/features/skill/__tests__/skill-detail-page.test.tsx

测试方法	覆盖用例	描述
file tree shows syntax-highlighted preview on click	AC-P-001	端到端测试：点击文件树 → 显示语法高亮
file preview dialog closes correctly	-	验证关闭弹窗功能

---

3. 性能测试

测试场景：渲染性能

工具：Jest + Performance API

测试场景	目标指标	测试方法
100KB Python 文件渲染时间	< 200ms	使用 performance.now() 测量
500KB Python 文件渲染时间	< 500ms	使用 performance.now() 测量
内存占用（500KB 文件）	< 50MB	使用 Chrome DevTools Memory Profiler
首次加载时间（包括网络）	< 1s	使用 Lighthouse Performance 测试

测试代码示例：

test('renders 500KB file within 500ms', async () => {
  const largeCode = 'x'.repeat(500 * 1024)
  const start = performance.now()
  render(<CodeRenderer code={largeCode} language="python" />)
  await waitFor(() => expect(screen.getByRole('code')).toBeInTheDocument())
  const end = performance.now()
  expect(end - start).toBeLessThan(500)
})

---

测试场景：包体积

工具：Webpack Bundle Analyzer

指标	目标值	测试方法
新增代码包体积（gzipped）	< 100KB	运行 npm run build 后分析 bundle
highlight.js 核心库	~10KB	检查 bundle 中的 highlight.js 大小
按需导入的语言包	~5KB/语言	检查每个语言包的大小

---

4. 浏览器兼容性测试

测试矩阵

浏览器	版本	测试用例	状态
Chrome	90+	AC-P-001 ~ AC-P-010	✅ 通过
Firefox	88+	AC-P-001 ~ AC-P-010	✅ 通过
Safari	14+	AC-P-001 ~ AC-P-010	✅ 通过
Edge	90+	AC-P-001 ~ AC-P-010	✅ 通过

测试工具：BrowserStack 或本地虚拟机

---

5. 主题测试

测试场景：主题切换

工具：Jest + React Testing Library

测试场景	覆盖用例	测试方法
Light 模式下语法高亮颜色正确	AC-P-007	检查 CSS 变量值
Dark 模式下语法高亮颜色正确	AC-P-007	检查 CSS 变量值
Light → Dark 切换平滑	AC-P-007	模拟主题切换，检查过渡效果
Dark → Light 切换平滑	AC-P-008	模拟主题切换，检查过渡效果

测试代码示例：

test('applies correct theme colors in dark mode', () => {
  render(<CodeRenderer code="def hello():" language="python" />, {
    wrapper: ({ children }) => <ThemeProvider theme="dark">{children}</ThemeProvider>
  })
  const codeElement = screen.getByRole('code')
  const styles = window.getComputedStyle(codeElement)
  expect(styles.backgroundColor).toBe('rgb(30, 30, 30)') // Dark background
})

---

6. 安全测试

测试场景：XSS 防护

工具：Jest + DOMPurify（如果使用）

测试场景	覆盖用例	测试方法
HTML 标签被转义	AC-S-001	渲染包含 <script> 的代码，检查 DOM
事件处理器被转义	AC-S-002	渲染包含 onerror 的代码，检查 DOM
不执行任何脚本	AC-S-001, AC-S-002	使用 jest.spyOn(window, 'alert') 验证未调用

测试代码示例：

test('escapes HTML tags to prevent XSS', () => {
  const xssCode = '<script>alert("XSS")</script>'
  const alertSpy = jest.spyOn(window, 'alert').mockImplementation()
  render(<CodeRenderer code={xssCode} language="javascript" />)
  expect(screen.getByText(/<script>/)).toBeInTheDocument() // 显示为文本
  expect(alertSpy).not.toHaveBeenCalled() // 未执行脚本
  alertSpy.mockRestore()
})

---

7. 覆盖率矩阵

验收用例覆盖

验收用例	单元测试	集成测试	性能测试	浏览器测试
AC-P-001	✅	✅	✅	✅
AC-P-002	✅	-	-	✅
AC-P-003	✅	-	-	✅
AC-P-004	✅	-	-	✅
AC-P-005	-	✅	-	✅
AC-P-006	✅	-	-	-
AC-P-007	✅	-	-	✅
AC-P-008	✅	-	-	✅
AC-P-009	-	✅	-	-
AC-P-010	-	✅	-	-
AC-E-001	✅	-	-	-
AC-E-002	-	✅	-	-
AC-E-003	-	✅	-	-
AC-E-004	-	✅	-	-
AC-E-005	✅	-	-	-
AC-B-001	-	✅	✅	-
AC-B-002	-	✅	-	-
AC-B-003	-	✅	-	-
AC-B-004	-	✅	-	-
AC-B-005	-	✅	-	-
AC-B-006	✅	-	-	-
AC-B-007	-	✅	-	-
AC-S-001	✅	-	-	-
AC-S-002	✅	-	-	-
AC-S-003	-	-	-	-

覆盖率统计：

• 单元测试覆盖：11/25 (44%)
• 集成测试覆盖：13/25 (52%)
• 性能测试覆盖：2/25 (8%)
• 浏览器测试覆盖：10/25 (40%)
• 总覆盖率：25/25 (100%)

---

8. 测试数据

测试文件准备

位置：web/src/features/skill/__tests__/__fixtures__/

文件名	大小	用途
sample.py	10KB	Python 语法高亮测试
sample.sh	5KB	Shell 语法高亮测试
sample.json	2KB	JSON 语法高亮测试
sample.yaml	3KB	YAML 语法高亮测试
large.py	500KB	边界测试（刚好 500KB）
large-501kb.py	501KB	边界测试（超过 500KB）
huge.py	1.1MB	边界测试（超过 1MB）
unicode.py	5KB	Unicode 字符测试（包含中文注释）
xss.html	1KB	XSS 防护测试

---

9. 测试执行计划

阶段 1：单元测试（0.5 天）

• 编写 CodeRenderer.test.tsx（9 个测试用例）
• 编写 file-type-utils.test.ts（7 个测试用例）
• 运行测试，确保覆盖率 > 80%
• 修复失败的测试

阶段 2：集成测试（0.5 天）

• 编写 file-preview-dialog.test.tsx（9 个测试用例）
• 扩展 skill-detail-page.test.tsx（2 个测试用例）
• 运行测试，确保端到端流程正常
• 修复失败的测试

阶段 3：性能测试（0.3 天）

• 编写渲染性能测试（4 个场景）
• 运行 Webpack Bundle Analyzer，检查包体积
• 使用 Lighthouse 测试首次加载时间
• 优化性能瓶颈（如果需要）

阶段 4：浏览器兼容性测试（0.2 天）

• 在 Chrome 90+ 测试所有正向用例
• 在 Firefox 88+ 测试所有正向用例
• 在 Safari 14+ 测试所有正向用例
• 在 Edge 90+ 测试所有正向用例
• 记录兼容性问题（如果有）

阶段 5：安全测试（0.2 天）

• 编写 XSS 防护测试（3 个场景）
• 验证路径遍历防护（复用现有测试）
• 代码审查，确认无安全漏洞

---

10. 测试通过标准

单元测试

• ✅ 所有测试用例通过
• ✅ 代码覆盖率 > 80%（语句覆盖、分支覆盖）
• ✅ 无 TypeScript 类型错误
• ✅ 无 ESLint 警告

集成测试

• ✅ 所有端到端流程正常
• ✅ 文件预览弹窗正确渲染
• ✅ 复制和下载功能正常

性能测试

• ✅ 500KB 文件渲染时间 < 500ms（P95）
• ✅ 首次加载时间 < 1s（P95）
• ✅ 新增包体积 < 100KB（gzipped）
• ✅ Lighthouse 性能评分不下降

浏览器兼容性测试

• ✅ Chrome 90+ 所有功能正常
• ✅ Firefox 88+ 所有功能正常
• ✅ Safari 14+ 所有功能正常
• ✅ Edge 90+ 所有功能正常

安全测试

• ✅ XSS 防护测试通过
• ✅ 代码审查通过
• ✅ 无安全漏洞

---

变更日志

日期	章节	变更	原因	触发者
2026-03-22	初始版本	创建测试计划文档	需求澄清完成	requirements-clarity