Top Related Projects
Snapshot view unit tests for iOS
📸 Delightful Swift snapshot testing.
Simple BDD for iOS
Common Xcode configuration files/settings.
Quick Overview
iOS Snapshot Test Case is a library for snapshot testing iOS applications. It allows developers to capture the appearance of UI components or entire screens as images and compare them against reference images to detect visual regressions.
Pros
- Easy integration with existing XCTest framework
- Supports both UIKit and SwiftUI
- Provides clear visual diffs when tests fail
- Can be used for both unit and UI testing
Cons
- May produce false positives due to minor rendering differences across devices
- Requires manual review of visual changes
- Can increase test suite run time, especially for large applications
- Maintenance of reference images can be challenging as the app evolves
Code Examples
- Basic snapshot test:
func testMyView() {
let view = MyView(frame: CGRect(x: 0, y: 0, width: 320, height: 100))
FBSnapshotVerifyView(view)
}
- Snapshot test with custom identifier:
func testMyViewWithCustomIdentifier() {
let view = MyView(frame: CGRect(x: 0, y: 0, width: 320, height: 100))
FBSnapshotVerifyView(view, identifier: "CustomIdentifier")
}
- Snapshot test with device agnostic naming:
func testMyViewDeviceAgnostic() {
let view = MyView(frame: CGRect(x: 0, y: 0, width: 320, height: 100))
FBSnapshotVerifyView(view, isDeviceAgnostic: true)
}
Getting Started
-
Add the following to your Podfile:
pod 'iOSSnapshotTestCase'
-
Run
pod install
in your terminal. -
Import the framework in your test file:
import FBSnapshotTestCase
-
Subclass
FBSnapshotTestCase
instead ofXCTestCase
:class MyViewTests: FBSnapshotTestCase { override func setUp() { super.setUp() self.recordMode = false } func testMyView() { let view = MyView(frame: CGRect(x: 0, y: 0, width: 320, height: 100)) FBSnapshotVerifyView(view) } }
-
Run your tests. The first time, set
recordMode = true
to generate reference images. Then set it back tofalse
for subsequent test runs.
Competitor Comparisons
Snapshot view unit tests for iOS
Pros of ios-snapshot-test-case (Facebook)
- Established and widely adopted in the iOS development community
- Extensive documentation and community support
- Integration with Facebook's other iOS testing tools
Cons of ios-snapshot-test-case (Facebook)
- No longer actively maintained (archived repository)
- May lack support for newer iOS versions and features
- Potential compatibility issues with modern development environments
Code Comparison
ios-snapshot-test-case (Facebook):
FBSnapshotVerifyView(view)
FBSnapshotVerifyLayer(layer)
FBSnapshotVerifyViewController(viewController)
ios-snapshot-test-case (Uber):
verifyView(view)
verifyLayer(layer)
verifyViewController(viewController)
The Uber version simplifies the API by removing the "FBSnapshot" prefix, making it more concise and easier to use. Both libraries provide similar functionality, but Uber's version is actively maintained and updated to support newer iOS versions and development practices.
While the Facebook version has a larger user base and more extensive documentation, the Uber fork offers ongoing support and improvements. Developers looking for a more up-to-date solution may prefer the Uber version, while those working on legacy projects or requiring specific Facebook integrations might still opt for the original Facebook library.
📸 Delightful Swift snapshot testing.
Pros of swift-snapshot-testing
- More flexible and extensible, supporting various types of snapshots (e.g., UIImage, String, Data)
- Better Swift integration with a more idiomatic API
- Actively maintained with regular updates and improvements
Cons of swift-snapshot-testing
- Steeper learning curve due to its more advanced features
- May require more setup and configuration for complex scenarios
- Potentially slower test execution for large test suites
Code Comparison
ios-snapshot-test-case:
FBSnapshotVerifyView(view)
swift-snapshot-testing:
assertSnapshot(matching: view, as: .image)
Key Differences
- API Design: swift-snapshot-testing offers a more Swift-friendly API with better type safety and composability.
- Snapshot Types: swift-snapshot-testing supports a wider range of snapshot types, including non-visual data.
- Customization: swift-snapshot-testing provides more options for customizing snapshot behavior and appearance.
- Community Support: While ios-snapshot-test-case has been around longer, swift-snapshot-testing has gained popularity and active development in recent years.
- Integration: swift-snapshot-testing integrates more seamlessly with modern Swift testing practices and frameworks.
Both libraries serve the purpose of snapshot testing, but swift-snapshot-testing offers more flexibility and a more modern approach, while ios-snapshot-test-case may be simpler for basic use cases and has a longer history in the iOS development community.
Simple BDD for iOS
Pros of Kiwi
- Provides a full BDD testing framework with expressive syntax
- Supports both Objective-C and Swift
- Offers powerful mocking and stubbing capabilities
Cons of Kiwi
- Steeper learning curve compared to snapshot testing
- May require more setup and configuration
- Less suitable for UI-focused tests
Code Comparison
Kiwi (BDD-style test):
describe(@"Calculator", ^{
it(@"should add two numbers", ^{
Calculator *calc = [[Calculator alloc] init];
[[theValue([calc add:2 to:3]) should] equal:theValue(5)];
});
});
ios-snapshot-test-case (Snapshot test):
- (void)testMyView {
UIView *view = [self setupView];
FBSnapshotVerifyView(view, nil);
}
Kiwi offers a more expressive, behavior-driven approach to testing, while ios-snapshot-test-case focuses on visual regression testing through snapshots. Kiwi is better suited for unit and integration tests, whereas ios-snapshot-test-case excels in UI testing and catching visual regressions. The choice between the two depends on the specific testing needs of the project.
Common Xcode configuration files/settings.
Pros of xcconfigs
- Focuses on Xcode configuration management, providing a set of reusable and customizable .xcconfig files
- Helps standardize and simplify project settings across multiple targets and projects
- Promotes better organization and maintainability of Xcode project configurations
Cons of xcconfigs
- Limited scope compared to ios-snapshot-test-case, as it only deals with configuration files
- Requires manual integration into existing projects, which may be time-consuming for large codebases
- Less active community and fewer contributors compared to ios-snapshot-test-case
Code Comparison
xcconfigs example:
SWIFT_VERSION = 5.0
IPHONEOS_DEPLOYMENT_TARGET = 13.0
ENABLE_BITCODE = NO
ios-snapshot-test-case example:
FBSnapshotVerifyView(view)
FBSnapshotVerifyLayer(layer)
FBSnapshotVerifyViewController(viewController)
While xcconfigs focuses on configuration management, ios-snapshot-test-case provides snapshot testing functionality for iOS applications. The code examples demonstrate the different purposes of these repositories, with xcconfigs offering configuration settings and ios-snapshot-test-case providing testing methods for UI components.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
iOSSnapshotTestCase (previously FBSnapshotTestCase)
What it does
A "snapshot test case" takes a configured UIView
or CALayer
and uses the necessary UIKit or Core Animation methods to generate an image snapshot of its contents. It
compares this snapshot to a "reference image" stored in your source code
repository and fails the test if the two images don't match.
Why?
We write a lot of UI code. There are a lot of edge
cases that we want to handle correctly when you are creating UIView
instances:
- What if there is more text than can fit in the space available?
- What if an image doesn't match the size of an image view?
- What should the highlighted state look like?
It's straightforward to test logic code, but less obvious how you should test views. You can do a lot of rectangle asserts, but these are hard to understand or visualize. Looking at an image diff shows you exactly what changed and how it will look to users.
iOSSnapshotTestCase
was developed to make snapshot tests easy.
Installation
Step 1: Add iOSSnapshotTestCase to your project
CocoaPods
Add the following lines to your Podfile:
target "Tests" do
use_frameworks!
pod 'iOSSnapshotTestCase'
end
If your test target is Objective-C only use iOSSnapshotTestCase/Core
instead, which doesn't contain Swift support.
Carthage
Add the following line to your Cartfile:
github "uber/ios-snapshot-test-case" ~> 8.0.0
Swift Package Manager
Add the following line to your Package.swift
:
dependencies: [
.package(url: "https://github.com/uber/ios-snapshot-test-case.git", from: "8.0.0"),
],
...or integrate with Xcode via File -> Swift Packages -> Add Package Dependency...
using the URL of the repository. We recommend using "Up to Next Major" with the Version field, as we use Semantic Versioning and only put breaking changes in major versions.
Step 2: Setup Test Scheme
Replace "Tests" with the name of your test project.
- There are three ways of setting reference image directories, the recommended one is to define
FB_REFERENCE_IMAGE_DIR
in your scheme. This should point to the directory where you want reference images to be stored. We normally use this:
Name | Value |
---|---|
FB_REFERENCE_IMAGE_DIR | $(SOURCE_ROOT)/$(PROJECT_NAME)Tests/ReferenceImages |
IMAGE_DIFF_DIR | $(SOURCE_ROOT)/$(PROJECT_NAME)Tests/FailureDiffs |
Define the IMAGE_DIFF_DIR
to the directory where you want to store diffs of failed snapshots. There are also three ways to set failed image diff directories.
Creating a snapshot test
- Subclass
FBSnapshotTestCase
instead ofXCTestCase
. - From within your test, use
FBSnapshotVerifyView
. - Run the test once with
self.recordMode = YES;
in the test's-setUp
method. (This creates the reference images on disk.) - Remove the line enabling record mode and run the test.
Features
- Automatically names reference images on disk according to test class and selector.
- Prints a descriptive error message to the console on failure. (Bonus: failure message includes a one-line command to see an image diff if you have Kaleidoscope installed.)
- Supply an optional "identifier" if you want to perform multiple snapshots in a single test method.
- Support for
CALayer
viaFBSnapshotVerifyLayer
. usesDrawViewHierarchyInRect
to handle cases likeUIVisualEffect
,UIAppearance
and Size Classes.fileNameOptions
to control appending the device model (iPhone
,iPad
,iPod Touch
, etc), OS version, screen size and screen scale to the images (allowing to have multiple tests for the same «snapshot» for differentOS
s and devices).
Notes
Your unit tests should be inside an "application" bundle, not a "logic/library" test bundle. (That is, it should be run within the Simulator so that it has access to UIKit.)
However, if you are writing snapshot tests inside a library/framework, you might want to keep your test bundle as a library test bundle without a Test Host.
Read more on this here.
Authors
iOSSnapshotTestCase
was written at Facebook by
Jonathan Dann with significant contributions by
Todd Krabach.
Today it is maintained by Uber.
License
iOSSnapshotTestCase
is MITâlicensed. See LICENSE
.
Top Related Projects
Snapshot view unit tests for iOS
📸 Delightful Swift snapshot testing.
Simple BDD for iOS
Common Xcode configuration files/settings.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot