[AT] deepin-reader AT-SPI 测试套件

tests/at/at-spi-implementation-checklist.md

@@ -0,0 +1,110 @@
+# AT-SPI Implementation Checklist — deepin-reader
+
+## 当前 AT-SPI 覆盖统计
+
+- 源码 UI 类总数: 173（扫描发现）
+- 有 setAccessibleName 的 UI 类: 8（含辅助方法中的调用）
+- 无 AT-SPI 名称的 UI 类: 165
+- 覆盖率: 4.6%
+
+## 命名规则建议
+
+```cpp
+// 统一命名前缀约定
+// 主窗口: <Widget>_<Function>_<Index>
+// 示例:
+// MainWindow_TitleMenu   — 主菜单按钮
+// Central_DocTab         — 文档标签页
+// SheetSidebar_Btn_01    — 侧边栏第一个按钮
+// FindWidget_SearchInput — 查找输入框
+```
+
+## 缺口明细
+
+### 必做（无任何锚点）
+
+| # | 目标名称 | 当前 fallback | 文件位置 | 修改模板 |
+|---|---------|--------------|---------|---------|
+| 1 | `TitleMenu.TitleMenu` | 无 | `reader/uiframe/TitleMenu.cpp:43` | 在构造函数中加 `setAccessibleName("TitleMenu_MenuBtn")` |
+| 2 | `Central.Central` | 无 | `reader/uiframe/Central.cpp` 构造函数 | 在构造函数中加 `setAccessibleName("Central_MainArea")` |
+| 3 | `CentralDocPage.CentralDocPage` | 无 | `reader/uiframe/CentralDocPage.cpp` 构造函数 | 在构造函数中加 `setAccessibleName("CentralDocPage_DocArea")` |
+| 4 | `DocSheet.DocSheet` | 无 | `reader/uiframe/DocSheet.cpp` 构造函数 | 在构造函数中加 `setAccessibleName("DocSheet_Container")` |
+| 5 | `DocTabBar.DocTabBar` | 无 | `reader/uiframe/DocTabBar.cpp` 构造函数 | 在构造函数中加 `setAccessibleName("DocTabBar_Tabs")` |
+| 6 | `FindWidget.FindWidget` | 无 | `reader/widgets/FindWidget.cpp:120` | 在 initWidget 中加 `m_findEdit->setAccessibleName("FindWidget_SearchInput")` |
+| 7 | `SheetSidebar.SheetSidebar` | 无 | `reader/sidebar/SheetSidebar.cpp:363` | 在 createBtn 中加 `button->setAccessibleName("SheetSidebar_" + btn->text())` |
+| 8 | `ScaleWidget.ScaleWidget` | 无 | `reader/widgets/ScaleWidget.cpp:42-79` | 对各子控件加 setAccessibleName |
+
+### 建议（fallback 易碎）
+
+| # | 目标名称 | 当前 fallback | 风险 | 修改模板 |
+|---|---------|--------------|------|---------|
+| 9 | `PagingWidget` 子控件 | objectName（中文不翻译） | 翻译后 objectName 可能变化 | 对 Edit_Page/Edit_Page_P 加 `setAccessibleName("Paging_CurrentPage")` |
+| 10 | `EncryptionPage` 子控件 | objectName | 同上 | 对 ensureBtn/passwdEdit 加 `setAccessibleName("Encrypt_ConfirmBtn")` |
+| 11 | `HandleMenu` 子控件 | objectName | 同上 | 对 defaultshape/handleshape 加 setAccessibleName |
+
+### 无需修改（已有注册/显式名）
+
+| 控件 | 名称来源 | 当前名称 |
+|------|---------|---------|
+| MainWindow | SET_FORM_ACCESSIBLE | MainWindow |
+| Central | SET_FORM_ACCESSIBLE | Central |
+| CentralDocPage | SET_FORM_ACCESSIBLE | CentralDocPage |
+| CentralNavPage | SET_FORM_ACCESSIBLE | CentralNavPage |
+| DocSheet | SET_FORM_ACCESSIBLE | DocSheet |
+| DocTabBar | SET_FORM_ACCESSIBLE | DocTabBar |
+| TitleWidget | SET_FORM_ACCESSIBLE | TitleWidget |
+| SheetSidebar | SET_FORM_ACCESSIBLE | SheetSidebar |
+| SheetBrowser | SET_FORM_ACCESSIBLE | SheetBrowser |
+| ThumbnailWidget | SET_FORM_ACCESSIBLE | ThumbnailWidget |
+| CatalogWidget | SET_FORM_ACCESSIBLE | CatalogWidget |
+| BookMarkWidget | SET_FORM_ACCESSIBLE | BookMarkWidget |
+| NotesWidget | SET_FORM_ACCESSIBLE | NotesWidget |
+| SearchResWidget | SET_FORM_ACCESSIBLE | SearchResWidget |
+| Menu_Browser | setAccessibleName | Menu_Browser |
+| Menu_BookMark | setAccessibleName | Menu_BookMark |
+| Menu_Note | setAccessibleName | Menu_Note |
+
+## 实施优先级
+
+### P0（影响核心自动化能力）
+1. TitleMenu 菜单按钮 → get AT-SPI anchor for 主菜单操作
+2. FindWidget 查找输入框 → get AT-SPI anchor for 搜索功能
+3. 文档区域交互元素（BrowserPage/SheetBrowser 子控件）
+
+### P1（影响功能覆盖）
+4. ScaleWidget 缩放控件
+5. SlidePlayWidget 幻灯片控件
+6. SheetSidebar 侧边栏按钮
+
+### P2（提升稳定性）
+7. PagingWidget 翻页控件子元素
+8. EncryptionPage 加密页面
+9. HandleMenu 工具菜单
+
+## 验证断言
+
+实施后，以下 AT 用例应可通过元素名称定位：
+
+```yaml
+# 主菜单按钮
+- action: element_action
+  selector:
+    name: "TitleMenu_MenuBtn"
+  do: click
+
+# 查找输入框  
+- action: element_action
+  selector:
+    name: "FindWidget_SearchInput"
+    role: "text"
+  do: click
+- action: keyboard_type
+  text: "test"
+```
+
+## 动态风险说明
+
+- `_N` 去重：DTK 动态创建的同名控件会在 AT-SPI 树中自动加 `_1`/`_2` 后缀
+- 弹窗控件：DDialog/DFileDialog 仅在打开时出现在 AT-SPI 树中
+- 菜单项：纯瞬态元素，只能用 `dtk_main_menu`/`dtk_context_menu`，不可用 `element_action`
+- [INFERENCE] 部分控件需运行时验证实际 AT-SPI 名称

