Electron

Playwright 对 Electron 自动化提供 实验性 支持。你可以通过以下方式访问 electron 命名空间：

🌐 Playwright has experimental support for Electron automation. You can access electron namespace via:

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

Electron 自动化脚本的一个示例是：

🌐 An example of the Electron automation script would be:

const { _electron: electron } = require('playwright');

(async () => {
  // Launch Electron app.
  const electronApp = await electron.launch({ args: ['main.js'] });

  // Evaluation expression in the Electron context.
  const appPath = await electronApp.evaluate(async ({ app }) => {
    // This runs in the main Electron process, parameter here is always
    // the result of the require('electron') in the main app script.
    return app.getAppPath();
  });
  console.log(appPath);

  // Get the first window that the app opens, wait if necessary.
  const window = await electronApp.firstWindow();
  // Print the title.
  console.log(await window.title());
  // Capture a screenshot.
  await window.screenshot({ path: 'intro.png' });
  // Direct Electron console to Node terminal.
  window.on('console', console.log);
  // Click button.
  await window.click('text=Click me');
  // Exit app.
  await electronApp.close();
})();

支持的 Electron 版本有：

• v12.2.0+
• v13.4.0+
• v14+

已知问题：

如果你无法启动 Electron 并且它会在启动过程中超时，请尝试以下操作：

🌐 If you are not able to launch Electron and it will end up in timeouts during launch, try the following:

• 确保 nodeCliInspect (FuseV1Options.EnableNodeCliInspectArguments) fuse 未 设置为 false。

模拟原生对话：

Playwright 不会拦截原生的 Electron dialog API（dialog.showOpenDialog、dialog.showSaveDialog、dialog.showMessageBox 等），因为这些调用发生在 Electron 主进程中并直接访问操作系统 API。使用 electronApplication.evaluate() 在主进程中替换相关方法，以便测试在没有任何操作系统级别 UI 的情况下确定性运行：

🌐 Playwright does not intercept the native Electron dialog API (dialog.showOpenDialog, dialog.showSaveDialog, dialog.showMessageBox, etc.) because those calls happen in the Electron main process and go straight to OS APIs. Use electronApplication.evaluate() to replace the relevant methods in the main process so tests run deterministically without any OS-level UI:

// Stub the open dialog to always return a fixed path.
await electronApp.evaluate(({ dialog }, filePaths) => {
  dialog.showOpenDialog = () => Promise.resolve({ canceled: false, filePaths });
}, ['/path/to/file.txt']);

// Stub the save dialog.
await electronApp.evaluate(({ dialog }, filePath) => {
  dialog.showSaveDialog = () => Promise.resolve({ canceled: false, filePath });
}, '/path/to/saved.txt');

// Stub showMessageBox to click the first button.
await electronApp.evaluate(({ dialog }) => {
  dialog.showMessageBox = () => Promise.resolve({ response: 0, checkboxChecked: false });
});

替换会持续有效直到应用关闭。同步版本（showOpenDialogSync、showSaveDialogSync、showMessageBoxSync）可以使用相同的方式进行存根——只需直接返回值，而不是返回 Promise。

🌐 The replacement persists until the application is closed. Synchronous variants (showOpenDialogSync, showSaveDialogSync, showMessageBoxSync) can be stubbed the same way — just return the value directly instead of a Promise.

---

方法

🌐 Methods

launch

Added in: v1.9 electron.launch

启动指定的 executablePath 的 Electron 应用。

🌐 Launches electron application specified with the executablePath.

用法

await electron.launch();
await electron.launch(options);

参数

