From c17aa0bf7c82da2a583dd3c2e142cdb4a2f6eccf Mon Sep 17 00:00:00 2001 From: Alan Zeino Date: Tue, 28 Aug 2018 10:58:44 -0700 Subject: [PATCH] Support library test bundles (#13) * Update library to support library test bundles * Delete fb_strictKeyWindow, improve documentation --- FBSnapshotTestCase.xcodeproj/project.pbxproj | 12 --- .../xcshareddata/IDEWorkspaceChecks.plist | 8 ++ .../UIApplication+StrictKeyWindow.h | 19 ---- .../UIApplication+StrictKeyWindow.m | 26 ----- .../Categories/UIImage+Snapshot.m | 3 +- .../FBSnapshotTestCasePlatform.m | 3 +- README.md | 12 ++- docs/LibraryVsApplicationTestBundles.md | 99 +++++++++++++++++++ 8 files changed, 118 insertions(+), 64 deletions(-) create mode 100644 FBSnapshotTestCase.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist delete mode 100644 FBSnapshotTestCase/Categories/UIApplication+StrictKeyWindow.h delete mode 100644 FBSnapshotTestCase/Categories/UIApplication+StrictKeyWindow.m create mode 100644 docs/LibraryVsApplicationTestBundles.md diff --git a/FBSnapshotTestCase.xcodeproj/project.pbxproj b/FBSnapshotTestCase.xcodeproj/project.pbxproj index c87bf0b..4b682b5 100644 --- a/FBSnapshotTestCase.xcodeproj/project.pbxproj +++ b/FBSnapshotTestCase.xcodeproj/project.pbxproj @@ -19,11 +19,9 @@ 827137911C63ABE900354E42 /* UIImage+Compare.h in Headers */ = {isa = PBXBuildFile; fileRef = 133564101B59C3F500A4E4BF /* UIImage+Compare.h */; }; 827137921C63ABF000354E42 /* UIImage+Diff.h in Headers */ = {isa = PBXBuildFile; fileRef = 133564121B59C3F500A4E4BF /* UIImage+Diff.h */; }; 827137931C63ABF000354E42 /* UIImage+Snapshot.h in Headers */ = {isa = PBXBuildFile; fileRef = 133564141B59C3F500A4E4BF /* UIImage+Snapshot.h */; }; - 827137941C63ABF000354E42 /* UIApplication+StrictKeyWindow.h in Headers */ = {isa = PBXBuildFile; fileRef = BC45D51F1C2AEFCE007C72F3 /* UIApplication+StrictKeyWindow.h */; }; 827137951C63ABF400354E42 /* UIImage+Compare.m in Sources */ = {isa = PBXBuildFile; fileRef = 133564111B59C3F500A4E4BF /* UIImage+Compare.m */; }; 827137961C63ABF400354E42 /* UIImage+Diff.m in Sources */ = {isa = PBXBuildFile; fileRef = 133564131B59C3F500A4E4BF /* UIImage+Diff.m */; }; 827137971C63ABF400354E42 /* UIImage+Snapshot.m in Sources */ = {isa = PBXBuildFile; fileRef = 133564151B59C3F500A4E4BF /* UIImage+Snapshot.m */; }; - 827137981C63ABF400354E42 /* UIApplication+StrictKeyWindow.m in Sources */ = {isa = PBXBuildFile; fileRef = BC45D5201C2AEFCE007C72F3 /* UIApplication+StrictKeyWindow.m */; }; 827137991C63ABF900354E42 /* FBSnapshotTestCase.h in Headers */ = {isa = PBXBuildFile; fileRef = B31988201AB7849400B0A900 /* FBSnapshotTestCase.h */; settings = {ATTRIBUTES = (Public, ); }; }; 8271379A1C63ABF900354E42 /* FBSnapshotTestCasePlatform.h in Headers */ = {isa = PBXBuildFile; fileRef = 13CBB39B1AEE013900B6ADBA /* FBSnapshotTestCasePlatform.h */; settings = {ATTRIBUTES = (Public, ); }; }; 8271379B1C63ABF900354E42 /* FBSnapshotTestController.h in Headers */ = {isa = PBXBuildFile; fileRef = B31988221AB7849400B0A900 /* FBSnapshotTestController.h */; settings = {ATTRIBUTES = (Public, ); }; }; @@ -47,8 +45,6 @@ B32447DE1AB78B5E00B1D6FF /* square.png in Resources */ = {isa = PBXBuildFile; fileRef = B32447DB1AB78B5E00B1D6FF /* square.png */; }; B76C68291C6BD6D200586E5B /* rect.png in Resources */ = {isa = PBXBuildFile; fileRef = B76C68271C6BD68100586E5B /* rect.png */; }; B76C682A1C6BD6D500586E5B /* rect.png in Resources */ = {isa = PBXBuildFile; fileRef = B76C68271C6BD68100586E5B /* rect.png */; }; - BC45D5211C2AEFCE007C72F3 /* UIApplication+StrictKeyWindow.h in Headers */ = {isa = PBXBuildFile; fileRef = BC45D51F1C2AEFCE007C72F3 /* UIApplication+StrictKeyWindow.h */; }; - BC45D5221C2AEFCE007C72F3 /* UIApplication+StrictKeyWindow.m in Sources */ = {isa = PBXBuildFile; fileRef = BC45D5201C2AEFCE007C72F3 /* UIApplication+StrictKeyWindow.m */; }; E5C2CD621B1F399A00669887 /* square_with_pixel.png in Resources */ = {isa = PBXBuildFile; fileRef = E5C2CD611B1F399A00669887 /* square_with_pixel.png */; }; F0D698F51B204E120005CAC9 /* SwiftSupport.swift in Sources */ = {isa = PBXBuildFile; fileRef = F0D698F41B204E120005CAC9 /* SwiftSupport.swift */; }; /* End PBXBuildFile section */ @@ -94,8 +90,6 @@ B32447DA1AB78B5E00B1D6FF /* square-copy.png */ = {isa = PBXFileReference; lastKnownFileType = image.png; path = "square-copy.png"; sourceTree = ""; }; B32447DB1AB78B5E00B1D6FF /* square.png */ = {isa = PBXFileReference; lastKnownFileType = image.png; path = square.png; sourceTree = ""; }; B76C68271C6BD68100586E5B /* rect.png */ = {isa = PBXFileReference; lastKnownFileType = image.png; path = rect.png; sourceTree = ""; }; - BC45D51F1C2AEFCE007C72F3 /* UIApplication+StrictKeyWindow.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = "UIApplication+StrictKeyWindow.h"; sourceTree = ""; }; - BC45D5201C2AEFCE007C72F3 /* UIApplication+StrictKeyWindow.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = "UIApplication+StrictKeyWindow.m"; sourceTree = ""; }; E5C2CD611B1F399A00669887 /* square_with_pixel.png */ = {isa = PBXFileReference; lastKnownFileType = image.png; path = square_with_pixel.png; sourceTree = ""; }; F0D698F41B204E120005CAC9 /* SwiftSupport.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = SwiftSupport.swift; sourceTree = ""; }; /* End PBXFileReference section */ @@ -143,8 +137,6 @@ 133564131B59C3F500A4E4BF /* UIImage+Diff.m */, 133564141B59C3F500A4E4BF /* UIImage+Snapshot.h */, 133564151B59C3F500A4E4BF /* UIImage+Snapshot.m */, - BC45D51F1C2AEFCE007C72F3 /* UIApplication+StrictKeyWindow.h */, - BC45D5201C2AEFCE007C72F3 /* UIApplication+StrictKeyWindow.m */, ); path = Categories; sourceTree = ""; @@ -226,7 +218,6 @@ isa = PBXHeadersBuildPhase; buildActionMask = 2147483647; files = ( - 827137941C63ABF000354E42 /* UIApplication+StrictKeyWindow.h in Headers */, 8271379A1C63ABF900354E42 /* FBSnapshotTestCasePlatform.h in Headers */, 827137911C63ABE900354E42 /* UIImage+Compare.h in Headers */, 827137991C63ABF900354E42 /* FBSnapshotTestCase.h in Headers */, @@ -240,7 +231,6 @@ isa = PBXHeadersBuildPhase; buildActionMask = 2147483647; files = ( - BC45D5211C2AEFCE007C72F3 /* UIApplication+StrictKeyWindow.h in Headers */, B31988281AB7849400B0A900 /* FBSnapshotTestCase.h in Headers */, 13CBB39D1AEE013900B6ADBA /* FBSnapshotTestCasePlatform.h in Headers */, B319882A1AB7849400B0A900 /* FBSnapshotTestController.h in Headers */, @@ -420,7 +410,6 @@ files = ( 827137961C63ABF400354E42 /* UIImage+Diff.m in Sources */, 8271379E1C63ABFD00354E42 /* FBSnapshotTestController.m in Sources */, - 827137981C63ABF400354E42 /* UIApplication+StrictKeyWindow.m in Sources */, 8271379D1C63ABFD00354E42 /* FBSnapshotTestCasePlatform.m in Sources */, 8271379C1C63ABFD00354E42 /* FBSnapshotTestCase.m in Sources */, 827137951C63ABF400354E42 /* UIImage+Compare.m in Sources */, @@ -442,7 +431,6 @@ buildActionMask = 2147483647; files = ( 133564171B59C3F500A4E4BF /* UIImage+Compare.m in Sources */, - BC45D5221C2AEFCE007C72F3 /* UIApplication+StrictKeyWindow.m in Sources */, B31988291AB7849400B0A900 /* FBSnapshotTestCase.m in Sources */, 133564191B59C3F500A4E4BF /* UIImage+Diff.m in Sources */, 1335641B1B59C3F500A4E4BF /* UIImage+Snapshot.m in Sources */, diff --git a/FBSnapshotTestCase.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist b/FBSnapshotTestCase.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist new file mode 100644 index 0000000..18d9810 --- /dev/null +++ b/FBSnapshotTestCase.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist @@ -0,0 +1,8 @@ + + + + + IDEDidComputeMac32BitWarning + + + diff --git a/FBSnapshotTestCase/Categories/UIApplication+StrictKeyWindow.h b/FBSnapshotTestCase/Categories/UIApplication+StrictKeyWindow.h deleted file mode 100644 index 4bfe1a9..0000000 --- a/FBSnapshotTestCase/Categories/UIApplication+StrictKeyWindow.h +++ /dev/null @@ -1,19 +0,0 @@ -/* - * Copyright (c) 2017-2018, Uber Technologies, Inc. - * Copyright (c) 2015-2018, Facebook, Inc. - * - * This source code is licensed under the MIT license found in the - * LICENSE file in the root directory of this source tree. - * - */ - -#import - -@interface UIApplication (StrictKeyWindow) - -/** - @return The receiver's @c keyWindow. Raises an assertion if @c nil. - */ -- (UIWindow *)fb_strictKeyWindow; - -@end diff --git a/FBSnapshotTestCase/Categories/UIApplication+StrictKeyWindow.m b/FBSnapshotTestCase/Categories/UIApplication+StrictKeyWindow.m deleted file mode 100644 index 23ced91..0000000 --- a/FBSnapshotTestCase/Categories/UIApplication+StrictKeyWindow.m +++ /dev/null @@ -1,26 +0,0 @@ -/* - * Copyright (c) 2017-2018, Uber Technologies, Inc. - * Copyright (c) 2015-2018, Facebook, Inc. - * - * This source code is licensed under the MIT license found in the - * LICENSE file in the root directory of this source tree. - * - */ - -#import - -@implementation UIApplication (StrictKeyWindow) - -- (UIWindow *)fb_strictKeyWindow -{ - UIWindow *keyWindow = [UIApplication sharedApplication].keyWindow; - if (!keyWindow) { - [NSException raise:@"FBSnapshotTestCaseNilKeyWindowException" - format:@"Snapshot tests must be hosted by an application with a key window. Please ensure your test" - " host sets up a key window at launch (either via storyboards or programmatically) and doesn't" - " do anything to remove it while snapshot tests are running."]; - } - return keyWindow; -} - -@end diff --git a/FBSnapshotTestCase/Categories/UIImage+Snapshot.m b/FBSnapshotTestCase/Categories/UIImage+Snapshot.m index 2553e28..1457ca5 100644 --- a/FBSnapshotTestCase/Categories/UIImage+Snapshot.m +++ b/FBSnapshotTestCase/Categories/UIImage+Snapshot.m @@ -8,7 +8,6 @@ */ #import -#import @implementation UIImage (Snapshot) @@ -43,7 +42,7 @@ + (UIImage *)fb_imageForView:(UIView *)view UIWindow *window = [view isKindOfClass:[UIWindow class]] ? (UIWindow *)view : view.window; BOOL removeFromSuperview = NO; if (!window) { - window = [[UIApplication sharedApplication] fb_strictKeyWindow]; + window = [[UIApplication sharedApplication] keyWindow]; } if (!view.window && view != window) { diff --git a/FBSnapshotTestCase/FBSnapshotTestCasePlatform.m b/FBSnapshotTestCase/FBSnapshotTestCasePlatform.m index 5ff60c2..77909ba 100644 --- a/FBSnapshotTestCase/FBSnapshotTestCasePlatform.m +++ b/FBSnapshotTestCase/FBSnapshotTestCasePlatform.m @@ -8,7 +8,6 @@ */ #import -#import #import BOOL FBSnapshotTestCaseIs64Bit(void) @@ -34,7 +33,7 @@ BOOL FBSnapshotTestCaseIs64Bit(void) NSString *FBDeviceAgnosticNormalizedFileName(NSString *fileName) { UIDevice *device = [UIDevice currentDevice]; - UIWindow *keyWindow = [[UIApplication sharedApplication] fb_strictKeyWindow]; + UIWindow *keyWindow = [[UIApplication sharedApplication] keyWindow]; CGSize screenSize = keyWindow.bounds.size; NSString *os = device.systemVersion; diff --git a/README.md b/README.md index bf8be5d..a5c948c 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ iOSSnapshotTestCase (previously named FBSnapshotTestCase) ====================== -[![Build Status](https://travis-ci.org/uber/ios-snapshot-test-case.svg)](https://travis-ci.org/uber/ios-snapshot-test-case) +[![Build Status](https://travis-ci.org/uber/ios-snapshot-test-case.svg)](https://travis-ci.org/uber/ios-snapshot-test-case) [![CocoaPods Compatible](https://img.shields.io/cocoapods/v/iOSSnapshotTestCase.svg)](https://img.shields.io/cocoapods/v/iOSSnapshotTestCase.svg) What it does @@ -82,11 +82,17 @@ Features Notes ----- -Your unit test must be an "application test", not a "logic test." (That is, it -must be run within the Simulator so that it has access to UIKit.) In Xcode 5 +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](docs/LibraryVsApplicationTestBundles.md). + Authors ------- diff --git a/docs/LibraryVsApplicationTestBundles.md b/docs/LibraryVsApplicationTestBundles.md new file mode 100644 index 0000000..884119f --- /dev/null +++ b/docs/LibraryVsApplicationTestBundles.md @@ -0,0 +1,99 @@ +# Library vs Application Test Bundles + +* Authors: [Alan Zeino](https://github.com/alanzeino) + +## Introduction + +Developers writing unit tests for iOS using XCTest typically use Application Test Bundles without much consideration as to _why_ their tests need to be inside an Application Test Bundle, as opposed to a Library Test Bundle. This document describes what you can and can't do with both, and why you might want to use a Library Test Bundle. + +Library Test Bundles were once called _Logic_ Test Bundles in Apple's nomenclature. In the context of this document, both Library and Logic are interchangeable. + +### Application tests + +Unit tests that test parts of an application (such as UIViewControllers, UIWindows, UIViews) should typically be part of an Application test bundle. An Application test bundle requires a Test Host (an application to run your tests in) and at test run time, a simulator too. The attached Test Host provides access to some iOS APIs that only work inside Application test bundles. In our experience, we've seen these: + +* `-[UIControl sendActionsForControlEvents:]` — This API is commonly used to trigger actions at runtime and sometimes you might want to use it inside a test to trigger a particular code path which is ordinarily run when a user performs an action. While it does not work inside a Library test bundle, we've written our own version for unit tests (see 'Code Snippets' below) that works well for this need. +* `UIAppearance` — Most `UIAppearance` APIs break when there is no test host present. +* `UIWindow` — You cannot make a `UIWindow` you created during your test the 'key window' because `makeKeyAndVisible` crashes at test run time. One workaround is to instead set `hidden` to `false` on the `UIWindow` instance you created. However there still won't be a 'key window' so if you have code that adds a `UIView` as a subview of the `keyWindow` then that will break. +* Keychain — Keychain operations require an application test bundle. + +### Library tests +Unit tests that test parts of a framework or library should be part of a Library test bundle. This does not strictly require a Test Host. Not using a Test Host has some advantages: + +* No need to install anything, which makes running your tests faster and reduces the likelihood of Simulator instability +* The Test Host application will start an application lifecycle, which is state that can cause instability in your tests +* Only one host application can run at the same time in a Simulator, so tests with a Test Host cannot parallelize on one simulator. The `xctest` stub process spawned without a Test Hist isn’t a full iOS application, so multiple can run in parallel sharing a single simulator. + +If you are using [Buck](https://buckbuild.com/), removing the `test_host_app` option for `apple_test()` rules will allow Buck and `xctool` to run your test bundles in parallel. + +### Code Examples +#### ub_sendActionsForControlEvents: +This code snippet shows how you might replace `UIControl`'s `sendActionForControlEvents:` in a test that is inside a library test bundle. Since it doesn't have universal application we haven't included it directly in the project. If you decide to use this category, make sure it can only be seen inside unit tests and not all of your code. + +``` +/** + Copyright (c) 2018 Uber Technologies, Inc. + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. + */ + +#import + +@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 + +/** + UIControlEvents has options in the range 0-8, 12-13, 16-19. 9-11 are reserved for future UIControlEventTouch* options. 14-15 are reserved for other options. If new options are added after 19, this const will need to be updated. + */ +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 *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 + +``` \ No newline at end of file