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.
ApprovalTests.Swift is compatible with the XCTest testing framework.
We'll start by writing a simple unit test to verify a list of names. But instead of using XCTest's XCTAssertEqual
function, we'll use Approvals.verifyAll
:
class SampleArrayTests: XCTestCase {
func testList() throws {
var names = ["Llewellyn", "James", "Dan", "Jason", "Katrina"]
names.sort()
try Approvals.verifyAll(names, label: "")
}
The verifyAll()
function performs a test assertion for a list of items. Unlike a normal assertion, it doesn’t specify an expected list. Instead, this will produce a “received” file matching the name of your test suite and test case. In this example, it will write a file SampleArrayTests.testList.received.txt
:
[0] = Dan
[1] = James
[2] = Jason
[3] = Katrina
[4] = Llewellyn
It also opens two files in a diff editor—the “received” file, and the “approved” file.
To approve the results, tell the diff editor to apply changes from the left side to the right side:
Most of the time, you’ll use one of the supported diff tools to examine and approve the result. If you don’t have any of these diff tools, you can rename the received file to SampleArrayTests.testList.approved.txt
and the test will now pass.
The best way to get started is download and open one of the starter projects:
These are standard projects and can be imported into any editor or IDE.
They also all have CI with Github actions.
They come ready with:
.gitignore
to exclude approval artifactsApprovalTests.Swift comes with useful verifiers:
Approvals.verify
— verify object or dictionaryApprovals.verifyAll
— verify array of items (or use array as inputs)Approvals.verifyAsJSON
— verify Encodable object converted to JSONApprovals.verifyQuery
— verify query, also showing query results on failureApprovals.verifySequence
— verify sequence of changing valuesApprovalTests.Swift runs out-of-the-box for macOS tests. But for iOS tests, you need a separate process running on your Mac to watch for diffs. Run iOSApprovalsWatcher.py from your command line, giving it the path to your test directory.
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.*
If you have iOS tests, you should also add command.sh
to your .gitignore
. (They are scripts written by the iOS side for the file monitor to execute from the macOS side.) So for iOS testing, make sure to exclude:
*.received.*
command.sh
See an example package manifest here
Get the following dependency:
dependencies: [
.package(
url: "https://github.com/approvals/ApprovalTests.Swift",
branch: "master"
),
],
Then add it to your test target:
.testTarget(
name: "ApprovalTests.Swift.StarterProject.MacOSTests",
dependencies: [
"ApprovalTests.Swift.StarterProject.MacOS",
"ApprovalTests.Swift",
],
Add the following to your Cartfile:
github "approvals/ApprovalTests.Swift" ~> 2.0
Then drag the the built framework from the appropriate Carthage/Build directory into your project, but with “Copy items into destination group’s folder” disabled.
If you want to add ApprovalTests.Swift using Cocoapods then add the following dependency to your Podfile. Most people will want ApprovalTests.Swift in their test targets, and not include any pods from their main targets:
target 'MyTests' do
inherit! :search_paths
use_frameworks!
pod 'ApprovalTests_Swift', '~> 2.0'
end
Ask Llewellyn Falco @LlewellynFalco or Jon Reid @qcoding on Twitter.
Find some extra documentation here.
You can also watch a series of short videos about using ApprovalTests in .Net on YouTube.
Prefer learning by listening? Then you might enjoy the following podcasts:
link |
Stars: 83 |
Last commit: 33 weeks ago |
try Approvals.verify(CGRect(x: 5, y: 10, width: 100, height: 200))
will produce these changes in your .approved.
files
- CGRect: (5.0, 10.0, 100.0, 200.0)
+ (5.0, 10.0, 100.0, 200.0)
verifyAll
improvements:
header
to print above the array.verifyAll
takes a labeler
closure to format each line.
For example, here's a way to make lists without indices: try Approvals.verifyAll(header: "grocery list", groceries) { $0 }
Approvals now offers a Verifiable interface that understands approvals.
Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics