Cypress中已加载扩展无法响应keydown按键事件问题排查

配置信息 #

Manifest.json 快捷键配置 #

"commands": {
    "toggle_extension": {
        "suggested_key": {
          "default": "Ctrl+Shift+X",
          "mac": "Command+Shift+X"
        },
        "description": "Toggle Your Extension"
      }
}

开发依赖 #

"devDependencies": {
  "@types/chrome": "^0.0.262",
  "@types/jest": "^29.5.12",
  "copy-webpack-plugin": "^12.0.2",
  "cypress": "^13.6.6",
  "ts-loader": "^9.5.1",
  "typescript": "5.3.3",
  "webpack": "^5.90.3",
  "webpack-cli": "^5.1.4"
}

Cypress测试用例 #

describe("Test alert", () => {
  it("passes", () => {
    cy.visit("");

    cy.window().trigger('keydown', {
        key: "x", // "X" key code
        keyCode: 88,
        ctrlKey: true,
        shiftKey: true,
      });

    cy.get("#alert").should("exist");
  })
});

Cypress配置文件（cypress.config.ts） #

import { defineConfig } from "cypress";
import * as path from "path";

export default defineConfig({
  e2e: {
    baseUrl: "https://example.com",
    specPattern: "tests/**/*.cy.ts",
    supportFile: false,
    fixturesFolder: false,
    defaultCommandTimeout: 5000,
    viewportWidth: 1280,
    viewportHeight: 720,
    chromeWebSecurity: false,
    testIsolation: true,
    screenshotOnRunFailure: false,
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser, launchOptions) => {
          launchOptions.extensions.push(path.resolve(__dirname, "release"));
          return launchOptions;
      });
    }
  },
});

问题现象 #

执行命令 npx cypress run --browser chrome --headed 后，扩展已加载，但触发快捷键后alert元素始终未出现，测试未达到预期效果。

问题原因及解决办法 #

1. Cypress DOM事件无法触发浏览器级快捷键 #

通过manifest.json配置的扩展快捷键属于浏览器层面的监听，Cypress的cy.window().trigger()只能触发网页DOM内的事件，无法模拟浏览器级别的快捷键触发逻辑。

2. 替代方案：直接触发扩展核心逻辑 #

方案一：调用内容脚本暴露的方法

如果扩展的内容脚本将触发逻辑暴露在网页的window对象上，可直接在测试中调用：

describe("Test alert", () => {
  it("passes", () => {
    cy.visit("");
    
    // 假设内容脚本在window上暴露了toggleExtension方法
    cy.window().then(win => win.toggleExtension());

    cy.get("#alert").should("exist");
  })
});

方案二：通过Chrome DevTools Protocol触发命令

Cypress支持通过CDP与浏览器交互，直接触发扩展命令：
首先在cypress.config.ts的setupNodeEvents中注册CDP任务：

setupNodeEvents(on, config) {
  on('before:browser:launch', (browser, launchOptions) => {
      launchOptions.extensions.push(path.resolve(__dirname, "release"));
      return launchOptions;
  });

  // 注册CDP任务
  on('task', {
    cdp({ command, params }) {
      return new Promise((resolve) => {
        Cypress.browser?.send(command, params, resolve);
      });
    }
  });
}

然后修改测试用例：

describe("Test alert", () => {
  it("passes", () => {
    cy.visit("");
    
    // 使用CDP触发扩展命令
    cy.task('cdp', {
      command: 'browser.sendCommand',
      params: { command: 'toggle_extension' }
    });

    cy.get("#alert").should("exist");
  })
});

3. 检查扩展命令监听是否正确注册 #

确保扩展代码中存在chrome.commands.onCommand的监听逻辑，否则快捷键触发后不会执行任何操作：

chrome.commands.onCommand.addListener((command) => {
  if (command === "toggle_extension") {
    // 触发alert的逻辑，例如：
    document.body.innerHTML += '<div id="alert">Alert Triggered</div>';
  }
});

4. 验证快捷键是否被占用 #

打开Chrome的chrome://extensions/shortcuts页面，确认toggle_extension命令的实际快捷键与配置一致，避免被其他扩展或系统快捷键占用。

内容的提问来源于stack exchange，提问作者Tsingis