cypress-plugin-snapshots

Cypress.io 的快照测试插件。

安装

npm i cypress-plugin-snapshots -S

文本快照的用法

describe('data test', () => {
  it('toMatchSnapshot - JSON', () => {
    return cy.request('data.json')
      .its('body')
      .toMatchSnapshot();
  });

  it('toMatchSnapshot - JSON with options', () => {
    return cy.request('data.json')
      .its('body')
      .toMatchSnapshot({
        ignoreExtraFields: true,
      });
  });

  it('toMatchSnapshot - HTML', () => {
    cy.visit('page.html')
      .then(() => {
        cy.get('div').toMatchSnapshot();
      });
  });
});

您可以向 toMatchSnapshot 传递以下选项以覆盖默认行为。

{
  "ignoreExtraFields": false,         // Ignore fields that are not in snapshot
  "ignoreExtraArrayItems": false,     // Ignore if there are extra array items in result
  "normalizeJson": true,              // Alphabetically sort keys in JSON
  "replace": {                        // Replace `${key}` in snapshot with `value`.
    "key": "value",
  }
}

replace 请谨慎使用 replace。测试应当是确定性的。通常，影响测试结果（例如通过模拟数据）比影响快照是更好的解决方案。

图像快照的用法

it('toMatchImageSnapshot - element', () => {
  cy.visit('/static/stub.html')
    .then(() => {
      cy.get('[data-test=test]')
        .toMatchImageSnapshot();
    });
});

it('toMatchImageSnapshot - whole page', () => {
  cy.visit('/static/stub.html')
    .then(() => {
      cy.document()
        .toMatchImageSnapshot();
    });
});

您可以向 toMatchImageSnapshot 传递以下选项以覆盖默认行为。

{
  "imageConfig": {
    "createDiffImage": true,                // Should a "diff image" be created, can be disabled for performance
    "threshold": 0.01,                      // Amount in pixels or percentage before snapshot image is invalid
    "thresholdType": "percent",             // Can be either "pixel" or "percent"
  },
  "name": "custom image name",            // Naming resulting image file with a custom name rather than concatenating test titles
  "separator": "custom image separator",  // Naming resulting image file with a custom separator rather than using the default ` #`
}

您还可以使用 cypress.screenshot 参数列表 中的任何选项。

例如：

cy.get('.element')
  .toMatchImageSnapshot({
    clip: { x: 0, y: 0, width: 100, height: 100 },
  });

配置 Cypress.io

将此添加到您的 cypress.json 配置文件中：

"ignoreTestFiles": [
  "**/__snapshots__/*",
  "**/__image_snapshots__/*"
]

插件

找到您的 cypress/plugins/index.js 文件并将其更改为如下所示：

const { initPlugin } = require('cypress-plugin-snapshots/plugin');

module.exports = (on, config) => {
  initPlugin(on, config);
  return config;
};

命令

找到你的 cypress/support/index.js 文件并添加以下行：

import 'cypress-plugin-snapshots/commands';

修改默认配置

您可以自定义 Cypress 项目根目录中的 cypress.json 文件中的配置。

将以下配置添加到您的 cypress.json 文件中，以修改默认值。

"env": {
  "cypress-plugin-snapshots": {
    "autoCleanUp": false,            // Automatically remove snapshots that are not used by test
    "autopassNewSnapshots": true,    // Automatically save & pass new/non-existing snapshots
    "diffLines": 3,                  // How many lines to include in the diff modal
    "excludeFields": [],             // Array of fieldnames that should be excluded from snapshot
    "ignoreExtraArrayItems": false,  // Ignore if there are extra array items in result
    "ignoreExtraFields": false,      // Ignore extra fields that are not in `snapshot`
    "normalizeJson": true,           // Alphabetically sort keys in JSON
    "prettier": true,                // Enable `prettier` for formatting HTML before comparison
    "imageConfig": {
      "createDiffImage": true,       // Should a "diff image" be created, can be disabled for performance
      "resizeDevicePixelRatio": true,// Resize image to base resolution when Cypress is running on high DPI screen, `cypress run` always runs on base resolution
      "threshold": 0.01,             // Amount in pixels or percentage before snapshot image is invalid
      "thresholdType": "percent"     // Can be either "pixels" or "percent"
    },
    "screenshotConfig": {            // See https://docs.cypress.io/api/commands/screenshot.html#Arguments
      "blackout": [],
      "capture": "fullPage",
      "clip": null,
      "disableTimersAndAnimations": true,
      "log": false,
      "scale": false,
      "timeout": 30000
    },
    "serverEnabled": true,           // Enable "update snapshot" server and button in diff modal
    "serverHost": "localhost",       // Hostname for "update snapshot server"
    "serverPort": 2121,              // Port number for  "update snapshot server"
    "updateSnapshots": false,        // Automatically update snapshots, useful if you have lots of changes
    "backgroundBlend": "difference"  // background-blend-mode for diff image, useful to switch to "overlay"
  }
}

注意事项 :warning:

目前在使用此插件运行 Cypress 中的 "All Tests" 时存在一个问题。您可以在此处](https://github.com/meinaart/cypress-plugin-snapshots/issues/10) 和此处](https://github.com/cypress-io/cypress/issues/3090) 跟踪该问题的进展。在运行 "All Tests" 时，任何使用 cypress-plugin-snapshots 的测试都会抛出错误。

路线图

以下是正在考虑在下一个版本中实现的功能列表。

• 修复包含可替换字段的 "update snapshot" 按钮的处理
• 在无头模式下禁用 "update snapshots" 服务器
• 添加更多单元测试
• 添加 JSDoc 文档
• 改进 TypeScript 绑定

贡献

在没有正式风格指南的情况下，请注意保持现有的编码风格。

许可证

此插件根据 MIT 许可证发布。