# @applitools/visual-grid-client 中文文档

规范地址：https://npmcn.com/package/%40applitools/visual-grid-client/

版本：15\.14\.1
npm 元数据更新时间：2026-06-28T14:45:53.962Z
中文译文更新时间：2026-11-06T11:52:06.411Z
软件包许可：SEE LICENSE IN LICENSE

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40applitools/visual-grid-client
原文对照：https://npmcn.com/package/%40applitools/visual-grid-client/?lang=original
项目主页：https://applitools.com/
源码仓库：https://github.com/applitools/eyes.sdk.javascript1

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：134 kB，57 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=12\.13\.0
- 运行依赖：10 个
- 首次发布：2018-08-19T03:49:30.738Z
- 最新版本发布：2022-09-16T11:55:06.567Z
- 近 30 天下载量：12450（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：575（近 12 个月 0 个）

## 中文简介

一个以多姆快照渲染来驱动视觉网格的库.

## 安装

```sh
npm install @applitools/visual-grid-client
```

也可以使用：`pnpm add @applitools/visual-grid-client`、`yarn add @applitools/visual-grid-client`、`bun add @applitools/visual-grid-client`

## README

# 视网格客户端

一个以多姆快照渲染来驱动视觉网格的库.

## 安装

```sh
npm install @applitools/visual-grid-client
```

## 使用软件包

```js
const {makeVisualGridClient} = require('@applitools/visual-grid-client')
```

完整的API见下文.

## API 密码

### 视觉图像

-   要创建视觉的GridClient, 呼叫 `makeVisualGridClient`数字 :

```js
const {makeVisualGridClient} = require('@applitools/visual-grid-client')
const visualGridClient = makeVisualGridClient()
```

图像GridClient, 由 `makeVisualGridClient`,是一个具有以下功能的对象:

-   `openEyes(configOverride)`: 开始一组测试, 其中每个步骤都是一组根据浏览器的渲染 配置中的东西. 此函数将返回具有函数的对象(见下文),允许您在 Applitools parlance),作测试用.
    
-   `testWindow({openParams, checkParams, throwEx})`
    
-   `closeBatch()`
    

### 打开Eyes

Async 函数 `openEyes` 将创建一个测试。 实际上,它将创建一系列测试,每个浏览器配置一个 定义 `browser` 配置属性.

-   `openEyes` 接受一个配置对象,以覆盖所发现的默认配置 `makeVisualGridClient`,根据本测试.
    
-   接受 :
    
    -   代理 - 字符串或对象, 例如 :
        
        `https://username:password@myproxy`
        
        `{url: 'https://myproxy', username: 'my_user', password: 'my_password', isHttpOnly: false`
        
    -   更多参数 TBD.
        
-   返回对对象的许诺,其函数如下:
    
    -   `checkWindow(...)`: 创建一个"步骤",按照基线检查窗口. 注意这一点 函数不会失败,您需要 `await` 承诺从 `close()` 等待失败或成功 在测试中的一组步骤.
    -   `close()`: 同步关闭由 `openEyes`。 。 。 .
    -   `abort()`: 如果你想中止此测试(或一系列测试) 。 Async (英语).

### `checkWindow(...)`

`checkWindow` 接收对象,参数如下:

-   `tag`:步骤的名称,见于Applitools Eyes.
-   `url`: 浏览器地址栏中出现的URL. CDT中所有相对的URL都会与之相对.
-   `snapshots`: 单个圆顶快照或与 `browser` 发送数组 `openEyes`。DOM快照可以具有以下属性:
    -   `cdt`: HTML 和 设置及资源,在 `x-applitools-html/cdt` 格式(见下文)。 您可以使用 `domNodesToCdt` 从 a 创建 CDT `document`。 。 。 .
    -   `resourceUrls`:默认为空数组. 在 CDT 中找不到额外的资源 URL .
    -   `resourceContents`: 所有资源值的映射。 密钥是 URL( 相对于 `url` (b) 财产).
    -   `frames`: 结构相同 `snapshot`,递归.
