Skip to content

Commit d26cd0f

Browse files
Yuki-NagoriYuki-Nagori
authored
[1007] 重命名启动页相关代码文件，补充测试 (#3360)
1 parent 50d0221 commit d26cd0f

10 files changed

Lines changed: 416 additions & 99 deletions

File tree

‎TeXmacs/tests/1002_1.scm‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2+
;;
3+
;; MODULE : 1002_1.scm
4+
;; DESCRIPTION : Integration tests for startup tab recent documents API
5+
;; COPYRIGHT : (C) 2026 Yuki Lu
6+
;;
7+
;; This software falls under the GNU general public license version 3 or later.
8+
;; It comes WITHOUT ANY WARRANTY WHATSOEVER. For details, see the file LICENSE
9+
;; in the root directory or <http://www.gnu.org/licenses/gpl-3.0.html>.
10+
;;
11+
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
12+
13+
(import (liii check))
14+
15+
(check-set-mode! 'report-failed)
16+
17+
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
18+
;; Helpers
19+
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
20+
21+
(define (save-recent-docs)
22+
(startup-tab-get-recent-docs))
23+
24+
(define (restore-recent-docs docs)
25+
(startup-tab-clear-all-recent)
26+
(for-each startup-tab-add-recent-doc docs))
27+
28+
;; 比较路径时忽略平台差异（url->system 可能在 Windows 上转换斜杠）
29+
(define (path-has-filename? path name)
30+
(let ((len-path (string-length path))
31+
(len-name (string-length name)))
32+
(and (>= len-path len-name)
33+
(let ((start (- len-path len-name)))
34+
(and (or (== start 0)
35+
(let ((ch (string-ref path (- start 1))))
36+
(or (== ch #\/) (== ch #\\))))
37+
(== (substring path start len-path) name))))))
38+
39+
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
40+
;; Tests
41+
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
42+
43+
(define (test-get-recent-docs-returns-list)
44+
(let ((docs (startup-tab-get-recent-docs)))
45+
(check (list? docs) => #t)))
46+
47+
(define (test-add-recent-doc)
48+
(let ((original (save-recent-docs)))
49+
(startup-tab-clear-all-recent)
50+
(check (length (startup-tab-get-recent-docs)) => 0)
51+
52+
;; 使用简单文件名避免 url->system 的平台差异
53+
(startup-tab-add-recent-doc "test-doc-1.tmu")
54+
(let ((docs (startup-tab-get-recent-docs)))
55+
(check (length docs) => 1)
56+
(check (path-has-filename? (car docs) "test-doc-1.tmu") => #t))
57+
58+
;; 添加第二个文档
59+
(startup-tab-add-recent-doc "test-doc-2.tmu")
60+
(let ((docs (startup-tab-get-recent-docs)))
61+
(check (length docs) => 2)
62+
;; 最近添加的应在最前面
63+
(check (path-has-filename? (car docs) "test-doc-2.tmu") => #t))
64+
65+
;; 重新添加已有文档应将其移到最前面
66+
(startup-tab-add-recent-doc "test-doc-1.tmu")
67+
(let ((docs (startup-tab-get-recent-docs)))
68+
(check (length docs) => 2)
69+
(check (path-has-filename? (car docs) "test-doc-1.tmu") => #t))
70+
71+
(restore-recent-docs original)))
72+
73+
(define (test-clear-recent-doc)
74+
(let ((original (save-recent-docs)))
75+
(startup-tab-clear-all-recent)
76+
(startup-tab-add-recent-doc "test-doc-a.tmu")
77+
(startup-tab-add-recent-doc "test-doc-b.tmu")
78+
(startup-tab-add-recent-doc "test-doc-c.tmu")
79+
80+
(startup-tab-clear-recent-doc "test-doc-b.tmu")
81+
(let ((docs (startup-tab-get-recent-docs)))
82+
(check (length docs) => 2)
83+
(check (path-has-filename? (car docs) "test-doc-c.tmu") => #t)
84+
(check (path-has-filename? (cadr docs) "test-doc-a.tmu") => #t))
85+
86+
;; 清除不存在的文档不应崩溃
87+
(startup-tab-clear-recent-doc "non-existent.tmu")
88+
(check (length (startup-tab-get-recent-docs)) => 2)
89+
90+
(restore-recent-docs original)))
91+
92+
(define (test-clear-all-recent)
93+
(let ((original (save-recent-docs)))
94+
(startup-tab-add-recent-doc "test-doc-x.tmu")
95+
(startup-tab-clear-all-recent)
96+
(check (length (startup-tab-get-recent-docs)) => 0)
97+
(restore-recent-docs original)))
98+
99+
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
100+
;; Entry point
101+
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
102+
103+
(tm-define (test_1002_1)
104+
(test-get-recent-docs-returns-list)
105+
(test-add-recent-doc)
106+
(test-clear-recent-doc)
107+
(test-clear-all-recent)
108+
(check-report))

‎devel/1007.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# [1007] 统一启动页 Qt 控件命名规范为 QTM 前缀
2+
3+
## 1 相关文档
4+
- [dddd.md](dddd.md) - 任务文档模板
5+
- [1001.md](1001.md) - 启动页保留行为
6+
- [1002.md](1002.md) - 将打开文件功能从侧边栏迁移到主页
7+
- [216_6.md](216_6.md) - 启动页 File 页视觉与 Recent 读写链路完善
8+
9+
## 2 任务相关的代码文件
10+
- `src/Plugins/Qt/QTMHomePage.hpp`
11+
- `src/Plugins/Qt/QTMHomePage.cpp`
12+
- `src/Plugins/Qt/QTMTemplatePage.hpp`
13+
- `src/Plugins/Qt/QTMTemplatePage.cpp`
14+
- `src/Plugins/Qt/QTMStartupTabWidget.hpp`
15+
- `src/Plugins/Qt/QTMStartupTabWidget.cpp`
16+
- `src/Plugins/Qt/qt_tm_widget.cpp`
17+
- `TeXmacs/tests/1002_1.scm`
18+
- `tests/Mogan/Startup/startup_tab_widget_test.cpp`
19+
20+
## 3 如何测试
21+
22+
### 3.1 确定性测试（单元测试 / 集成测试）
23+
24+
C++ Qt Test：
25+
```bash
26+
./bin/test_only startup_tab_widget_test
27+
```
28+
29+
Scheme 集成测试：
30+
```bash
31+
./bin/test_only 1002_1
32+
```
33+
34+
### 3.2 非确定性测试（文档验证）
35+
```bash
36+
xmake build stem
37+
xmake run stem
38+
```
39+
40+
1. 启动应用，确认启动页侧边栏显示 "Home" 和 "Template"
41+
2. 点击 "Template" 切换页面，确认 Template Center 正常加载
42+
3. 点击 "Home" 返回主页，确认样式卡片和最近文档区域正常显示
43+
4. 验证最近文档列表的增删行为正常
44+
45+
## 4 如何提交
46+
47+
提交前执行以下最少步骤：
48+
49+
```bash
50+
# 确认编译通过
51+
xmake build stem
52+
53+
# 运行 C++ 测试
54+
./bin/test_only startup_tab_widget_test
55+
56+
# 运行 Scheme 集成测试
57+
./bin/test_only 1002_1
58+
```
59+
60+
## 5 What
61+
62+
统一启动页三个核心 Qt 控件的命名规范，使其与项目惯例（`QTM*` 前缀）保持一致，并补充对应集成测试。
63+
64+
1. **文件与类重命名**
65+
- `qt_home_page.hpp/cpp` → `QTMHomePage.hpp/cpp`，类名 `QtHomePage` → `QTMHomePage`
66+
- `qt_template_page.hpp/cpp` → `QTMTemplatePage.hpp/cpp`，类名 `QTTemplatePage` → `QTMTemplatePage`
67+
- `qt_startup_tab_widget.hpp/cpp` → `QTMStartupTabWidget.hpp/cpp`，类名 `QTStartupTabWidget` → `QTMStartupTabWidget`
68+
- 更新 `qt_tm_widget.cpp` 中的 `#include` 与 `new` 表达式
69+
70+
2. **头文件宏调整**
71+
- 将 `QTM_HOME_PAGE_HPP`、`QTMTEMPLATEPAGE_HPP` 等调整为 `QTMHOMEPAGE_HPP`、`QTMTEMPLATEPAGE_HPP`，与项目现有 `QTM*.hpp` 文件风格一致
72+
73+
3. **C++ 集成测试**
74+
- 新增 `tests/Mogan/Startup/startup_tab_widget_test.cpp`
75+
- 测试 `QTMTemplatePage` 的构造/初始化、`TemplateManager` 信号响应（`templatesLoaded` / `categoriesLoaded`）、resize 稳定性
76+
- 使用 `QSignalSpy` + `findChild` 做黑盒验证，不依赖真实网络请求
77+
78+
4. **Scheme 集成测试**
79+
- 新增 `TeXmacs/tests/1002_1.scm`
80+
- 测试 `startup-tab-get-recent-docs`、`startup-tab-add-recent-doc`、`startup-tab-clear-recent-doc`、`startup-tab-clear-all-recent` 四个 API 的数据一致性
81+
- 使用 `save-recent-docs` / `restore-recent-docs` 做测试隔离，避免污染全局 recent 状态
82+
83+
## 6 Why
84+
85+
项目自定义 Qt 控件命名存在两种风格：`qt_*.hpp/cpp`（多为 TeXmacs widget 实现层）和 `QTM*.hpp/cpp`（纯 Qt 控件层）。启动页的三个控件属于纯 Qt 控件，但前期使用了不一致的前缀（`QtHomePage`、`QTTemplatePage`、`QTStartupTabWidget`），与仓库内 `QTMWidget`、`QTMWindow` 等现有惯例不统一。重命名后，代码结构更清晰，也便于后续维护者快速识别控件层级。
86+
87+
## 7 How
88+
89+
### 7.1 重命名策略
90+
91+
使用 `git mv` 进行文件重命名，保留文件历史。然后批量替换：
92+
- 类名（如 `QTStartupTabWidget` → `QTMStartupTabWidget`）
93+
- 文件名引用（如 `#include "qt_home_page.hpp"` → `#include "QTMHomePage.hpp"`）
94+
- 头文件包含防护宏
95+
- 成员变量类型声明（如 `QtHomePage* homePage_` → `QTMHomePage* homePage_`）
96+
97+
### 7.2 C++ 测试策略
98+
99+
`QTMStartupTabWidget` 和 `QTMHomePage` 在构造函数中会调用 `eval_scheme`，需要完整的 S7 Scheme 解释器初始化，在 C++ 单测环境中直接实例化会 crash。因此 C++ 测试聚焦在**不依赖 Scheme** 的 `QTMTemplatePage` 上：
100+
- 构造 + `initialize()` 不 crash
101+
- `TemplateManager::templatesLoaded()` 手动发射后，网格刷新为 "No templates available."
102+
- `TemplateManager::categoriesLoaded()` 手动发射后，分类栏保持可访问
103+
- `resizeEvent` 不 crash
104+
105+
### 7.3 Scheme 测试策略
106+
107+
`startup-tab-get-recent-docs` 内部调用了 `url->system`，在 Windows 上会转换路径格式（如 `/tmp/test.tmu` → `tmp\test.tmu`）。为避免平台差异导致断言失败，测试中使用**无目录分隔符的简单文件名**（如 `test-doc-1.tmu`），并编写 `path-has-filename?` 辅助函数做宽松匹配。

0 commit comments

Comments
 (0)