January 25, 2022

ApprovalTests for Powerful Assertions in Swift: How to Get Started

Click to play


I’m Jon Reid, and I want to introduce you to a new testing tool for Swift called ApprovalTests.

For more:

Adding ApprovalTests

We’re going to start in an iOS application. You can see I have a very simple app that has a place for unit tests.

The first thing we need to do is add ApprovalTests. First, let’s look it up in the Swift Package Index, find ApprovalTests, and copy the package URL. Then in Xcode, we select File, Add Packages, and paste the package URL. You can specify a version, or just use the latest branch. Click “Add Package”. Xcode will ask you where to add it. Be sure to select your test target. This adds ApprovalTests.Swift to your package dependencies.

Writing Test Code

Now you’re still using the regular XCTest framework. Normally, you would write an assertion like XCTAssertEqual to compare two values.

XCTAssertEqual("Hello", "Hello")

Here, we are checking that “Hello” is equal to “Hello”. If we run this, we can see the test passes.

ApprovalTests are very similar to this. But instead of XCTAssertEqual, you’re going to say try Approvals.verify. Here, let’s verify a string, but make it more complex.

try Approvals.verify("Hello world\nWelcome to Approval Tests")

And running this test will fail. But to make this more useful, I’ve installed a free diff tool called DiffMerge.

Running Tests for iOS

For iOS tests, we need one more step to communicate the test results from the iOS side to the Mac side. Inside of ApprovalTests.Swift, you’ll find a Python file called iOSApprovalsWatcher. In your terminal, go to your project directory. Drag iOSApprovalsWatcher.py to your terminal, and tell it where your tests are. It says, “Ready for iOS Approval Tests”.

Now when I run tests, it shows the received results, and how it differs from the approved results. The approved results are empty right now because we haven’t approved anything yet. The result received is Hello world, and on a new line, Welcome to Approval Tests.

Diff tool showing text on left, empty on right

The test will fail until these two things match. So once you see the results and you like them, then tell your diff tool to apply the changes from left to right.

Diff tool with left side copied to right

We close and save. And now when we run the test, it will pass.

If we ever change anything, like adding an exclamation point, and run it again, it will fail. The right side shows what we previously said was okay, and the left side shows what has changed. And the better your diff tool, the easier it is to see just where the difference is.

Diff tool highlighting exclamation mark

Now you can decide whether to revert the change, or approve the new result to say, this new version is now the correct version.

New testing tool for Swift: #ApprovalTests. When you run tests, it shows the received results, and how they differ from the approved results.

Click to Tweet

File Artifacts

One more thing to point out: If you look in your test folder, you will see these files, the approved result and the received result. They use the name of the test class, the name of the test method, and approved.txt or received.txt.

Finder showing DemoTests.swift, DemoTests.test_demo.approved.txt, and DemoTests.test_demo.received.txt

The received file is there because the last time we ran the test, it failed. If we re-approve to get a passing test, you’ll see that only the approved file exists. Check this approved file into your source control. You should never check in the received files. And for iOS tests, ApprovalTests also writes a command.sh script which it uses to launch your diff tool. Don’t check those command.sh files in, either.


So I hope that helps you get started with ApprovalTests. I plan to show you more details in other short videos.

I want to thank Llewellyn Falco and Matthew Carlson for starting this project. Llewellyn has created ApprovalTests on a variety of platforms, pairing with contributors from around the world. Matthew worked with Llewellyn to get the Swift version off the ground. Then I took the baton from Matthew, and have been pairing regularly with Llewellyn as he continues to discover interesting new ways to use Approval Testing.

If you have any questions about ApprovalTests.Swift, you can tweet it to me, @qcoding. And if you add hashtag #ApprovalTests, Llewellyn will also see your question. Thank you for watching.

What do you think so far? Any questions, or concerns? Feel free to ask in the comments below.

How to Verify Objects (and Simplify TDD) using ApprovalTests.Swift

Jon Reid

About the author

Programming was fun when I was a kid. But working in Silicon Valley, I saw poor code lead to fear, with real human costs. Looking for ways to make my life better, I learned about Extreme Programming, including unit testing, test-driven development (TDD), and refactoring. Programming became fun again! I've now been doing TDD in Apple environments for 20 years. I'm committed to software crafting as a discipline, hoping we can all reach greater effectiveness and joy.

{"email":"Email address invalid","url":"Website address invalid","required":"Required field missing"}

Never miss a good story!

Want to make sure you get notified when I release my next article or video? Then sign up here to subscribe to my newsletter. Plus, you’ll get access to the test-oriented code snippets I use every day!