-   `target`:渲染的目标. 可以成为其中之一 `window`, (中文(简体) ), `region`
-   `fully`: 设定时间 `target` 实值 `window`,如果 `fully` 实值 `true` 如果 `fully` 实值 `false` 然后快照就是取景口.
-   `selector`: 如果 `target` 实值 `region`,这是我们的目标选择器.
-   `region`: 如果 `target` 实值 `region`这就是我们的目标区域. 这是对象 `x`, (中文(简体) ), `y`, (中文(简体) ), `width`, (中文(简体) ), `height` 属性.
-   `ignore`语文: TBD
-   `floating`语文: TBD
-   `accessibility`语文: TBD
-   `strict`语文: TBD
-   `layout`语文: TBD
-   `content`语文: TBD
-   `sendDom`语文: TBD
-   `scriptHooks`:一组由浏览器在渲染过程中运行的脚本. 具有下列属性的对象:
    -   `beforeCaptureScreenshot`:在页面被装入后但在取取截图前运行的脚本. 该值是一个具有下列属性的对象:
    -   `url`:是的,再说一遍.
    -   `type`: 资源的内容类型.
    -   `value`(单位:千美元) `Buffer` 资源内容.
-   `matchLevel`:比较两个截图时使用的方法,它表示两个图像预期匹配的程度.
-   `accessibilitySettings`:用于截图的无障碍. 可能的值为"AA"和"AA". // 开始
-   `batchNotify`。 。 。 .

### 关闭( c)

`close` 接收 `throwEx` 参数,并返回承诺.

-   如果抛出Ex=真(默认) :
    -   如果在 `openEyes` 那就通过承诺吧 **已解决** 带有“测试结果”的矩阵.
    -   如果在定义的测试中发现有差异,则 `openEyes` 那么,承诺是 **被拒绝** 带有“测试结果”的矩阵.
    -   如果有任何像网络错误这样的出乎意料的错误 那么承诺就是 **被拒绝** 与“ Error ” 矩阵组合.
-   如果抛出Ex=虚假 :
    -   承诺总是 **已解决** 使用 Array < testResults > 错误.

### CDT 格式

```js
{
  domNodes: [
    {
      nodeType: number, // like in the DOM Standard
      nodeName: ‘...’ , // for elements and DocumentType
      nodeValue: ‘...’, // for text nodes
      attributes: [{name, value}, ...],
      childNodeIndexes: [index, index, ...]
    },
    //...
  ],
  resources: [
    {
      hashFormat: 'sha256', // currently the only hash format allowed
      hash: '....', // the hash of the resource.
      contentType: '...', // the mime type of the resource.
    },
    //...
  ]
}

```

### dom 节点TOCt

接受符合 DOM 规格的文档对象(浏览器文档很好,JSDOM文档也很好). 返回 cdt, 准备传递给 `checkWindow`

## 配置

