拒绝 JSDOM 假绿灯！键盘小鹿基于 Electron 特权协议与真实 WebGL 的 1979 项自动化与多分辨率视觉回归

一、 为什么传统的 JSDOM 单元测试是“自欺欺人的假绿灯”？

绝大多数前端团队习惯在 vitest 或 jest 中依赖 JSDOM 进行组件测试。然而在复杂的打字训练引擎、2D Canvas 游戏与桌面客户端领域，JSDOM 暴露出了三大不可逾越的物理硬伤：

• JSDOMFakes -> KeyDeerRealQAPipeline
• 1. 视口溢出检测（Overflow Detection）在 JSDOM 中完全失效： 在 1366×768 的老款笔记本屏幕上，如果某个打字提示按钮被挤到了屏幕最底部外侧，用户根本点不到。而在 JSDOM 环境中，所有元素都没有真实的物理坐标和换行几何计算，overflow: hidden 截断在单测里永远显示“渲染正常”，导致严重的布局 Bug 被堂而皇之推向生产环境。
• 2. Canvas 与 WebGL 场景沦为测试盲区： 在《汉字飞机》、《王国对决》等 Phaser 2D 打字游戏中，游戏逻辑涉及大量纹理图集加载、着色器编译与粒子渲染。JSDOM 没有真实的 GPU 上下文，现有的测试方案往往只是对 canvas.getContext('2d') 注入一个空对象（Mock），游戏即便底层已经抛出着色器语法错误或纹理丢失崩溃，JSDOM 依然高高兴兴地给你亮出“绿灯（Pass）”。

二、 键盘小鹿基于真实 Electron 特权协议的 QA 架构拓扑

为彻底消灭“假绿灯”，键盘小鹿搭建了基于真实无头 Electron 的端到端自动化测试流水线：

• QAProtocol -> >Runner: 返回 RGBA 像素矩阵与 DOM 溢出扫描报告

三、 核心工程实现细节

// scripts/qa-responsive-layout.mjs 视口溢出自动扫描器核心实现
import { BrowserWindow, app } from 'electron'

const RESOLUTION_PRESETS = [
  { name: 'XGA', width: 1024, height: 768 },
  { name: 'Old-Laptop', width: 1366, height: 768 },
  { name: 'Standard-HD', width: 1600, height: 900 },
  { name: 'Full-HD', width: 1920, height: 1080 },
  { name: '2K-Monitor', width: 2560, height: 1440 }
]

export async function sweepAndVerifyLayoutOverflow(mainWindow) {
  console.log('[QA Runner] 启动全分辨率视口溢出扫描门禁...')

  for (const preset of RESOLUTION_PRESETS) {
    // 1. 真实改变 Electron 原生窗口尺寸
    mainWindow.setContentSize(preset.width, preset.height)
    await new Promise(r => setTimeout(r, 200)) // 等待重排重绘稳定

    // 2. 在真实 Chromium 内核执行物理几何检测
    const overflowReport = await mainWindow.webContents.executeJavaScript(`
      (() => {
        const docWidth = document.documentElement.clientWidth;
        const scrollWidth = document.documentElement.scrollWidth;
        const bodyScroll = document.body.scrollWidth;
        
        // 扫描所有可见元素，排查是否有超出视口的节点
        const overflowingElements = [];
        const allElements = document.querySelectorAll('*');
        for (const el of allElements) {
          const rect = el.getBoundingClientRect();
          if (rect.right > docWidth + 2 || rect.left < -2) {
            // 忽略特定的离屏隐藏元素
            if (el.offsetParent !== null && window.getComputedStyle(el).overflow !== 'hidden') {
              overflowingElements.push({
                tag: el.tagName,
                className: el.className,
                right: rect.right,
                viewportWidth: docWidth
              });
            }
          }
        }

        return {
          hasHorizontalScroll: scrollWidth > docWidth || bodyScroll > docWidth,
          overflowCount: overflowingElements.length,
          violators: overflowingElements.slice(0, 3)
        };
      })()
    `)

    if (overflowReport.hasHorizontalScroll || overflowReport.overflowCount > 0) {
      throw new Error(`[QA Alert] 在分辨率 ${preset.name} (${preset.width}x${preset.height}) 下发生视口溢出！详情: ${JSON.stringify(overflowReport.violators)}`)
    }

    console.log(`[QA Pass] 分辨率 ${preset.name} (${preset.width}x${preset.height}) 布局验证通过，零溢出。`)
  }
}

• 1. 特权测试协议与视口溢出自动化探测（qa-responsive-layout.mjs）： 测试脚本会自动遍历 8 种常见的物理分辨率（从 1024×768 到 4K 3840×2160），在真实渲染引擎中检测是否有任何元素溢出视口：
• 2. Phaser 2D 游戏真实 WebGL 像素断言（qa-phaser-games.mjs）： 测试脚本不依赖任何虚假 Mock，而是直接注入按键驱动游戏进行，并调用底层的 readPixels 验证画布上是否真实绘制了被击中的爆炸粒子：

四、 工业级排查复盘：CI Linux 无头服务器没有 GPU 导致 WebGL 崩溃

在将这套自动化测试迁移到 GitHub Actions / Linux CI 持续集成服务器时，我们遭遇了典型的基础设施死锁：

配合虚拟显示服务器 xvfb-run -a，使 Linux 云服务器完全依靠 CPU 线程极其精准地完成 WebGL 2.0 着色器编译、深度缓冲计算与像素渲染，不仅测试稳定度达到 100%，更实现了在纯无头环境下的跨平台高保真回归！

# CI 启动参数
electron . --disable-gpu-sandbox --use-gl=angle --use-angle=swiftshader --enable-webgl

• 1. 现象复现： 在开发机（Windows 11 带独立显卡）上测试全部顺畅通过，但在纯 Linux CI 服务器（Ubuntu Server）上运行时，Electron 启动瞬间报错： Failed to create a WebGL context: WebGL not supported or disabled in this configuration. 导致所有涉及 Phaser 游戏与粒子渲染的测试用例全盘红灯崩溃。
• 2. 根因追溯： Linux 云服务器没有物理显卡和显示器硬件（Headless），Chromium 默认会禁用所有 WebGL 硬件加速。
• 3. 第一性原理配置 SwiftShader 软件光栅化驱动： 我们在启动无头 Electron 时，注入了 Chromium 官方的 CPU 软件光栅化引擎（Google SwiftShader）：

五、 测试方案横向评测与收益看板