Flutter测试验证插件approval_tests的使用

Flutter测试验证插件approval_tests的使用

Approval Tests实现于Dart 🚀

📖 关于 #

Approval Tests 是断言的一种替代方案。它们在测试包含复杂值（如长字符串）、大量属性或对象集合的对象时非常有用。

Approval Tests 通过拍摄结果快照并确认它们没有变化来简化这一过程。

在常规单元测试中，你会说 expect(person.getAge(), 5)。使用 Approval Tests，当你要断言的内容不再是基本类型而是复杂对象时，你可以这样做：例如，Approvals.verify(person)。

我在 Dart 中实现了一个 Approval Tests 的版本。如果有人愿意帮忙，请 联系我。🙏

包 #

ApprovalTests 设计用于两个级别：Dart 和 Flutter。

包	版本	描述
approval_tests		Dart 包用于 approval 测试的 单元 测试 (主要)
approval_tests_flutter		Flutter 包用于 approval 测试的 小部件 和 集成 测试

📋 如何工作 #

• 第一次运行测试时会自动创建一个 approved 文件，如果没有这样的文件。
• 如果更改后的结果与 approved 文件完全匹配，则测试通过。
• 如果有差异，一个 reporter 工具会突出显示不匹配部分，并且测试失败。
• 如果测试通过，received 文件会被自动删除。你可以通过在 options 中改变 deleteReceivedFile 的值来更改此行为。如果测试失败，received 文件会保留以供分析。

📦 安装 #

在你的 pubspec.yaml 文件中添加以下内容：

dependencies:
  approval_tests: ^1.1.0

👀 入门 #

最好的入门方式是下载并打开启动项目：

• Approvaltests.Dart.StarterProject

这是一个可以导入任何编辑器或IDE的标准项目，并且还包括GitHub Actions的CI。

它已经准备好了：

• 一个合适的 .gitignore 以排除 approval 艺术品
• 一个内置的 linter
• 一个 GitHub 动作来运行测试，你可以在 README.md 文件中的徽章上随时查看测试状态。

📚 如何使用 #

为了使用 Approval Tests，用户需要：

1. 设置测试：这涉及将 Approval Tests 库导入到自己的代码中。
2. 可选地设置报告器：报告器是在测试失败时突出显示批准文件和接收文件之间差异的工具。虽然不是必需的，但它们使看到导致测试失败的变化变得更加容易。默认报告器是 CommandLineReporter。你也可以使用 DiffReporter 在IDE中比较文件，以及使用 GitReporter 在 Git GUI 中查看差异。
3. 管理 approved 文件：当第一次运行测试时，会自动生成一个批准文件。这个文件将代表预期的结果。一旦测试结果令人满意，应更新批准文件以反映这些变化。稍后我将说明如何操作。

这种设置很有用，因为它缩短了反馈循环，节省了开发人员的时间，只需突出显示发生了什么变化，而不是要求他们解析整个输出来看他们的更改产生了什么影响。

批准结果

批准结果意味着保存 .approved.txt 文件为所需的结果。

我们将稍后提供更多解释，但简要地说，这里有几种常见的方法来完成此操作。

• 通过 Diff 工具

大多数 Diff 工具都有将文本从左移到右的功能，并保存结果。 如何使用 Diff 工具请看下方，有一个 Comparator 类为此目的。

• 通过 CLI 命令

你可以在终端中运行命令来审查文件：

dart run approval_tests:review

运行命令后，文件将被分析，然后你会被要求选择一个选项：

• y - 批准接收文件。
• n - 拒绝接收文件。
• view - 查看接收文件和批准文件之间的差异。选择 v 后，你会被问及想要使用哪个 IDE 来查看差异。

• 通过 approveResult 属性

如果你想在运行测试后自动保存结果，你需要在 Options 中使用 approveResult 属性：

void main() {
  test('test JSON object', () {
    final complexObject = {
      'name': 'JsonTest',
      'features': ['Testing', 'JSON'],
      'version': 0.1,
    };

    Approvals.verifyAsJson(
      complexObject,
      options: const Options(
        approveResult: true,
      ),
    );
  });
}

这将生成以下文件： example_test.test_JSON_object.approved.txt

{
  "name": "JsonTest",
  "features": [
    "Testing",
    "JSON"
  ],
  "version": 0.1
}

• 通过文件重命名

你可以直接将 .received 文件重命名为 .approved。

报告器

报告器是 Approval Tests 中在不匹配时启动 Diff 工具的部分。它们是系统的一部分，使查看发生了什么变化变得容易。

该包中有几个可用的报告器：

• CommandLineReporter - 这是默认报告器，它将在终端中输出差异。
• GitReporter - 这个报告器将在 Git GUI 中打开差异。
• DiffReporter - 这个报告器将在你的 IDE 中打开 Diff 工具。
  • 对于 Diff Reporter，我使用默认路径到 IDE，如果某些东西不起作用，则你可以在控制台中看到预期正确的 IDE 路径，并指定自定义 Diff 信息。你也可以联系我寻求帮助。

要使用 DiffReporter，只需要将其添加到 options 中：

 options: const Options(
   reporter: const DiffReporter(),
 ),

📝 示例 #

我在这里提供了一些小例子来展示如何使用该包。 在 example 文件夹中还有更多例子供你探索。将来我会添加更多的例子。 在 gilded_rose 文件夹内，有一个使用 ApprovalTests 测试 Gilded Rose kata 的旧代码的例子。你可以学习它以了解如何使用该包来测试复杂的代码。

verify_methods 文件夹中有一些使用不同 ApprovalTests 方法的小例子。

JSON 示例

使用 verifyAsJson 时，如果你传递的数据模型作为 JsonItem，嵌套其他模型作为 AnotherItem 和 SubItem，则需要为每个模型添加一个 toJson 方法以使序列化成功。

void main() {
  const jsonItem = JsonItem(
    id: 1,
    name: "JsonItem",
    anotherItem: AnotherItem(id: 1, name: "AnotherItem"),
    subItem: SubItem(
      id: 1,
      name: "SubItem",
      anotherItems: [
        AnotherItem(id: 1, name: "AnotherItem 1"),
        AnotherItem(id: 2, name: "AnotherItem 2"),
      ],
    ),
  );

  test('verify model', () {
    Approvals.verifyAsJson(
      jsonItem,
      options: const Options(
        deleteReceivedFile:
            true, // 自动删除接收文件。
        approveResult:
            true, // 自动批准结果。创建批准文件后可以移除此属性。
      ),
    );
  });
}

这将生成以下文件： verify_as_json_test.verify_model.approved.txt

{
  "jsonItem": {
    "id": 1,
    "name": "JsonItem",
    "subItem": {
      "id": 1,
      "name": "SubItem",
      "anotherItems": [
        {
          "id": 1,
          "name": "AnotherItem 1"
        },
        {
          "id": 2,
          "name": "AnotherItem 2"
        }
      ]
    },
    "anotherItem": {
      "id": 1,
      "name": "AnotherItem"
    }
  }
}

❓ 哪些文件艺术品应从源代码控制中排除 #

你必须将所有 approved 文件添加到源代码控制系统中。但是 received 文件会在每次运行时发生变化，应该被忽略。对于 Git，将以下内容添加到你的 .gitignore 文件中：

*.received.*