I’m Jon Reid, and I want to introduce you to a new testing tool for Swift called ApprovalTests.
For more:
Improve your test writing “Flow.”
Sign up to get my test-oriented code snippets.
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.
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.
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.
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.
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.
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.
Questions?
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.
All Articles in this series
