如何让 Playwright 自动化测试的显示鼠标？—— 注入式 Mouse Helper 实践

在进行 E2E（端到端）自动化测试时，我们经常会选择以 Headed（有头/有 GUI 界面） 模式启动浏览器，以便实时观察测试用例的交互行为是否符合预期。

然而，在使用 Playwright 运行有头测试时，许多开发者都会遇到一个非常疑惑的现象：

浏览器中的按钮被物理点击了、Canvas 图形被物理拖拽绘制了，但屏幕上的鼠标光标（Cursor）却始终静止在原处，或者根本没有任何物理指针在运动。整个过程像是有隐形的"幽灵"在操控网页。

这使得在排查诸如"画布物理拖拉碰撞"或"下拉菜单悬停失败"等复杂的交互问题时，调试体验变得像是一个黑盒子。

本文将为您深度拆解这一现象的技术根源，并分享一种在业界广受赞誉的无侵入式鼠标指示器（Playwright Mouse Helper） 实现方案，帮助您在测试运行中"看清"鼠标的每一步操作轨迹。

🔎 一、为什么 Playwright 默认看不见鼠标指针？

这与 Playwright 底层的驱动机制密不可分。

常规的 Selenium 等传统测试工具，往往是通过操作系统的系统级 API 来模拟真实的物理鼠标指针移动，这会导致在运行测试时抢占用户的实际鼠标控制权。

而 Playwright 则是直接通过 CDP (Chrome DevTools Protocol) 协议或浏览器的底层调试通道，直接向网页的目标元素派发（Dispatch）物理鼠标事件（如 mousemove、mousedown、mouseup 等事件帧）。

这种方式速度极快，且完全不会抢占或干扰您当前操作系统的物理鼠标指针。
但它的负面效果就是：浏览器虽然接收并响应了这些物理事件，但并不会在浏览器的 GUI 渲染层上绘制和渲染系统光标的移动轨迹。

因此，为了解决这种调试盲区，我们需要在网页的渲染层"自己画一个指针"。

💡 二、破案思路：前端无侵入式"跟随投影"

要在浏览器页面中模拟并可视化鼠标光标，最优雅且无害的方式是通过一段极简的 JavaScript 脚本向当前页面动态注入一个指示器 DOM 节点：

外观设计 ：在 body 根部挂载一个高优先级的半透明圆形 div，通过 CSS 样式让它看起来像一个炫酷的光标。
完全穿透 ：通过 CSS 的 pointer-events: none; 属性，确保这个指示器绝对不会被鼠标点击捕获，从而 100% 避免它干扰测试中真实的点击命中决策。
轨迹跟随 ：在全局 document 上注册捕获阶段的事件监听（mousemove），将指示器的 left / top 实时与物理事件的坐标对齐。
点击特效 ：通过 mousedown / mouseup 动态增删 .click 类名，实现点击时指示器闪烁变绿并伴随轻微缩放特效。

💻 三、单页面注入式实现代码 (Vanilla JS)

在测试脚本中，我们可以编写如下辅助方法，在页面成功打开后将其注入：

less 复制代码

/**
 * 向页面中注入物理鼠标指示器（Playwright Mouse Helper）
 * @param {import('playwright').Page} page Playwright 页面实例
 */
async function installMouseHelper(page) {
  try {
    await page.evaluate(() => {
      // 1. 创建指示器 DOM 节点
      const box = document.createElement('playwright-mouse-pointer');
      
      // 2. 注入样式
      const styleElement = document.createElement('style');
      styleElement.innerHTML = `
        playwright-mouse-pointer {
          pointer-events: none; /* 关键：确保光标不阻挡真实的点击事件 */
          position: absolute;
          top: 0;
          left: 0;
          width: 18px;
          height: 18px;
          background: rgba(239, 68, 68, 0.4);   /* 默认移动状态：半透明红 */
          border: 2px solid rgba(239, 68, 68, 0.8);
          border-radius: 50%;
          margin: -9px 0 0 -9px; /* 居中校准 */
          z-index: 999999;       /* 绝对置顶 */
          transition: background 0.15s, border-color 0.15s, transform 0.15s;
        }
        playwright-mouse-pointer.click {
          background: rgba(34, 197, 94, 0.6);   /* 点击按下状态：亮眼绿 */
          border-color: rgba(34, 197, 94, 0.9);
          transform: scale(0.8);                /* 点击时轻微收缩特效 */
        }
      `;
      
      document.head.appendChild(styleElement);
      document.body.appendChild(box);
      
      // 3. 全局事件捕获与更新
      document.addEventListener('mousemove', event => {
        box.style.left = event.pageX + 'px';
        box.style.top = event.pageY + 'px';
      }, true);
      
      document.addEventListener('mousedown', () => {
        box.classList.add('click');
      }, true);
      
      document.addEventListener('mouseup', () => {
        box.classList.remove('click');
      }, true);
    });
  } catch (e) {
    console.warn('⚠️ 注入鼠标指示器失败，跳过...', e.message);
  }
}

