iOSSnapshotTestCase

When writing unit tests for iOS, you must decide whether to use an Application Test Bundle or a Library Test Bundle (formerly known as Logic Test Bundles). The choice depends on the components you are testing and your requirements for test execution speed and parallelism.

Application Test Bundles

Use these for testing application-level components like UIViewControllers, UIWindows, and UIViews.

Requirements & Limitations:

• Requires a Test Host: An application must be running to host the tests.
• Requires a Simulator: Tests run within a simulator environment.
• API Access: Provides access to iOS APIs that are unavailable in Library bundles, such as:
  • -[UIControl sendActionsForControlEvents:] (standard implementation).
  • UIAppearance APIs.
  • Keychain operations.
• Limitations:
  • UIWindow.makeKeyAndVisible will crash at runtime. A workaround is setting hidden = false, but there will still be no true 'key window'.
  • Cannot easily parallelize tests on a single simulator because only one host application can run at a time.

Library Test Bundles

Use these for testing frameworks or libraries. These do not strictly require a Test Host.

Advantages:

• Speed: Faster execution as there is no need to install or launch a host application.
• Stability: Avoids the application lifecycle state of a host app, which can cause test instability.
• Parallelism: Multiple xctest stub processes can run in parallel on a single simulator because they are not full iOS applications.

Note for Buck users: Removing the test_host_app option for apple_test() rules allows buck and xctool to run your test bundles in parallel.

In a Library Test Bundle (without a Test Host), the standard UIControl method sendActionsForControlEvents: does not work. To trigger code paths that normally run when a user interacts with a control, you must use a custom implementation that manually iterates through targets and actions.

Objective-C Implementation

You can use the following ub_sendActionsForControlEvents: method. Warning: Ensure this category is only visible within your unit tests to avoid polluting your production codebase.

Swift Implementation

If you are using Swift, you can use the testSendActions(for:toTarget:) extension.

Note: If any of the targets in allTargets do not subclass NSObject, the testSendActions(for:) method will crash. In such cases, call testSendActions(for:toTarget:) directly for each specific target.

import UIKit

public extension UIControl {
    /// Note: if any of the targets in `allTargets` do not subclass NSObject, this will crash.
    /// You should directly call `testSendActions(for:toTarget:)` for each target instead.
    ///
    /// - Parameter controlEvent: The control events to send actions.
    func testSendActions(
        for controlEvent: UIControl.Event
    ) {
        for target in allTargets {
            testSendActions(for: controlEvent, toTarget: target as AnyObject)
        }
    }

    /// Send an action for a given control event to a target.
    /// - Parameters:
    ///   - controlEvent: A control event to send.
    ///   - target: The target to send it to.
    func testSendActions(
        for controlEvent: UIControl.Event,
        toTarget target: AnyObject
    ) {
        guard let actions = actions(forTarget: target, forControlEvent: controlEvent) else {
            return
        }

        for action in actions {
            _ = target.perform(Selector(action), with: self)
        }
    }
}

To release a new version of iOSSnapshotTestCase, follow these steps in order:

1. Prepare Metadata: Update CHANGELOG.md and the version number in iOSSnapshotTestCase.podspec.
2. Validate CocoaPods: Run pod lib lint from the repository root.
3. Verify Demo (CocoaPods): Run pod install inside demos/FBSnapshotTestCaseDemo/.
4. Commit and Tag: Commit all changes to the master branch and create a git tag using the version number (e.g., git tag 0.0.1).
5. Push Tags: Push the tag to the remote repository using git push --tags.
6. Push to CocoaPods Trunk: Execute pod trunk push iOSSnapshotTestCase.podspec.
7. Build Carthage Frameworks:
   • Navigate to demos/iOSSnapshotTestCaseCarthageDemo/.
   • Run carthage update --use-xcframeworks.
   • Run carthage build --no-skip-current --use-xcframeworks.
   • Note: iOSSnapshotTestCaseCarthageDemo/Cartfile.resolved can be committed and pushed even if it changed without a new version.
8. Archive Framework:
   • Return to the repository root.
   • Run carthage build --archive --configuration Debug --use-xcframeworks.
9. Finalize Release: Upload the resulting FBSnapshotTestCase.framework.zip to the corresponding tagged release on GitHub.

A custom implementation for UIControl to be used in Library Test Bundles where the standard sendActionsForControlEvents: is unavailable. It mimics the behavior by finding all targets and actions associated with a specific UIControlEvents bitmask and invoking them manually.

#import <UIKit/UIKit.h>

@interface UIControl (SendActions)

/**
 In library test bundles with no test host, the default sendActionsForControlEvents: does not work.

 This replacement mimics the same idea of that method by finding all the targets associated with the control, finding all the actions on that target for the given control event, and invoking those actions on those targets.

 @param controlEvents A bitmask whose set flags specify the control events for which action messages are sent.
 */
- (void)ub_sendActionsForControlEvents:(UIControlEvents)controlEvents;

@end

static NSUInteger const UIControlEventsMaxOffset = 19;

@implementation UIControl (UberTesting)

- (void)ub_sendActionsForControlEvents:(UIControlEvents)controlEvents
{
  for (NSUInteger i = 0; i < UIControlEventsMaxOffset; i++) {
    UIControlEvents controlEvent = 1 << i;
    if (controlEvents & controlEvent) {
      for (id target in self.allTargets) {
        NSArray<NSString *> *targetActions = [self actionsForTarget:target forControlEvent:controlEvent];
        for (NSString *action in targetActions) {
          SEL selector = NSSelectorFromString(action);
          IMP imp = [target methodForSelector:selector];
          void (*func)(id, SEL, id) = (void *)imp;
          func(target, selector, self);
        }
      }
    }
  }
}

@end