多显示器测试¶

virtualDisplay 插件利用 macOS CoreGraphics API 创建虚拟显示器，使您可以在无需物理显示器的情况下编写和运行多显示器测试。由于 macOS CoreGraphics 的一些特殊行为，建议在编写测试之前完整阅读一遍本指南。

方法¶

virtualDisplay.create([options])¶

创建一个虚拟显示器并返回显示器 ID。

```js @ts-nocheck const virtualDisplay = require('@electron-ci/virtual-display') // Default: 1920×1080 at origin (0, 0) const displayId = virtualDisplay.create()

```js @ts-nocheck
const virtualDisplay = require('@electron-ci/virtual-display')
// Custom options (all parameters optional and have default values)
const displayId = virtualDisplay.create({
  width: 2560, // Display width in pixels
  height: 1440, // Display height in pixels
  x: 1920, // X position (top-left corner)
  y: 0 // Y position (top-left corner)
})

返回： number - 用于标识显示器的唯一显示器 ID。创建显示器失败时返回 0。

[!NOTE] 建议在每次测试前调用 virtualDisplay.forceCleanup()，以防止该测试中的显示器创建失败。macOS CoreGraphics 维护一个内部显示器 ID 分配池，在测试期间快速创建和销毁虚拟显示器时可能会损坏。如果没有正确清理，后续显示器创建可能会因显示器 ID 不一致而失败，从而导致测试不稳定。

virtualDisplay.forceCleanup()¶

对所有虚拟显示器执行完整清理，并重置 macOS CoreGraphics 显示系统。

```js @ts-nocheck beforeEach(() => { virtualDisplay.forceCleanup() })

#### `virtualDisplay.destroy(displayId)` {#virtualdisplaydestroydisplayid}

移除虚拟显示器。

```js @ts-nocheck
virtualDisplay.destroy(displayId)

[!NOTE] 使用后始终销毁虚拟显示器，以防止损坏 macOS CoreGraphics 显示池并影响后续测试。

推荐用法模式¶

```js @ts-nocheck describe('multi-monitor tests', () => { const virtualDisplay = require('@electron-ci/virtual-display') beforeEach(() => { virtualDisplay.forceCleanup() })

it('should handle multiple displays', () => { const display1 = virtualDisplay.create({ width: 1920, height: 1080, x: 0, y: 0 }) const display2 = virtualDisplay.create({ width: 2560, height: 1440, x: 1920, y: 0 }) // Your test logic here virtualDisplay.destroy(display1) virtualDisplay.destroy(display2) }) })

## 显示器约束 {#display-constraints}

### 尺寸限制 {#size-limits}

虚拟显示器的最小尺寸为 720×720 像素，最大尺寸为 8192×8192 像素。实际限制可能因您的 Mac 图形能力而异，因此超出此范围（如 9000×6000）的尺寸在某些系统上可能会失败。

```js @ts-nocheck
// Safe sizes for testing
virtualDisplay.create({ width: 1920, height: 1080 }) // Full HD
virtualDisplay.create({ width: 3840, height: 2160 }) // 4K

定位行为¶

macOS 通过自动调整显示器位置来维护连续的桌面空间，如果存在任何重叠或间隙。在出现任一情况时，新原点的放置位置会尽可能接近请求的位置，同时不会与显示器重叠，也不会在显示器之间留下间隙。

重叠：

```js @ts-nocheck // Requested positions const display1 = virtualDisplay.create({ x: 0, y: 0, width: 1920, height: 1080 }) const display2 = virtualDisplay.create({ x: 500, y: 0, width: 1920, height: 1080 })

// macOS automatically repositions display2 to x: 1920 to prevent overlap const actualBounds = screen.getAllDisplays().map(d => d.bounds) // Result: [{ x: 0, y: 0, width: 1920, height: 1080 }, { x: 1920, y: 0, width: 1920, height: 1080 }]

**间隙：**

```js @ts-nocheck
// Requested: gap between displays
const display1 = virtualDisplay.create({ width: 1920, height: 1080, x: 0, y: 0 })
const display2 = virtualDisplay.create({ width: 1920, height: 1080, x: 2000, y: 0 })
// macOS snaps display2 to x: 1920 (eliminates 80px gap)

[!NOTE] 创建后始终使用 screen.getAllDisplays() 验证实际位置，因为 macOS 可能会调整坐标，使其不同于设置的值。