在您的单页面测试用例中，只需简单调用即可开启光标显示：

csharp 复制代码

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();
  
  await page.goto('http://127.0.0.1:5173');
  
  // 页面加载完成后，立刻注入指示器
  await installMouseHelper(page);
  
  // 后续所有的 hover、click、drag 动作，您都将在有头界面中看见红绿圆点的精确移动！
  await page.locator('#target-btn').click();
})();

🛠️ 四、高级工程大器：全局自动挂载方案 (Fixtures)

在成熟的测试工程中，如果每次编写测试用例都需要手动调用 installMouseHelper，会产生大量样板代码。

对此，Playwright 提供了功能强大的 Fixtures（测试夹具） 机制。我们可以通过自定义 page 夹具，并结合 addInitScript 方法，实现对所有测试页面在初始化阶段的全局自动注入：

1. 编写扩展模块 `fixtures.ts`

less 复制代码

// tests/fixtures.ts
import { test as base } from '@playwright/test';

export const test = base.extend({
  page: async ({ page }, use) => {
    // addInitScript 能够在页面加载前、任何脚本运行之前自动注册初始化脚本
    await page.addInitScript(() => {
      window.addEventListener('DOMContentLoaded', () => {
        const box = document.createElement('playwright-mouse-pointer');
        const styleElement = document.createElement('style');
        styleElement.innerHTML = `
          playwright-mouse-pointer {
            pointer-events: none; position: absolute;
            top: 0; left: 0; width: 18px; height: 18px;
            background: rgba(239, 68, 68, 0.4); border: 2px solid rgba(239, 68, 68, 0.8);
            border-radius: 50%; margin: -9px 0 0 -9px; z-index: 999999;
            transition: background 0.15s, border-color 0.15s, transform 0.15s;
          }
          playwright-mouse-pointer.click {
            background: rgba(34, 197, 94, 0.6); border-color: rgba(34, 197, 94, 0.9);
            transform: scale(0.8);
          }
        `;
        document.head.appendChild(styleElement);
        document.body.appendChild(box);
        
        document.addEventListener('mousemove', event => {
          box.style.left = event.pageX + 'px';
          box.style.top = event.pageY + 'px';
        }, true);
        document.addEventListener('mousedown', () => box.classList.add('click'), true);
        document.addEventListener('mouseup', () => box.classList.remove('click'), true);
      });
    });

    // 将就绪的 page 实例投喂给下游测试用例
    await use(page);
  }
});

2. 在测试用例中直接引入

csharp 复制代码

// example.spec.ts
// 使用我们刚刚导出的 test，而不是 Playwright 原生的 test
import { test } from './fixtures'; 

test('Canvas 矩形框物理拖拽测试', async ({ page }) => {
  await page.goto('http://127.0.0.1:5173');
  
  // 此时无需进行任何额外配置，光标已全局生效！
  await page.mouse.move(100, 100);
  await page.mouse.down();
  await page.mouse.move(300, 300);
  await page.mouse.up();
});

🎯 总结

通过在网页的 DOM 初始化阶段动态注入一个带事件监听、pointer-events: none 穿透的指示性小圆球，我们能以极其轻量、高内聚的方式将 Playwright 的物理操作直观地呈现在屏幕上。

无论是进行日常录屏演示，依然调试复杂的 Konva/Canvas 等坐标密集型拖拉操作，这套 Mouse Helper 指标都是您测试工程中不可多得的神兵利器！