approval_tests 0.4.5

Approval Tests implementation in Dart. Inspired by ApprovalTests.

Approval Tests implementation in Dart 🚀

📖 About

Approval Tests are an alternative to assertions. You’ll find them useful for testing objects with complex values (such as long strings), lots of properties, or collections of objects.

Approval tests simplify this by taking a snapshot of the results, and confirming that they have not changed.

In normal unit testing, you say expect(person.getAge(), 5). Approvals allow you to do this when the thing that you want to assert is no longer a primitive but a complex object. For example, you can say, Approvals.verify(person).

I am writing an implementation of Approval Tests in Dart. If anyone wants to help, please text me. 🙏

📦 Installation

Add the following to your pubspec.yaml file:

dependencies:
  approval_tests: ^0.4.5

👀 Getting Started

The best way to get started is to download and open the starter project:

• Approvaltests.Dart.StarterProject

This is a standard project that can be imported into any editor or IDE and also includes CI with GitHub Actions.

It comes ready with:

• A suitable .gitignore to exclude approval artifacts
• A ready linter with all rules in place
• A GitHub action to build and run tests
• A GitHub build status ToBadge

📚 How to use

Approving Results

Approving results just means saving the .approved.txt file with your desired results.

We’ll provide more explanation in due course, but, briefly, here are the most common approaches to do this.

• Via Diff Tool

Most diff tools have the ability to move text from left to right, and save the result. How to use diff tools is just below, there is a Comparator class for that.

• Via approveResult property

If you want the result to be automatically saved after running the test, you need to use the approveResult property in Options:

void main() {
  test('test complex JSON object', () {
    final complexObject = {
      'name': 'JsonTest',
      'features': ['Testing', 'JSON'],
      'version': 0.1,
    };
    Approvals.verifyAsJson(
      complexObject,
      options: const Options(
        approveResult: true,
      ),
    );
  });
}

^{snippet source | anchor}

this will result in the following file example_test.approved.txt

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

^{snippet source | anchor}

• Via file rename

You can just rename the .received file to .approved.

Comparators

You can use different comparators to compare files. The default is CommandLineComparator which compares files in the console.

To use IDEComparator you just need to add it to options:

 options: const Options(
   comparator: IDEComparator(
      ide: ComparatorIDE.visualStudioCode,
   ),
 ),

But before you add an IDEComparator you need to do the initial customization:

• Visual Studio Code

  • For this method to work, you need to have Visual Studio Code installed on your machine.
  • And you need to have the code command available in your terminal.
  • To enable the code command, press Cmd + Shift + P and type Shell Command: Install 'code' command in PATH.

• IntelliJ IDEA

  • For this method to work, you need to have IntelliJ IDEA installed on your machine.
  • And you need to have the idea command available in your terminal.
  • To enable the idea command, you need to create the command-line launcher using Tools - Create Command-line Launcher in IntelliJ IDEA.

• Android Studio

  • For this method to work, you need to have Android Studio installed on your machine.
  • And you need to have the studio command available in your terminal.
  • To enable the studio command, you need to create the command-line launcher using Tools - Create Command-line Launcher in Android Studio.

📝 Examples

I have provided a couple of small examples here to show you how to use the package. There are more examples in the example folder for you to explore. I will add more examples in the future. Inside, in the gilded_rose folder, there is an example of using ApprovalTests to test the legacy code of Gilded Rose kata. You can study it to understand how to use the package to test complex code.

And the verify_methods folder has small examples of using different ApprovalTests methods for different cases.

JSON example

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 JSON output of an object', () {
    Approvals.verifyAsJson(
      jsonItem,
      options: const Options(
        deleteReceivedFile:
            true, // Automatically delete the received file after the test.
        approveResult:
            true, // Approve the result automatically. You can remove this property after the approved file is created.
      ),
    );
  });
}

^{snippet source | anchor}

this will result in the following file verify_as_json_test.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"
    }
  }
}

^{snippet source | anchor}

❓ Which File Artifacts to Exclude from Source Control

You must add any approved files to your source control system. But received files can change with any run and should be ignored. For Git, add this to your .gitignore:

*.received.*

✉️ For More Information

Questions?

Ask me on Telegram: @yelmuratoff.
Email: [e-mail]

Video Tutorials

• Getting Started with ApprovalTests.Swift
• How to Verify Objects (and Simplify TDD)
• Verify Arrays and See Simple, Clear Diffs
• Write Parameterized Tests by Transforming Sequences
• Wrangle Legacy Code with Combination Approvals

You can also watch a series of short videos about using ApprovalTests in .Net on YouTube.

Podcasts

Prefer learning by listening? Then you might enjoy the following podcasts:

• Hanselminutes
• Herding Code
• The Watir Podcast

Coverage

🤝 Contributing

Show some 💙 and star the repo to support the project! 🙌
The project is in the process of development and we invite you to contribute through pull requests and issue submissions. 👍
We appreciate your support. 🫰

Thanks to all contributors of this package