-   见 [眼睛 Cypress 配置](https://github.com/applitools/eyes.cypress#advanced-configuration) 用于列表配置中的属性, 并理解视觉网格客户端 读取配置.

## 日志

♪ \* \* \* § \* \* \* § \* \*?

## 示例

示例 [摩诃迦叶](https://www.npmjs.com/package/mocha) 使用视觉网格客户端的测试 :

```js
const path = require('path')
const fs = require('fs')
const {makeVisualGridClient} = require('@applitools/visual-grid-client')
const {getProcessPageAndSerialize} = require('@applitools/dom-snapshot')
const puppeteer = require('puppeteer')

describe('visual-grid-client test', function() {
  let visualGridClient
  let closePromises = []
  let processPageAndSerialize
  let browser
  let page

  before(async () => {
    browser = await puppeteer.launch()
    page = await browser.newPage()

    visualGridClient = makeVisualGridClient({
      showLogs: true,
    })

    processPageAndSerialize = `(${await getProcessPageAndSerializeScript()})()`
  })

  after(async () => {
    await browser.close()
    const results = await Promise.all(closePromises)
    await visualGridClient.closeBatch() // after all sessions ended (session = open checkWindow close)
    return results;
  })

  let checkWindow, close
  beforeEach(async () => {
    ;({checkWindow, close} = await visualGridClient.openEyes({
      appName: 'visual grid client with a cat',
      testName: 'visual-grid-client test',
    }))
  })
  afterEach(() => closePromises.push(close()))

  it('should work', async () => {
    await page.goto('index.html')
    const {cdt, url, resourceUrls, blobs, frames} = await page.evaluate(processPageAndSerialize)
    const resourceContents = blobs.map(({url, type, value}) => ({
      url,
      type,
      value: Buffer.from(value, 'base64'),
    }));
    checkWindow({
      tag: 'first test',
      target: 'region',
      fully: false,
      url,
      snapshots: {
        cdt,
        resourceUrls,
        resourceContents,
        frames,
      }
    })
  })
})
```

## 示例测试窗口( )

```js
const {makeVisualGridClient} = require('@applitools/visual-grid-client')
const {getProcessPageAndSerialize} = require('@applitools/dom-snapshot')
const puppeteer = require('puppeteer')

describe('visual-grid-client test', function() {
  let visualGridClient
  let closePromises = []
  let processPageAndSerialize
  let browser
  let page

  before(async () => {
    browser = await puppeteer.launch()
    page = await browser.newPage()

    visualGridClient = makeVisualGridClient({
      showLogs: true,
    })

    processPageAndSerialize = `(${await getProcessPageAndSerializeScript()})()`
  })

  after(async () => {
    await browser.close()
    const results = await Promise.all(closePromises)
  })

  it('should work', async () => {
    await page.goto('index.html')
    const {cdt, url, resourceUrls, blobs, frames} = await page.evaluate(processPageAndSerialize)
    const resourceContents = blobs.map(({url, type, value}) => ({
      url,
      type,
      value: Buffer.from(value, 'base64'),
    }));

    const checkParams = {
      tag: 'first test',
      target: 'region',
      fully: false,
      url,
      snapshots: {
        cdt,
        resourceUrls,
        resourceContents,
        frames,
      }
    };

    const openParams = {
      appName: 'visual grid client with a cat',
      testName: 'visual-grid-client test',
    }

    const results = await testWindow({checkParams, openParams, throwEx: false})
  })
})
```

## 捐款

### 生成更改日志

最好的办法是跑 `npm run changelog`这样做的先决条件是: [强克](https://stedolan.github.io/jq/) 在 git 配置中安装并定义以下内容:

```sh
git config changelog.format "* %s - %an [[%h](https://github.com/applitools/visual-grid-client/commit/%H)]"
```

## 常见问题

### @applitools/visual-grid-client 是什么？

一个以多姆快照渲染来驱动视觉网格的库\.

### 如何安装 @applitools/visual-grid-client？

在项目目录运行 npm install @applitools/visual-grid-client，或使用 pnpm add / yarn add / bun add。

### @applitools/visual-grid-client 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/applitools\_\_visual-grid-client 是否存在。

### @applitools/visual-grid-client 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @applitools/visual-grid-client 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=12\.13\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @applitools/visual-grid-client 可以商用吗？

@applitools/visual-grid-client 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @applitools/visual-grid-client 的下载量有多少？

根据 npm 官方下载统计，@applitools/visual-grid-client 在 2026/10/07 – 2026/11/05 这 30 天内被下载 12,450 次，日均约 415 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @applitools/visual-grid-client 还在维护吗？

最新版本 15\.14\.1 发布于 2022/09/16（4 年前）；至今共发布 575 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/08/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。