Latest 6.0.3
Homepage https://github.com/uber/ios-snapshot-test-case
License MIT
Platforms ios 10.0, tvos 9.0, requires ARC
Frameworks XCTest, UIKit, Foundation, QuartzCore

iOSSnapshotTestCase (previously named FBSnapshotTestCase)

Build Status
CocoaPods Compatible
Carthage compatible

What it does

A "snapshot test case" takes a configured UIView or CALayer and uses the
renderInContext: method to get 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 with CocoaPods

  1. 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.

    Replace "Tests" with the name of your test project.

  2. 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.

iOSSnapshotTestCase

Creating a snapshot test

  1. Subclass FBSnapshotTestCase instead of XCTestCase.
  2. From within your test, use FBSnapshotVerifyView.
  3. Run the test once with self.recordMode = YES; in the test’s -setUp
    method. (This creates the reference images on disk.)
  4. 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 via FBSnapshotVerifyLayer.
  • usesDrawViewHierarchyInRect to handle cases like UIVisualEffect, 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 different OSs 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.)

In Xcode 5
and later new projects only offer application tests, but older projects will
have separate targets for the two types.

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 and Alan Zeino.

License

iOSSnapshotTestCase is MIT–licensed. See LICENSE.

Latest podspec

{
    "name": "iOSSnapshotTestCase",
    "module_name": "FBSnapshotTestCase",
    "version": "6.0.3",
    "summary": "Snapshot view unit tests for iOS",
    "description": "A "snapshot test case" takes a configured UIView or CALayernand uses the renderInContext: method to get an image snapshotnof its contents. It compares this snapshot to a "reference image"nstored in your source code repository and fails the test if thentwo images don't match.",
    "homepage": "https://github.com/uber/ios-snapshot-test-case",
    "license": "MIT",
    "authors": "Uber",
    "source": {
        "git": "https://github.com/uber/ios-snapshot-test-case.git",
        "tag": "6.0.3"
    },
    "platforms": {
        "ios": "10.0",
        "tvos": "9.0"
    },
    "requires_arc": true,
    "frameworks": [
        "XCTest",
        "UIKit",
        "Foundation",
        "QuartzCore"
    ],
    "pod_target_xcconfig": {
        "ENABLE_BITCODE": "NO"
    },
    "user_target_xcconfig": {
        "FRAMEWORK_SEARCH_PATHS": "$(PLATFORM_DIR)/Developer/Library/Frameworks"
    },
    "default_subspecs": "SwiftSupport",
    "subspecs": [
        {
            "name": "Core",
            "source_files": [
                "FBSnapshotTestCase/**/*.{h,m}",
                "FBSnapshotTestCase/*.{h,m}"
            ],
            "public_header_files": [
                "FBSnapshotTestCase/FBSnapshotTestCase.h",
                "FBSnapshotTestCase/FBSnapshotTestCasePlatform.h",
                "FBSnapshotTestCase/FBSnapshotTestController.h"
            ],
            "private_header_files": [
                "FBSnapshotTestCase/Categories/UIImage+Compare.h",
                "FBSnapshotTestCase/Categories/UIImage+Diff.h",
                "FBSnapshotTestCase/Categories/UIImage+Snapshot.h"
            ]
        },
        {
            "name": "SwiftSupport",
            "dependencies": {
                "iOSSnapshotTestCase/Core": []
            },
            "source_files": "FBSnapshotTestCase/**/*.swift"
        }
    ]
}

Pin It on Pinterest

Share This