tests/at/at-tree-annotated.yaml

@@ -0,0 +1,142 @@
+version: '1.0'
+tree:
+- id: ''
+  role: panel
+  name: SideBarImageListView
+  object_name: ''
+  accessible_id: ''
+  classification: container
+  comment: "GUI位置: 左侧侧边栏-图像列表视图 | 功能: 显示缩略图/书签/注释/目录等侧边栏内容的图像列表容器"
+  annotation_status: draft
+  children:
+  - id: ''
+    role: panel
+    name: sideBarImageListView
+    object_name: sideBarImageListView
+    accessible_id: ''
+    classification: container
+    comment: "GUI位置: 左侧侧边栏-图像列表视图内 | 功能: 侧边栏内部列表视图，显示缩略图/书签列表项"
+    annotation_status: draft
+  - id: ''
+    role: panel
+    name: sideBarImageListViewViewport
+    object_name: sideBarImageListViewViewport
+    accessible_id: ''
+    classification: container
+    comment: "GUI位置: 左侧侧边栏-图像列表视图视口 | 功能: 侧边栏列表视口的视图窗口"
+    annotation_status: draft
+- id: ''
+  role: panel
+  name: BrowserMenu
+  object_name: BrowserMenu
+  accessible_id: ''
+  classification: container
+  comment: "GUI位置: 文档阅读区域 | 功能: 浏览器右键菜单容器，包含复制/搜索等菜单项"
+  annotation_status: draft
+- id: ''
+  role: panel
+  name: EncryptionPage
+  object_name: ''
+  accessible_id: ''
+  classification: container
+  comment: "GUI位置: 加密PDF文档打开时的密码输入页面 | 功能: 加密文档密码验证界面"
+  annotation_status: draft
+  children:
+  - id: ''
+    role: panel
+    name: ensureBtn
+    object_name: ensureBtn
+    accessible_id: ''
+    classification: container
+    comment: "GUI位置: 加密页面-确认按钮 | 功能: 确认密码输入"
+    annotation_status: draft
+  - id: ''
+    role: panel
+    name: passwdEdit
+    object_name: passwdEdit
+    accessible_id: ''
+    classification: container
+    comment: "GUI位置: 加密页面-密码输入框 | 功能: 输入PDF文档密码"
+    annotation_status: draft
+- id: ''
+  role: panel
+  name: HandleMenu
+  object_name: ''
+  accessible_id: ''
+  classification: container
+  comment: "GUI位置: 工具栏-工具切换菜单 | 功能: 手形工具/选择文本工具切换菜单"
+  annotation_status: draft
+  children:
+  - id: ''
+    role: panel
+    name: defaultshape
+    object_name: defaultshape
+    accessible_id: ''
+    classification: container
+    comment: "GUI位置: 工具栏-工具菜单-默认选项 | 功能: 手形工具（Hand Tool）模式"
+    annotation_status: draft
+  - id: ''
+    role: panel
+    name: handleshape
+    object_name: handleshape
+    accessible_id: ''
+    classification: container
+    comment: "GUI位置: 工具栏-工具菜单-选择文本选项 | 功能: 选择文本（Select Text）模式"
+    annotation_status: draft
+- id: ''
+  role: panel
+  name: PagingWidget
+  object_name: ''
+  accessible_id: ''
+  classification: container
+  comment: "GUI位置: 底部工具栏-翻页控件 | 功能: 文档翻页导航（页码输入/上下翻页）"
+  annotation_status: draft
+  children:
+  - id: ''
+    role: panel
+    name: Edit_Page
+    object_name: Edit_Page
+    accessible_id: ''
+    classification: container
+    comment: "GUI位置: 底部翻页控件-当前页码输入框 | 功能: 显示和输入当前页码"
+    annotation_status: draft
+  - id: ''
+    role: panel
+    name: Edit_Page_P
+    object_name: Edit_Page_P
+    accessible_id: ''
+    classification: container
+    comment: "GUI位置: 底部翻页控件-总页码显示 | 功能: 显示文档总页数"
+    annotation_status: draft
+  - id: ''
+    role: panel
+    name: thumbnailNextBtn
+    object_name: thumbnailNextBtn
+    accessible_id: ''
+    classification: container
+    comment: "GUI位置: 底部翻页控件-下一页按钮 | 功能: 翻到下一页"
+    annotation_status: draft
+  - id: ''
+    role: panel
+    name: thumbnailPreBtn
+    object_name: thumbnailPreBtn
+    accessible_id: ''
+    classification: container
+    comment: "GUI位置: 底部翻页控件-上一页按钮 | 功能: 翻到上一页"
+    annotation_status: draft
+- id: ''
+  role: panel
+  name: TextEditShadowWidget
+  object_name: TextEditShadowWidget
+  accessible_id: ''
+  classification: container
+  comment: "GUI位置: 注释编辑区域 | 功能: 文本编辑阴影控件，用于注释文本编辑框的阴影效果"
+  annotation_status: draft
+- id: ''
+  role: panel
+  name: TransparentTextEdit
+  object_name: TransparentTextEdit
+  accessible_id: ''
+  classification: container
+  comment: "GUI位置: 注释编辑区域 | 功能: 透明文本编辑框，用于文档注释编辑"
+  annotation_status: draft