okooooooo/CloudSSH
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
CloudSSH/tests/README.md
T
TanXinandTanXin 1ce345d61b release: 发布 v2.0.0 Gem-Alpha 架构解耦与交互体验升级版本 (#123) 
## 本次版本更新内容（v2.0.0 — Gem-Alpha 重大里程碑版本）

本次发布为 CloudSSH **v2.0.0** 重大版本更新（代号
**Gem-Alpha**），包含后端与前端大文件深层次架构解耦瘦身、核心交互体验升级、SFTP
路径面包屑与三向排列表头、命令片段动态占位符与模糊搜索、多标签页内联重命名与上下文操作、以及 AI Agent 助手响应式窗口与移动端深度适配。

---

### 一、核心更新要点

#### 1. 架构深度解耦瘦身与代码健康治理
- **分享审计持久化管道解耦（`src/worker/share-audit-writer.ts`）**：抽离
`ShareAuditWriter`，统一封装审计记录排空、防抖刷新与排他写入锁；
- **RFC 4256 交互式键盘认证状态机解耦（`src/worker/ssh-interactive-auth.ts`）**：抽离
`KeyboardInteractiveAuthHandler`，独立管理多轮挑战 ID、超时看门狗及响应组包；
- **弱网断线保持与重连缓冲解耦（`src/worker/ssh-detached-buffer.ts`）**：抽离
`DetachedSessionBuffer`，独立负责 128KB 有界环形缓冲队列与重连补偿逻辑；
- **远端操作系统探测执行器解耦（`src/worker/os-detect.ts`）**：抽离
`detectAndPersistRemoteOS`，封装探测执行、解析与 UserDB 持久化；
- **SFTP 前端大文件解耦**：
- 抽离
`SFTPEditorCoordinator`（`frontend/src/sftp-editor-session.ts`）：独立管理编辑器挂载、编码探测、冲突检测与覆盖保存；
  - 抽离 `sftp-dialogs.ts`：管理文件/目录创建、重命名与删除交互对话框及路径合法性校验；
  - 抽离 `sftp-helpers.ts` 与 `sftp-transfer.ts`：封装面包屑解析、多维排序算法与异步传输状态模型；
- **代码健康规范治理**：全局显式补充 `parseInt` 10 进制基数，清理冗余构造函数与导入，收敛严格类型断言与类型告警。

#### 2. SFTP 与核心交互体验优化
- **SFTP
路径面包屑与可排列表头**：支持可点击直达的面包屑导航，保留文本框快速跳转与失焦自动恢复；表头支持文件名、大小、修改时间三向排序，目录智能置顶；
- **SFTP 工具栏新建文件**：点击工具栏「新建文件」按钮弹出命名弹窗，通过 0 字节探测上传后无缝调起在线编辑器；
- **命令片段模糊搜索与一键复制**：片段库新增实时搜索过滤，支持名称与命令模糊匹配；列表项增加一键复制到剪贴板按钮；
- **终端快捷键增强**：macOS 新增 `Cmd+F` 调出搜索栏，`Cmd+K` / `Ctrl+Shift+K`
清除终端屏幕缓冲区（`terminal.clear()`），并完好保留 Linux/Bash 默认的 `Ctrl+K` 剪切行尾逻辑。

#### 3. 易用性增强与多标签/Agent 体验
- **服务器卡片一键克隆**：提供一键克隆操作，完整复用主机、端口、用户名、跳板机关系与标签，安全清空敏感凭据，自动附加 `(Copy)`
后缀；
- **片段动态参数占位符**：支持 `{{variable}}` 语法，插入或执行前自动解析变量并弹出输入弹窗，支持默认值与输入记忆；
- **多标签页双击内联重命名与上下文菜单**：双击标签页标题直接进行内联编辑（`Enter` 保存，`Esc`
取消，空值/纯空白自动恢复原名）；右键标签弹出操作菜单（重命名、克隆会话、关闭其他、关闭当前）；
- **AI Agent 助手体验全面升级**：
- **动态 Clamp 响应式窗口**：参考 SFTP 采用 `min(clamp(420px, 40vw, 600px), 100%)`
弹性自适应宽度，顶栏对齐 `h-12` 规范并内联 `smart_toy` 助手图标；
- **桌面端严格限制在终端区域**：分栏高度严格限制在 `#terminal-area`
内部，绝不遮挡顶部状态栏右上方的双端延迟展示（`#term-info`）与连接状态；
- **移动端全屏覆盖与软键盘联动**：移动端保持全屏覆盖（`position: fixed; top:
48px;`）保证小屏下充裕的对话阅读空间；打开 Agent
时联动隐藏底部软键盘终端快捷工具栏，彻底解决输入框和发送按钮被遮挡问题；退出返回终端后自动恢复工具栏；
- **诊断 Prompt 预设与触控热区强化**：提供 4 组一键场景诊断 Prompt 胶囊（分析报错、系统负载、端口网络、Docker
状态），移动端全面优化 Prompt
胶囊（`32px`）、发送按钮（`40px`）、代码块操作（`30px`）和高危命令确认弹窗按钮触控热区；支持按 `Esc` 快速退出
Agent 返回终端。

---

### 二、提交列表

- `70042c2` feat: 提交 Gem-Alpha 版本（SFTP增强/片段占位符/标签菜单/大文件解耦瘦身） (#120)
- `78dca39` feat: Gem-Alpha 增量迭代（AI Agent 窗口响应式与移动端优化 / 标签重命名缺陷修复 /
文档同步） (#122)
- `0b04480` fix: 恢复移动端 AI Agent 全屏覆盖布局以保障小屏交互空间
- `0c19ac2` fix: 移动端打开 AI Agent 时自动隐藏底部终端快捷键工具栏
- `50171c7` release: 发布 v2.0.0 Gem-Alpha 架构解耦与交互体验升级版本

---

### 三、关联 Issue / PR

- 关联 PR：#120, #122

---

### 四、验证结果

- ✅ `pnpm run typecheck`：通过（Worker + Frontend 0 错误）
- ✅ `pnpm test`：通过（66 个测试文件，755 项测试全数通过）
- ✅ `pnpm run build:frontend`：通过（单 bundle 确定性构建并内联至
`src/worker/html.ts`）
- ✅ `pnpm run test:e2e`：通过（75 项 Playwright 端到端及 axe 无障碍测试全部通过，1
项按平台条件跳过）
- ✅ `pnpm run verify`：完整本地质量门禁验证全绿通过

---------

Co-authored-by: TanXin <tanxin@example.com>
2026-09-04 14:14:08 +08:00

6.8 KiB
Raw Permalink Blame History

CloudSSH 测试套件

本目录包含 CloudSSH 的单元测试、协议集成测试、构建回归和浏览器 E2E。测试框架以 Vitest 和 Playwright 为主。

目录结构

tests/
├── build/                         # 生产构建、可复现性和原生弹窗回归
├── e2e/                           # Chromium 浏览器交互与 axe 无障碍检查
├── ssh/                           # SSH 算法、认证、加密、KEX、Packet 与测试密钥夹具
├── worker/                        # Worker 路由、安全、DNS、UserDB 与标签测试
├── agent-code-actions.test.ts # Agent 代码块复制/填入规则
├── agent-terminal-selection.test.ts # 终端选区附件和非授权安全边界
├── api-errors.test.ts          # API 错误信息边界与状态码
├── auth-challenge-dialog.test.ts # RFC 4256 认证挑战对话框交互
├── clipboard.test.ts              # Clipboard API 与旧版复制回退
├── editor-content.test.ts         # 在线编辑内容解码、BOM/换行符与嗅探
├── frontend-ux.test.ts            # 前端关键交互源码回归（标签栏/状态栏渲染等）
├── host-display.test.ts           # IPv4/IPv6 掩码与完整地址复制
├── i18n.test.ts                   # 中英文词条和语言解析
├── known-hosts.test.ts            # 已知主机指纹 TOFU 信任与变更流程
├── mobile-input.test.ts           # iOS IME diff 与一次性修饰键帮助函数
├── sftp-dialogs.test.ts           # SFTP 新建/重命名/删除弹窗与名称校验
├── sftp-helpers.test.ts           # SFTP 面包屑解析、多维排序与格式化
├── sftp-panel.test.ts             # SFTP 面包屑与路径状态回归
├── sftp-selection.test.ts         # SFTP 单选、多选、连选和全选模型
├── sftp-transfer.test.ts          # SFTP 传输控制器与异步原语
├── share-session.test.ts          # 分享会话确认/领取幂等与页面状态
├── snippet-local-store.test.ts    # 匿名命令片段 localStorage 存储与限额
├── snippet-manager.test.ts        # 命令片段搜索过滤与一键复制交互
├── snippet-schema.test.ts         # 片段名称/命令/数量校验与规范化
├── snippet-variables.test.ts      # 命令片段 {{var}} 参数占位符提取与替换
├── terminal-shortcuts.test.ts     # 终端快捷键（Cmd+F 搜索、Cmd+K 清屏）
├── terminal-status.test.ts        # SSH 状态事件翻译
├── terminal-text.test.ts          # 终端文本处理
├── theme.test.ts                  # 内置/自定义主题
├── types.test.ts                  # 共享类型和终端尺寸边界
└── README.md

tests/ssh/fixtures/ 中的私钥只用于公开的协议测试，不得用于生产服务器或真实账号。

运行命令

# 运行全部 Vitest 单元与集成测试
pnpm test

# 运行指定测试文件
pnpm test tests/ssh/auth.test.ts

# 生成覆盖率报告（输出到 coverage/）
pnpm run test:coverage

# 监听模式
pnpm test --watch

# 安装并运行 Chromium E2E 与 axe 无障碍检查
pnpm exec playwright install chromium
pnpm run test:e2e

# 类型检查、测试、可复现构建和 E2E 完整门禁
pnpm run verify

测试类型检查：pnpm run typecheck 的 worker 阶段会依次执行 tsc --noEmit（src）、tsc -p tests/tsconfig.worker.json（tests/worker|ssh|build， workers-types 环境）与 tsc -p tests/tsconfig.frontend.json（tests 根目录 *.test.ts + e2e， DOM 环境）。两个测试配置分开的原因：@cloudflare/workers-types 声明的基础 DOM 接口 （如 Element.append）与 DOM lib 合并冲突，不能在同一项目里同时加载。

当前覆盖范围

SSH 协议

  • 算法协商列表与兼容性
  • 密码认证
  • Ed25519、ECDSA P-256/P-384/P-521、RSA-SHA2 私钥认证
  • OpenSSH 私钥解析、DER/SSH 签名转换
  • AES-GCM/CTR、HMAC、Packet、KEX 辅助和二进制工具

Worker 与安全边界

  • Turnstile 验证 token 的结构、过期时间和 HMAC
  • Origin 检查、端口范围、连接令牌和错误信息边界
  • IPv4/IPv6 保留地址、DoH 解析与 DNS rebinding 防护
  • Agent 危险命令拦截、确认规则和 SSRF URL 校验
  • 主机密钥信任：首见指纹确认、更换指纹阻断与路由作用域隔离
  • 键盘交互认证、OS 检测、跳板链、SFTP 上传冲突、分享会话策略
  • UserDB 服务器标签/片段迁移、规范化、序列化、更新与隔离

前端与构建

  • 服务器搜索、标签筛选、配置一键克隆（Duplicate Server）和响应式分页（桌面 9 / 平板 6 / 移动 3）
  • 终端多标签：双击内联重命名（空值还原）、右键上下文菜单（重命名/克隆会话/关闭其他/关闭）与 document click 防泄漏
  • 终端快捷键适配：macOS Cmd+F 搜索、Cmd+K / Ctrl+Shift+K 清屏且不干扰 Shell 原生 Ctrl+K
  • 命令片段库：实时模糊搜索、一键复制到剪贴板与 {{var}} 动态参数占位符弹窗录入
  • SFTP 生产力：路径面包屑分级导航、表头多维排序（文件名/大小/时间）、新建 0 字节文件与 CodeMirror 在线编辑联动
  • SFTP 单选、Cmd/Ctrl 多选、Shift 连选和全选
  • Agent 终端选区附件、问题组合、快捷诊断 Prompt 气泡（Chips）和非授权安全边界
  • 终端选区自动复制、指针取消和旧版复制回退
  • i18n、Theme V3 主题（背景/效果/版式钳制、对比度与 schema）、终端状态/文本、已知主机与片段本地存储
  • 构建可复现性、xterm 生产构建兼容和原生弹窗禁用

浏览器 E2E

  • 匿名连接表单 axe 检查
  • 服务器弹窗的基本对话框语义、初始焦点和 Escape 关闭
  • 服务器标签筛选、分页与配置快速克隆
  • 多标签操作：双击内联重命名、空值与失焦恢复、右键菜单项与外部点击关闭
  • Agent 终端选区附件与快捷诊断 Prompt 气泡点击填入
  • 终端选区复制与焦点恢复
  • 认证挑战对话框、iOS 输入法、移动端后台连接恢复与分享会话领取
  • SFTP 覆盖确认、路径面包屑、表头排序、新建文件、主题样式与 UI 回归

当前限制

  • Playwright 的完整界面与无障碍回归主要运行 Chromium；认证挑战、iOS 输入法和移动端后台连接恢复另在 WebKit 设备项目中执行。Firefox 尚未纳入当前质量门禁。
  • 浏览器 E2E 主要通过 mock API 验证前端行为，尚未连接真实 OpenSSH/Dropbear 和 SFTP 服务。
  • SSHSessionDO、SSH 会话状态机、SFTP 数据流和 AgentCore 等运行态模块的覆盖率仍偏低。
  • 新增协议状态、WebSocket 消息或安全边界时，应优先补充运行时错误、取消、超时和畸形输入测试，而不仅验证成功路径。
Reference in new issue View Git Blame Copy Permalink