• options Object (optional)

  • acceptDownloads boolean (optional) Added in: v1.12#

    是否自动下载所有附件。默认值为 true，表示接受所有下载。

  • args Array<string> (optional)#

    启动应用时传递的附加参数。通常在这里传递主脚本名称。

  • artifactsDir string (optional) Added in: v1.59#

    如果指定，工件（痕迹、视频、下载、HAR 文件等）将保存到此目录中。浏览器关闭时，该目录不会被清理。如果未指定，则使用临时目录，并在浏览器关闭时清理该目录。

  • bypassCSP boolean (optional) Added in: v1.12#

    切换是否绕过页面的内容安全策略。默认值为 false。

  • chromiumSandbox boolean (optional) Added in: v1.59#

    启用 Chromium 沙箱。默认值为 false。

  • colorScheme null | "light" | "dark" | "no-preference" (optional) Added in: v1.12#

    模拟 prefers-colors-scheme 媒体特性，支持的值为 'light' 和 'dark'。更多详情请参见 page.emulateMedia()。传入 null 可将模拟重置为系统默认值。默认值为 'light'。

  • cwd string (optional)#

    当前启动应用的工作目录。

  • env Object<string, string> (optional)#

    指定将在 Electron 中可见的环境变量。默认值为 process.env。

  • executablePath string (optional)#

    启动指定的 Electron 应用。如果未指定，则启动此包中安装的默认 Electron 可执行文件，位于 node_modules/.bin/electron。

  • extraHTTPHeaders Object<string, string> (optional) Added in: v1.12#

    一个包含附加 HTTP 头的对象，这些头将随每个请求发送。默认为无。

  • geolocation Object (optional) Added in: v1.12#

    • latitude number

      纬度在 -90 到 90 之间。

    • longitude number

      经度在 -180 到 180 之间。

    • accuracy number (optional)

      非负精度值。默认值为 0。

  • httpCredentials Object (optional) Added in: v1.12#

    • username string

    • password string

    • origin string (optional)

      限制在特定来源 (scheme://host:port) 上发送 http 凭据。

    • send "unauthorized" | "always" (optional)

      此选项仅适用于从对应的 APIRequestContext 发送的请求，并不影响从浏览器发送的请求。'always' - Authorization 头信息会随每个 API 请求发送基本认证凭据。'unauthorized - 凭据仅在收到带有 WWW-Authenticate 头的 401（未授权）响应时发送。默认为 'unauthorized'。

    HTTP 认证 的凭据。如果未指定来源，用户名和密码将在收到未授权响应时发送到任何服务器。

  • ignoreHTTPSErrors boolean (optional) Added in: v1.12#

    发送网络请求时是否忽略 HTTPS 错误。默认值为 false。

  • locale string (optional) Added in: v1.12#

    指定用户区域设置，例如 en-GB、de-DE 等。区域设置会影响 navigator.language 的值、Accept-Language 请求头的值以及数字和日期的格式规则。默认为系统默认区域设置。有关模拟的更多信息，请参阅我们的 模拟指南。

  • offline boolean (optional) Added in: v1.12#

    是否模拟网络离线。默认为 false。了解更多关于 网络模拟 的信息。

  • recordHar Object (optional) Added in: v1.12#

    • omitContent boolean (optional)

      可选设置，用于控制是否从 HAR 中省略请求内容。默认值为 false。已弃用，请改用 content 策略。

    • content "omit" | "embed" | "attach" (optional)

      可选设置，用于控制资源内容管理。如果指定 omit，内容不会被保存。如果指定 attach，资源将作为单独的文件或 ZIP 压缩包中的条目保存。如果指定 embed，内容将根据 HAR 规范内联存储在 HAR 文件中。默认情况下，对于 .zip 输出文件为 attach，对于所有其他文件扩展名为 embed。

    • path string

      要写入 HAR 文件的文件系统路径。如果文件名以 .zip 结尾，则默认使用 content: 'attach'。

    • mode "full" | "minimal" (optional)

      当设置为 minimal 时，仅记录从 HAR 路由所需的信息。这会省略在从 HAR 回放时不使用的大小、时间、页面、Cookies、安全性以及其他类型的 HAR 信息。默认值为 full。

    • urlFilter string | RegExp (optional)

      用于过滤存储在 HAR 中的请求的全局或正则表达式模式。当通过上下文选项提供了 baseURL 并且传入的 URL 是路径时，它会通过 new URL() 构造函数进行合并。默认情况下没有。

    启用对所有页面的 HAR 记录，并保存到 recordHar.path 文件中。如果未指定，则不会记录 HAR。请确保在保存 HAR 前等待 browserContext.close()。

  • recordVideo Object (optional) Added in: v1.12#

    • dir string (optional)

      要放入视频的目录路径。如果未指定，视频将存储在 artifactsDir（参见 browserType.launch() 选项）。

    • size Object (optional)

      • width number

        视频帧宽度。

      • height number

        视频帧高度。

      录制视频的可选尺寸。如果未指定，大小将等于 viewport 并缩小以适应 800x800。如果未显式配置 viewport，视频大小默认为 800x450。每页的实际画面如有必要将缩小以适应指定尺寸。

    • showActions Object (optional)

      • duration number (optional)

        每个注释显示的时间长度，单位为毫秒。默认值为 500。

      • position "top-left" | "top" | "top-right" | "bottom-left" | "bottom" | "bottom-right" (optional)

        操作标题覆盖的位置。默认值为 "top-right"。

      • fontSize number (optional)

        操作标题的字体大小（像素）。默认值为 24。

      如果指定，则在视频录制期间对交互元素启用可视注释。

    启用将所有页面的视频录制到 recordVideo.dir 目录。如果未指定，则不会录制视频。请确保等待 browserContext.close() 以便保存视频。

  • timeout number (optional) Added in: v1.15#

    等待应用启动的最长时间（毫秒）。默认值为 30000（30 秒）。传入 0 可禁用超时。

  • timezoneId string (optional) Added in: v1.12#

    更改上下文的时区。有关支持的时区 ID 列表，请参阅 ICU 的 metaZones.txt。默认使用系统时区。

  • tracesDir string (optional) Added in: v1.36#

    如果指定，跟踪将保存到此目录中。

返回

• Promise<ElectronApplication>#