matrixprojects.net

Defining Multiple Accessibility Actions in SwiftUI

Mon, 12 Apr 2021 17:00:00 +0000

Update (2022): iOS 16 now supports this via the new accessibilityActions modifier. The contents of this post can be used as a reference for how this could be supported on older OS versions.

Overview

I’ve been experimenting with SwiftUI in a side project to get a chance to learn it by practice. An interesting pickle I found myself running into recently was how to go about defining multiple accessibility actions.

Background
- Accessibility Actions
- Defining Accessibility Actions
The issue
Possible solutions
- Attempt 1: Iteration
- Attempt 2: Flattening accessibility elements
Conclusion
Links
Update: Avoiding type erasure
Update: iOS 16 API

Background

Accessibility Actions

Making Apps More Accessible With Custom Actions is well worth a watch to learn more about accessibility actions. In summary they can be thought of as shortcuts to perform custom actions within an application that can be invoked from various assistive technologies like Voice Over and Switch Control.

For example, in the Reminders app each reminder item has dedicated accessibility actions to mark it as complete, delete it or view its details. This makes those actions easier to find and perform quickly when using assistive technologies.

Defining Accessibility Actions

In SwiftUI accessibility actions can be defined on views via the accessibilityAction modifier.

struct ContentView: View {
    var body: some View {
        Text("Custom View")
            .padding()
            .border(Color.red)
            .accessibilityAction(named: "Custom Action") {
                print(">> Custom Action")
            }
    }
}

Additional actions can be defined by leveraging the same modifier multiple times with different parameters.

struct ContentView: View {
    var body: some View {
        Text("Custom View")
            .padding()
            .border(Color.red)
            .accessibilityAction(named: "First Action") {
                print(">> First Action")
            }
            .accessibilityAction(named: "Second Action") {
                print(">> Second Action")
            }
    }
}

We can verify the actions are working via the accessibility inspector - hovering over our custom view should reveal we do indeed now have two custom actions, and performing them triggers the corresponding action.

The issue

The current API works great when we have a list of static actions we know upfront, however it becomes challenging if we want this list of actions to be dynamically defined.

For example, if we are driving our view from a view model, we may want to also drive the accessibility actions from there too via a published array property.

final class ViewModel: ObservableObject {
    struct CustomAction: Identifiable {
        var id: String
        var name: String
    }

    @Published var title = "Custom View"
    @Published var actions: [CustomAction] = [
        CustomAction(id: "action_1", name: "Action One"),
        CustomAction(id: "action_2", name: "Action Two"),
    ]

    func perform(action: CustomAction) {
        // ...
    }
}

Seeing the API is defined via modifiers for individual actions, it makes defining all our accessibility actions from an array a bit awkward. Based on my limited experience with SwiftUI, I haven’t found a neat way to apply a modifier multiple times given an array of parameters.

We can’t use a regular for loop within a view builder to iterate over the list of actions as that is invalid.

struct ContentView: View {
    @StateObject var viewModel = ViewModel()
    var body: some View {
        Text(viewModel.title)
            .padding()
            .border(Color.red)
            // !! invalid syntax
            // for action in viewModel.actions {
	          //  .accessibilityAction(named: action.name) {
	          //      viewModel.perform(action: action)
	          //  }
            // }
    }
}

In SwiftUI, there’s a dedicated ForEach view that is typically used in cases where a loop is needed, however this only works at the view level rather than the modifier level. The following example will yield multiple custom views, one for each custom accessibility action rather than an individual view with multiple accessibility actions.

struct ContentView: View {
    @StateObject var viewModel = ViewModel()
    var body: some View {
        ForEach(viewModel.actions) { action in
            Text(viewModel.title)
                .padding()
                .border(Color.red)
                .accessibilityAction(named: action.name) {
                    viewModel.perform(action: action)
                }
        }
    }
}

Possible solutions

Attempt 1: Iteration

My first thought was, view builders are nice to use, but what’s stopping us from falling back to regular functions where we can leverage a for loop?

func addAccessibilityActions(from viewModel: ViewModel, to view: View) -> some View {
    var modifiedView = view
    for action in viewModel.actions {
        modifiedView = modifiedView
            .accessibilityAction(named: action.name) {
                viewModel.perform(action: action)
            }
    }
    return modifiedView
}

The first complication we face here is that View is a protocol with an associated type …

Protocol 'View' can only be used as a generic constraint because it has Self or associated type requirements

Which means we can’t use it like a regular type, rather it can only be used in a generic context.

func addAccessibilityActions<V: View>(from viewModel: ViewModel, to view: V) -> some View {
    var modifiedView = view
    for action in viewModel.actions {
        modifiedView = modifiedView
            .accessibilityAction(named: action.name) {
                viewModel.perform(action: action)
            }
    }
    return modifiedView
}

The next complication we face now we’re dealing with generics, the original view type is not the same type as the view with the modifier applied, as such we can’t simply assign it to a local variable.

Cannot assign value of type ‘ModifiedContent<V, AccessibilityAttachmentModifier>’ to type ‘V’

To get this working in this fashion, we sadly have to resort to type erasure by leveraging AnyView.

func addAccessibilityActions<V: View>(from viewModel: ViewModel, to view: V) -> some View {
    var modifiedView = AnyView(view)
    for action in viewModel.actions {
        modifiedView = AnyView(
            modifiedView.accessibilityAction(named: action.name) {
                viewModel.perform(action: action)
            }
        )
    }
    return modifiedView
}

This can then be used by our custom view:

var body: some View {
    addAccessibilityActions(
        from: viewModel,
        to: Text(viewModel.title)
            .padding()
            .border(Color.red)
    )
}

While not the most elegant it does the job. The code ergonomics can be improved slightly by leveraging an intermediate type and a custom modifier.

struct AccessibilityAction {
    var name: LocalizedStringKey
    var handler: () -> Void
}

struct AccessibilityActionsModifier: ViewModifier {
    let actions: [AccessibilityAction]

    func body(content: Content) -> some View {
        var modifiedView = AnyView(content)
        for action in actions {
            modifiedView = AnyView(
                modifiedView.accessibilityAction(named: action.name, action.handler)
            )
        }
        return modifiedView
    }
}

extension View {
    func accessibilityActions(_ actions: [AccessibilityAction]) -> some View {
        modifier(AccessibilityActionsModifier(actions: actions))
    }
}

Finally, using the new method.

struct ContentView: View {
    @StateObject var viewModel = ViewModel()
    var body: some View {
        Text(viewModel.title)
            .padding()
            .border(Color.red)
            .accessibilityActions(makeAccessibilityActions())
    }

    private func makeAccessibilityActions() -> [AccessibilityAction] {
        viewModel.actions.map { action in
            AccessibilityAction(
                name: "\(action.name)"
            ) {
                viewModel.perform(action: action)
            }
        }
    }
}

Attempt 2: Flattening accessibility elements

SwiftUI has other accessibility APIs, one of those is the .accessibilityElement(children:) modifier that can control the accessibility behaviour of nested child views.

The modifier takes an AccessibilityChildBehavior parameter which has one of three values:

ignore: All accessibility information within child views are ignored
contain: Maintains the child views accessibility information as separate nested elements
combine Flattens the accessibility information of all child views to a single accessibility element

The last option is of particular interest - earlier we discarded the use ForEach because it will end up creating a view for each accessibility action, however now with this extra modifier we can make it work!

Albeit a bit of a questionable approach - we can create a background view composed of multiple invisible views, each hosting an individual accessibility action, and finally combining them into a single accessibility element using the .accessibilityElement(children: .combine) modifier.

struct ContentView: View {
    @StateObject var viewModel = ViewModel()
    var body: some View {
        Text(viewModel.title)
            .padding()
            .border(Color.red)
            .background(
                ForEach(viewModel.actions) { action in
                    Color
                        .clear
                        .accessibilityAction(named: action.name) {
                            viewModel.perform(action: action)
                        }
                }
            )
            .accessibilityElement(children: .combine)
    }
}

As with the previous approach we can leverage a custom modifier to make the API a bit neater. A slight difference is we’ll need to make the AccessibilityAction type Identifiable in order for it to work with ForEach.

struct AccessibilityAction: Identifiable {
    var id: String
    var name: LocalizedStringKey
    var handler: () -> Void
}

struct AccessibilityActionsModifier: ViewModifier {
    let actions: [AccessibilityAction]

    func body(content: Content) -> some View {
        content.background(
            ForEach(actions) { action in
                Color
                    .clear
                    .accessibilityAction(named: action.name, action.handler)
            }
        )
        .accessibilityElement(children: .combine)
    }
}

extension View {
    func accessibilityActions(_ actions: [AccessibilityAction]) -> some View {
        modifier(AccessibilityActionsModifier(actions: actions))
    }
}

And finally, it can be used by our custom view as before.

struct ContentView: View {
    @StateObject var viewModel = ViewModel()
    var body: some View {
        Text(viewModel.title)
            .padding()
            .border(Color.red)
            .accessibilityActions(makeAccessibilityActions())
    }

    private func makeAccessibilityActions() -> [AccessibilityAction] {
        viewModel.actions.map { action in
            AccessibilityAction(
                id: action.id,
                name: "\(action.name)"
            ) {
                viewModel.perform(action: action)
            }
        }
    }
}

Conclusion

While I’m glad I found a few ways to get this working, I can’t help but feel those are merely workarounds. I have filed a feedback for this specific case (FB9071861) to suggest the addition of a modifier that can configure multiple accessibility actions accessibilityActions().

I suspect this sort of issue will crop up for other SwiftUI APIs that leverage modifiers. Aside from leveraging type erasure to AnyView, I wonder if there’s a more idiomatic and elegant approach to applying modifiers dynamically given a list of parameters.

Links

Updates

Avoiding type erasure

Updated: April 16, 2021

A huge thanks to @IanKay for suggesting this neater alternative that doesn’t require any type erasure!

Type erasure was needed with the first approach to allow assigning two different types to the same results variable while iterating, the original View and it’s modified version ModifiedContent<View, AccessibilityAttachmentModifier>.

// pseudo code

// type: View
var modified = view 
for action in actions {
    // type: ModifiedContent<View, AccessibilityAttachmentModifier>
    modified = modified.accessibilityAction { ... } 
}

However if we were to have the initial value be the view with the modifier applied, we’d no longer have this issue as we’d only be assigning one type to the same variable.

// pseudo code

let first = actions.first
// type: ModifiedContent<View, AccessibilityAttachmentModifier>
var modified = view.accessibilityAction(named: first.name, first.handler) 
for action in actions.dropFirst() {
    // type: ModifiedContent<View, AccessibilityAttachmentModifier>
    modified = modified.accessibilityAction(named: action.name, action.handler) 
}

Piecing this together we can update our custom modifier

struct AccessibilityActionsModifier: ViewModifier {
    let actions: [AccessibilityAction]

    @ViewBuilder
    func body(content: Content) -> some View {
        if let first = actions.first {
            let initial = content.accessibilityAction(named: first.name, first.handler)
            actions.dropFirst().reduce(initial) { view, action in
                view.accessibilityAction(named: action.name, action.handler)
            }
        } else {
            content
        }
    }
}

Note the use of @ViewBuilder here, this allows the body method to return two different types even though it’s declaring an opaque return type of some View.

iOS 16 API

Updated: June 27, 2022

My feedback FB9071861 was addressed in iOS 16 🎉, many thanks to the engineers involved! accessibilityActions is now a public API in Swift UI and allows constructing a dynamic set of accessibility actions.

This alleviates the need for the workarounds described above. That said, to support older OS versions, the helpers previously described in this post could be extended and conditioned for iOS 16 as follows:

extension View {
    @ViewBuilder
    func accessibilityActions(_ actions: [AccessibilityAction]) -> some View {
        if #available(iOS 16.0, *) {
            accessibilityActions {
                ForEach(actions) { action in
                    Button(action.name, action: action.handler)
                }
            }
        } else {
            modifier(AccessibilityActionsModifier(actions: actions))
        }
    }
}

Skipping Tests in Xcode

Sun, 09 Aug 2020 18:15:00 +0000

Overview

It’s that time of year where we get to play with the latest APIs in the beta versions Xcode, try out all the new shiny APIs as well as make sure our apps continue to work with the existing APIs. it’s both an exciting and somewhat interesting time.

As the name suggests, the beta versions of Xcode and operating systems are just that, they are beta versions and may come with bugs included. Some of which may cause some of our tests to genuinely fail, and may require us to to temporarily disable those tests while those bugs are resolved.

In this post, we’ll explore a number of different techniques we can use to disable or skip tests in Xcode, more specifically we’ll be looking into how we can skip tests based on the OS or Xcode version in use.

Backstory
Disabling Tests
Skipping Tests
Side Notes
- First Attempt
- Skipping Based on Other Custom Data
Closing Thoughts
Reference Material

Backstory

Recently, while running our test suite using Xcode 12 beta 4, we uncovered an iOS 14 beta bug. Typically around this time, our CI is configured to run against both a release version of Xcode (e.g. Xcode 11.5) as well as the latest beta (e.g. Xcode 12 beta 4) to ensure our code is compatible with both.

This left us with a puzzling choice now that some of the tests fail on Xcode 12 beta:

Add a temporary workaround for the bug to get the tests passing again
Temporarily disable those tests and remember to re-enable them when the next beta is released

In this particular case, writing a workaround isn’t worthwhile (yet) as we hope this will get fixed in an upcoming beta, as such we’re left with temporarily disabling those failing tests.

This got me thinking, is there a way for us to skip tests based on a specific version of Xcode? Such that when we update to the next beta, the tests would automatically stop getting skipped.

Disabling Tests

Tempting Options

One temptation could be to comment out the failing test all together:

// func test_betaFailingTests() {
//    // ...
// }

While definitely a quick and easy option, it does come with a downside, the test code will not even be compiled. Depending on how long the test remains commented out, the code could evolve in a way that results in the test method no longer compiling in the future when it eventually gets uncommented.

Another temptation could be to rename the test method:

func disabled_test_betaFailingTests() {
   // ...
}

XCTest only runs test methods that have a test prefix, as such renaming to anything else will result in that test no longer getting run. This approach does at least allow the code to benefit from compilation, however will no longer be run or recognised as a test on any version of Xcode.

It’s best those options be avoided where possible in favor of some of the other options listed in this post.

Disabling tests via Xcode

Xcode has a built in mechanism that allows you to selectively disable tests without resorting to any code changes.

This can be achieved by right clicking on the test name in the test inspector and selecting the “Disable” option.

This marks those tests within the selected scheme or test plan as disabled and subsequently they will be excluded when running the entire test suite. One benefit of this approach over the previous options is that even while excluded from the test suite, disabled tests can still be individually run from within the editor in Xcode when needed.

Dedicated Schemes

While we can’t conditionally mark tests as disabled within a scheme, we can still leverage them to do so by creating different schemes, one for the release version of Xcode and another for the beta.

Where we only mark the tests as disabled within the beta scheme.

Then on our CI we can use the appropriate scheme based on Xcode version in use:

# When using Xcode 11
$ xcrun xcodebuild test \
  -scheme App  \
  -destination 'platform=iOS Simulator,OS=latest,name=iPhone 8'

# When using Xcode 12 beta
$ xcrun xcodebuild test \
  -scheme App_iOS14  \
  -destination 'platform=iOS Simulator,OS=latest,name=iPhone 8'

Dedicated Test Plans

An alternate to managing multiple schemes is to leverage multiple test plans. As of Xcode 11, Xcode supports more advanced configuration customisations for tests know as test plans. A scheme can have one or more test plans associated with it.

We can create a test plan dedicated to iOS 14 beta testing.

Tests can then be marked as disabled within that test plan via the test inspector, or even directly in the test plan itself (make sure to take note of which test plan is selected):

Then on our CI we can use the appropriate test plan based on Xcode version in use:

# When using Xcode 11
$ xcrun xcodebuild test \
  -scheme App  \
  -testPlan App_TestPlan \
  -destination 'platform=iOS Simulator,OS=latest,name=iPhone 8'

# When using Xcode 12 beta
$ xcrun xcodebuild test \
  -scheme App  \
  -testPlan App_TestPlan_iOS14 \
  -destination 'platform=iOS Simulator,OS=latest,name=iPhone 8'

Skipping Tests

Skipping via Command Line

Another option available to us that doesn’t require maintaining multiple schemes or test plans is to leverage the -skip-testing command line option when using xcodebuild.

It takes the form of:

-skip-testing:”<TestTargetName>/<TestClassName>/<TestName>”

For example:

# When using Xcode 12 beta
$ xcrun xcodebuild test \
  -scheme App  \
  -destination 'platform=iOS Simulator,OS=latest,name=iPhone 8' \
  -skip-testing:"AppTests/AppTests/test_betaFailingTest" \
  -skip-testing:"AppTests/AppTests/test_anotherBetaFailingTest"

This will result in those tests getting skipped on the Xcode 12 CI job only, however will continue to run on other CI jobs as well as locally in Xcode.

Skipping at Runtime

In Xcode 11.4, XCTSkip , XCTSkipIf and XCTSkipUnless were introduced to allow skipping tests at runtime.

func test_skipMe() throws {
   throw XCTSkip("Skipping this test")
   // ...
}

func test_skipIf() throws {
   try XCTSkipIf(someConditionIsTrue(), "Skipping this test")
   // ...
}

func test_skipUnless() throws {
   try XCTSkipUnless(someConditionIsFalse(), "Skipping this test")
   // ...
}

It’s worth watching this year’s WWDC’s XCTSkip your tests video for more details.

Skipping Based on OS Version

We could leverage the new skipping feature to conditionally skip based on OS version.

For example:

final class AppTests: XCTestCase {
    func test_betaFailingTest() throws {
        try skipIfiOS14()
        // ...
    }
}

extension XCTestCase {
   func skipIfiOS14() throws {
      if #available(iOS 14, *)  {
         throw XCTSkip("Skipping test on iOS 14")
      }
   }
}

Skipping Based on Swift Compiler Version

Along the same lines, we could also skip based on Swift compiler version.

extension XCTestCase {
    func skipIfSwift53Compiler() throws {
        #if compiler(>=5.3)
            throw XCTSkip("Skipping test on Swift 5.3 compiler")
        #endif
    }
}

This can sometimes be handy in the event the issue causing the tests to fail relates to a specific compiler version as opposed to a specific iOS version (e.g. Running the test built with Xcode beta on an iOS 13 simulator would also fail). Xcode 12 beta has a new Swift compiler version 5.3, this can allow us to distinguish between it and Xcode 11.

Skipping based on Xcode Version

Going back to the scenario we faced, we would like to temporarily skip the test for a particular Xcode beta version, and not for iOS 14 or the Swift 5.3 compiler forever more … in fact it would be great if it gets re-enabled automatically next time we update Xcode.

We’d like something along the lines of:

final class AppTests: XCTestCase {
    func test_betaFailingTest() throws {
        try skipIf(xcodeVersion: "12.0-beta4")
        // ...
    }
}

Finding the Xcode Version

As it happens, the information we’re after is already included within the Info.plist of our test target. Xcode by default includes a few additional keys at compile time to the final plist file that gets embedded within the built product (the .xctests bundle).

We can inspect the contents of the plist file to see for ourselves:

defaults read /path/to/DerrivedData/AppTests.xctests/Info.plist

The .xctests bundle can be located by right clicking on the test target under the Products group in Xcode and selecting Reveal in Finder.

Note: for unit tests with host applications, the .xctests bundle is embedded within the host application.

defaults read /path/to/DerrivedData/App.app/PlugIns/AppTests.xctests/Info.plist

We should see something similar to this:

{
    BuildMachineOSBuild = 19E287;
    CFBundleDevelopmentRegion = en;
    CFBundleExecutable = AppTests;
    CFBundleIdentifier = "net.testing.AppTests";
    CFBundleInfoDictionaryVersion = "6.0";
    CFBundleName = AppTests;
    CFBundlePackageType = BNDL;
    CFBundleShortVersionString = "1.0";
    CFBundleSupportedPlatforms =     (
        iPhoneSimulator
    );
    CFBundleVersion = 1;
    DTCompiler = "com.apple.compilers.llvm.clang.1_0";
    DTPlatformBuild = 18A5342e;
    DTPlatformName = iphonesimulator;
    DTPlatformVersion = "14.0";
    DTSDKBuild = 18A5342e;
    DTSDKName = "iphonesimulator14.0";
    DTXcode = 1200;
    DTXcodeBuild = 12A8179i;
    MinimumOSVersion = "13.0";
    UIDeviceFamily =     (
        1,
        2
    );
}

Notice two interesting keys, DTXcode and DTXcodeBuild:

    DTXcode = 1200;
    DTXcodeBuild = 12A8179i;

While we do not have the beta number per se, the DTXcodeBuild (build version) value is unique to each Xcode version including beta versions. This can be found in Xcode’s about screen:

Or from the command line:

$ xcrun xcodebuild -version
Xcode 12.0
Build version 12A8179i

Accessing the Xcode Version at Runtime

We can access values from our Info.plist file at runtime via bundle.object(forInfoDictionaryKey:)

func currentXcodeBuildVersion() -> String? {
   class BundleFinder { }
   let bundle = Bundle(for: BundleFinder.self)
   return bundle.object(forInfoDictionaryKey: "DTXcodeBuild") as? String
}

Final Results

Piecing together what we have so far, we can write a small helper method to skip based on a specific Xcode version:

extension XCTestCase {
    func skipIf(xcodeVersion: String) throws {
         guard let currentVersion = currentXcodeBuildVersion() else {
            return
        }
        try XCTSkipIf(xcodeVersion == currentVersion, "Skipping test, Xcode build version is \(xcodeVersion)")
    }
}

Instead of dealing with string versions, we can tidy things up a bit by creating an XcodeVersion enum that helps us map them to their semantic versions:

enum XcodeVersion: String {
   // ...
   case xcode12_beta4 = "12A8179i"
}

extension XCTestCase {
    func skipIf(xcodeVersion: XcodeVersion) throws {
        guard let currentVersion = currentXcodeBuildVersion() else {
            return
        }
        try XCTSkipIf(xcodeVersion == currentVersion, "Skipping test, Xcode build version is \(xcodeVersion)")
    }

    func currentXcodeBuildVersion() -> XcodeVersion? {
        class BundleFinder { }
        let bundle = Bundle(for: BundleFinder.self)
        let versionString = bundle.object(forInfoDictionaryKey: "DTXcodeBuild") as? String
        return versionString.flatMap {
            XcodeVersion(rawValue: $0)
        }
    }
}

And we finally end up with the following at the call site:

final class AppTests: XCTestCase {
    func test_betaFailingTest() throws {
        try skipIf(xcodeVersion: .xcode12_beta4)
        // ...
    }
}

Side Notes

First Attempt

At first I didn’t realise that the DTXcodeBuild key was already included in the final Info.plist file, it’s not till I started preparing this blog post and explaining the methodology that I discovered it. This is one of the great things about blogging or presenting topics publicly, it encourages you to research that topic further to help explain it better, and by doing so you actually end up learning more about said topic!

For completeness, here was my initial approach to obtaining the Xcode build version (for the next few paragraphs, let’s pretend DTXcodeBuild doesn’t exist).

Is the Xcode build version available to us at build time? To answer this question, we can inspect all the build settings available and their resolved values via:

$ xcrun xcodebuild -showBuildSettings -target AppTests

This will flood our console (there’s a fair bit of build settings!), we can either use grep to filter through or store the output in a file and browse it in our favourite editor.

Inspecting the build settings, we can see a few Xcode related settings:

$ xcrun xcodebuild -showBuildSettings -target AppTests | grep -i xcode_
    # ...
    XCODE_PRODUCT_BUILD_VERSION = 12A8179i
    XCODE_VERSION_ACTUAL = 1200
    XCODE_VERSION_MAJOR = 1200
    XCODE_VERSION_MINOR = 1200

This is quite useful as we can reference any of those build settings in our test target’s Info.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <!-- ... -->
  <key>CurrentXcodeBuildVersion</key>
   <string>$(XCODE_PRODUCT_BUILD_VERSION)</string>
</plist>

When compiling our test target, Xcode will evaluate the Info.plist file and embed a version with the final resolved values within the built .xctests bundle product.

We can inspect the evaluated plist as we previously did:

defaults read /path/to/DerrivedData/AppTests.xctests/Info.plist

{
    ...
    CurrentXcodeBuildVersion = 12A8179i;
}

We’ve already seen how to access those values at runtime.

bundle.object(forInfoDictionaryKey: "CurrentXcodeBuildVersion") as? String

Alas we don’t need to jump through those hoops as DTXcodeBuild is automatically set for us.

Skipping Based on Other Custom Data

If you find yourself needing to skip tests based on other environmental conditions at runtime, you can leverage the same Info.plist technique used above and pass your own custom data.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <!-- ... -->
  <key>CustomKey</key>
   <string>$(MY_CUSTOM_KEY)</string>
</plist>

MY_CUSTOM_KEY can then be set directly in Xcode’s build settings editor as a user defined setting, or in an .xcconfig file, or even specified via the command line:

$ xcrun xcodebuild test \
  -scheme App  \
  -destination 'platform=iOS Simulator,OS=latest,name=iPhone 8' \
  MY_CUSTOM_KEY="CustomValue"

Closing Thoughts

What started out as curious exploration of the question “Can we skip tests based on a specific Xcode version?”, turned into this longish post on a number of different ways one can disable or skip tests in Xcode.

I hope you find this useful, happy testing!

Reference Material

Markdown test specifications

Sun, 03 Nov 2019 20:00:00 +0000

Overview

xcdiff has recently been open sourced 🎉. It’s a command line tool we’ve been working on to aid us with our migration over to using generated Xcode projects.

Today I wanted to shine a small spot light on an interesting testing technique we employed for xcdiff - that is using markdown files to define test specifications.

Here’s an example of what that looks like:

Please note that even though I am writing this post, credit goes to @marciniwanicki and @adamkhazi for all their hard work on this, I am merely jotting it down in blog form 🙂.

What is xcdiff?

It’s a command line tool that helps us compare Xcode projects against one another. In the context of migrating over to leveraging generated projects using tools like XcodeGen or Tuist, it provides us with a mechanism to verify what we’ve generated matches the original project we previously had.

It does so using by using a number of different “comparators”, each of which can diff a specific attribute of an Xcode project, such as “sources”, “headers”, “settings” and more.

The final results are combined into a report which can be in any of those formats: console, markdown or json.

For example here’s a snippet from a console formatted report:

xcdiff -p1 OriginalProject.xcodeproj -p2 GeneratedProject.xcodeproj -v

❌ SOURCES > "Project" target

⚠️  Only in first (1):

  • Project/Group B/AnotherObjcClass.m


⚠️  Value mismatch (1):

  • Project/Group A/ObjcClass.m compiler flags
    ◦ nil
    ◦ -ObjC

The report indicates that our generated project is missing a source file AnotherObjcClass.m and that the source file ObjcClass.m has mismatching compiler flags set.

The original motivation

In addition to having unit tests for xcdiff we wanted to have a suite of integration tests that exercise all of xcdiff’s components together on some real projects.

Initially, we had a few XCTest based tests written out for those integration tests:

func testRun_whenDifferentProjects() {
    // Given
    let command = buildCommand()

    // When
    let code = sut.run(with: command)

    // Then
    XCTAssertEqual(printer.output, """
    ❌ TARGETS > Native
    ❌ TARGETS > Aggregate
    """)

    XCTAssertEqual(code, 1)
}

However we soon noticed a few issues with this approach:

We were were constantly updating those test as we added more features
Getting the multi-line strings to be a perfect match to the output was more challenging than we thought - more often than not we would miss a new line at the end!

For example, the test above is a wholistic “show me a summary of all the differences” between two projects. When we added a sources comparator, the test needed to be updated as the output now includes that new comparator’s results:

XCTAssertEqual(printer.output, """
❌ TARGETS > Native
❌ TARGETS > Aggregate
❌ SOURCES > "Project" target
""")

This was somewhat manageable with a handful of those tests, but we wanted to test the output for a few different argument combinations.

--format console
--format console --verbose
--format markdwon
--format markdwon --verbose
--format json
--format json --verbose

We really liked the power of those tests however we couldn’t realistically scale them further or try to introduce additional combinations of arguments.

So we started exploring some alternate options.

External files

Rather than constantly copy and paste the expected output to the test we found it was much simpler to run the command and pipe its output to a file:

xcdiff --format markdwon --verbose > markdown_verbose.md
xcdiff --format json --verbose > json_verbose.json

Using this approach we modified our test to read those files and use their contents to validate the command output against.

func testRun_whenDifferentProjects() {
    // Given
    let command = buildCommand("--format", "markdown", "--verbose")

    // When
    let code = sut.run(with: command)

    // Then
    XCTAssertEqual(printer.output, expectedOutput(file: "markdown_verbose.md"))
    XCTAssertEqual(code, 1)
}

// MARK: - Helpers

private func expectedOutput(file: String) -> String {
   // read file contents from a known location
}

This helped us manage those tests better and reduced the size of the test code as it was no longer mixed with lengthy expected output strings!

Automating file generation

Using external files helped us scale our tests but as we did that, the first issue (keeping the outputs in sync) started getting somewhat tedious and repetitive.

xcdiff --format markdwon --verbose > markdown_verbose.md
xcdiff --format json --verbose > json_verbose.json
...
...

However this process is scriptable! So we wrote a small script that ran through all our test commands to generate our files.

Scripts/generate_tests_commands_files

This way we didn’t need to constantly figure out which commands we needed to run to re-generate the files.

Making files self describing

In order to add a new integration test we needed to manually add new test cases in code as well as a corresponding expected output file. We saw an opportunity for improvement here.

We wanted a solution that would allow us to simply add a file and that somehow gets automatically evaluated as part of our integration tests.

Iterating over a directory with files is fairly straight forward, however what we lacked was conveying all the necessary information to test. Our integration test need three pieces of information:

The command to run
The expected exit code
The expected output

The output we already had, it was the content of the file itself, we just needed to find a way to convey the other two.

Our first attempt was to encode that in the file name:

<command>.<exitcode>.txt

For example:

--format markdown --verbose.1.txt

This worked! We weren’t sure if we’d be able to encode all our parameters as file names, but to our surprise it was ok.

So we updated our integration test to scan a directory called CommandTests where all those text files lived:

func testRun_commands() {
    let commandTests = parseFiles(in: "CommandTests")
    commandTests.forEach { commandTest in
	    // Given
	    let command = buildCommand(commandTest.command)
	
	    // When
	    let code = sut.run(with: command)
	
	    // Then
	    XCTAssertEqual(printer.output, commandTest.output)
	    XCTAssertEqual(code, commandTest.exitCode)
	}
}

This allowed us to significantly boost the number of integration tests we had - it was now a matter of adding a new file to a directory whenever we needed a new one, or running the generate script to update the existing one.

Markdown files

As we introduced more comparators and corresponding tests, we noticed that there was room for yet some more improvements.

Having commands and exit codes encoded in the filename works well for our test code, just sadly not for us mortal humans. We found that reviewing those files wasn’t as smooth as we would have liked them to be. We needed to inspect the file name (which could be fairly lengthy) separately from the file content to see what the test case was.

So we decided to try moving that information into the file contents, such that now the contents contain all three pieces of information needed for the test.

Now we had to think of a format of how to structure the file internally.

<command>
<exit code>
<output>

Our first thought was fairly simple:

line 1: command
line 2: expected exit code
line 3 - End of file: expected output

However seeing we could craft this file to be any format we wanted, why not make it even more readable by giving it some structure, more so, some structure that renders well in our editors and on GitHub!

Thus the markdown idea! We structured the file in the following format:

 # Command
 ```json
 <JSON REPRESENTATION OF THE COMMAND>
 ```

 # Expected exit code
 <NUMBER>

 # Expected output
 ```
 <CONTENT OF THE OUTPUT>
 ```

For example:

 # Command
 ```json
 ["--foobar"]
 ```

 # Expected exit code
 1

 # Expected output
 ```
 ERROR: unknown option --foobar; use --help to list available options
 ```

This of course didn’t come fore free, we had to write a custom parser using Scanner- but we thought was worth the effort given the final results.

Final workflow

After many iterations we now have the following workflow:

To add new test cases:

Update a json file that contains a list of all the commands we’d like to run integration tests for
- generated_test_commands.json: This file hosts a list or arguments which the test generator uses to generate various command combinations
- manual_test_commands.json: This file hosts commands we manually add
Run the test generator Scripts/generate_tests_commands_files.py
- This reads the json files to generate our markdown test specifications to the CommandTests directory
Review the generated files

For newly added commands, the review step helps both the author and the reviewer see a real example of the output without them needing to build and run xcdiff.

For existing commands, regressions or changes to the output format are easily spottable as they will appear in the git diff.

Lastly all of the markdown files are run through the CommandBasedTests integration to ensure it reflects reality.

Future improvements

There’s still room for more improvements of course, for example instead of using json:

 # Command
 ```json
 ["--format", "markdown", "--verbose"]
 ```

It would be nicer to write out the command as users of the tool would:

 # Command
 ```sh
 xcdiff --format markdown --verbose
 ```

Additionally, all our integration tests appear as a single test in test case in XCTest and would be great to see if there’s a way we can hook into the the test runners to make each file appear as an individual test case in the test inspector.

But those all could be made as the need for them arises in the future.

Conclusion

What started out as a means to help us reason about our integration tests has also doubled as a source of live documentation for xcdiff’s output that is guaranteed to stay up-to-date!

It by no means is a technique that should be used for all use cases, nor should it be used as a means to overlook a good suite of unit tests. It is however is an interesting technique that could bring some additional value that is worth considering.

Safe Area Insets

Sat, 27 Oct 2018 16:00:00 +0000

Overview

The safe area API was first introduced back in WWDC 2017 in iOS 11 as a replacement for the deprecated topLayoutGuide and bottomLayoutGuide properties on UIViewController. Up till then, those deprecated properties were used to support extended layouts. Typically used to ensure our views weren’t obscured by any translucent top or bottom bars added by UIKit container view controllers such UINavigationController and UITabBarController.

It wasn’t till the iPhone X launch later that year that the true motivation behind the new API came to light. In addition to the top and bottom bars, we now have to account for the rounded corners and the sensor housing (aka the notch). With potential obstructions on all sides, a more versatile API was needed.

That is exactly what the safe area API offered! UIView now has two new properties safeAreaLayoutGuide (for auto layout) safeAreaInsets (for manual layout). The fact those properties are on UIView is a much welcomed addition, as now each view can manage its layout without the need to have the view controller propagate the appropriate insets down to the views or worse, have the views reference the view controller to pull them out!.

That said, the safe area API has some oddities in behaviour which don’t appear to be well documented (at least non that I could find), especially when it comes to child view controller views.

The short version

The behaviour of safeAreaInsets actually varies based on the view type, size and location in the hierarchy:

For standalone views (i.e. ones not managed by a view controller), their safeAreaInsets will update based on their position in relation to their superview’s bounds and safeAreaInsets
For view controller views however (e.g. child view controller views), their safeAreaInsets remain fixed or “frozen”

In the event the view controller’s view is initially offset at the time of adding it to the view hierarchy, the insets remain zero up till the point the view offset is reset to zero (i.e. aligned with the screen):

However, if the child view controller’s view size is smaller than the screen, the insets starts behaving like the standalone view:

Lastly, child view controller’s view safeAreaInsets can outgrow their superview, even when the view controller’s addtionalSafeAreaInsets is zero!

Setup

To explore how the safeAreaInsets behave in those different situations and reproduce the results above, we’ll need to setup a small test environment.

Safe Area Test View

We’ll be using a UIView subclass to help us visualize the safeAreaInsets which has:

A red background color
A blue subview that is pinned to the safeAreaLayoutGuide
A label to display the safeAreaInsets value

class SafeAreaTestView: UIView {
    
    let safeAreaLabel = UILabel()
    
    override init(frame: CGRect) {
        super.init(frame: frame)
        
        let safeAreaView = UIView()
        addSubview(safeAreaView)
        safeAreaView.anchor(to: safeAreaLayoutGuide)
        
        safeAreaLabel.numberOfLines = 0
        addSubview(safeAreaLabel)
        safeAreaLabel.anchor(to: safeAreaLayoutGuide)
        
        safeAreaLabel.textColor = .lightGray
        safeAreaView.backgroundColor = .blue
        backgroundColor = .red
    }
    
    override func safeAreaInsetsDidChange() {
        super.safeAreaInsetsDidChange()
        safeAreaLabel.text = "\(safeAreaInsets)"
    }

    // ...
}

// ...

private extension UIView {
    func anchor(to layoutGuide: UILayoutGuide) {
        translatesAutoresizingMaskIntoConstraints = false
        NSLayoutConstraint.activate([
            leadingAnchor.constraint(equalTo: layoutGuide.leadingAnchor),
            topAnchor.constraint(equalTo: layoutGuide.topAnchor),
            trailingAnchor.constraint(equalTo: layoutGuide.trailingAnchor),
            bottomAnchor.constraint(equalTo: layoutGuide.bottomAnchor),
        ])
    }
}

I’ll be using a similar view but with minor color and text formatting adjustments to make the screenshots a little more presentable.

Root View Controller

We’ll then need a simple view controller which hosts a container view and a UISlider that controls its position:

class RootViewController: UIViewController {
    
    // ...

    var containerView: UIView!
    func setupContainers() {
        containerView = UIView(frame: view.bounds)
        containerView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(containerView)
    }

    // ...

    func setupControls() {
        let slider = UISlider()
        slider.minimumValue = -100
        slider.maximumValue = 100
        slider.addTarget(self,
                         action: #selector(didUpdateOffset(_:)),
                         for: .valueChanged)
        
        slider.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(slider)
        NSLayoutConstraint.activate([
            slider.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),
            slider.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor),
            slider.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor)
        ])
    }

    @objc func didUpdateOffset(_ sender: UISlider) {
        let offset: CGFloat = CGFloat(sender.value)
        var frame = containerView.frame
        frame.origin.y = offset
        containerView.frame = frame
    }
}

Experiments

Standalone view

For our first experiment, we’ll be adding the SafeAreaTestView as a subview of the container view.

class RootViewController: UIViewController {
    
    // ...

    func setupTest() {
        let safeAreaView = SafeAreaTestView(frame: containerView.bounds)
        safeAreaView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        containerView.addSubview(safeAreaView)
    }
}

Then we’ll use the slider to offset the containerView’s position and examine the test view.

We’ll notice that:

When increasing the view’s y coordinate, the top safe area insets keep decreasing till they reach zero
The bottom safe area inset on the other hand remains fixed as the bottom edge of the view goes out of bounds
Similar results are obtained the other way too when decreasing the y coordinate

The behaviour here looks normal and is expected based on the safeAreaInsets documentation:

… For other views in the view hierarchy, the insets reflect only the portion of the view that is covered. For example, if a view is entirely within the safe area of its superview, the edge insets in this property are 0.

It doesn’t explicitly call out that the insets become fixed for the edge of the view that goes out of bounds, but that seems reasonable.

Child view controller view

Next, we’ll repeat the same experiment, but instead we’ll have the test view be the root view of a view controller subclass.

class ChildViewController: UIViewController {
    override func loadView() {
        view = SafeAreaTestView()
    }
}

This view controller can then be added as a child of our RootViewController:

class RootViewController: UIViewController {

    // ...

    func setupTest() {
        let childViewController = ChildViewController()
        embed(child: childViewController, in: containerView)
    }
    
    func embed(child: UIViewController, in view: UIView) {
        addChild(child)
        child.view.frame = view.bounds
        child.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(child.view)
        child.didMove(toParent: self)
    }
}

We’ll notice a slight difference in behaviour here:

The safeAreaInsets remain fixed or “frozen” regardless of the view’s position

This is where the odd behaviour starts, and where the safeAreaInsets documentation becomes a little foggy:

For the view controller’s root view, the insets account for the status bar, other visible bars, and any additional insets that you specified using the additionalSafeAreaInsets property of your view controller.

Unless we take it literally?

… the insets account ONLY for the status bar, other visible bars …

Initially offset view

This time, we’ll have the container view already offset before adding our ChildViewController’s view to the hierarchy.

    // ...

    let initialOffset: CGFloat = 50.0
    func setupContainers() {
        containerView = UIView(frame: view.bounds.offsetBy(dx: 0, dy: initialOffset))
        containerView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(containerView)
    }
    
    // ...

We’ll notice another interesting behaviour:

The safeAreaInsets start out as zero
They remain zero even while the container’s bounds start intersecting the “unsafe” area
The safeAreaInsets finally update upon the offset reaching zero
The insets then get frozen again

Smaller view

Making the ChildViewController’s view smaller by making the containerView smaller will yield a different result:

    // ...

    let heightDelta: CGFloat = -50.0
    func setupContainers() {
        var frame = view.bounds
        frame.size.height += heightDelta
        containerView = UIView(frame: frame)
        containerView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(containerView)
    }
    
    // ...

The behaviour now reverts back to that of the standalone view

Out of bounds view

For our final experiment, the goal is to test out the behaviour while the views go out of bounds but not off screen. We can achieve this by creating another view to host our containerView and have that view be inset within the RootViewController’s view.

Adding some sort of border will help us visualize the parent’s bounds.

    // ...

    let containerParentInset = UIEdgeInsets(top: 30, left: 0, bottom: 30, right: 0)
    var containerParentView: UIView!
    var containerView: UIView!
    func setupContainers() {
        let parentFrame = view.bounds.inset(by: containerParentInset)
        containerParentView = UIView(frame: parentFrame)
        containerParentView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        containerParentView.layer.borderColor = UIColor.purple.cgColor
        containerParentView.layer.borderWidth = 2.0
        view.addSubview(containerParentView)
        
        containerView = UIView(frame: containerParentView.bounds)
        containerView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        containerParentView.addSubview(containerView)
    }

    // ...

This yields yet another inconsistency in behaviour when comparing the the standalone view (labelled as “subview” in the screenshots above) with the ChildViewController’s view side by side:

The standalone view’s safeAreaInsets stop updating or “freeze” for the edge that is going out of bounds
While the ChildViewController’s view safeAreaInsets continue to update even after it’s out of bounds

What’s really interesting here is the fact that the ChildViewController’s view can have safeAreaInsets that are greater that its superview, even while its additionalSafeAreaInsets is zero!

Conclusions

It’s unclear if this behaviour is intended or a bug in the safe area API. Searching around, I found two open radars on this topic:

The best mental model I can come with for the current behavior is:

For standalone views:
- safeAreaInsets are based on the view’s location in relation to its superview, and its superview’s insets
- safeAreaInsets are frozen for the edge of the view that goes out of bounds
For view controller managed views
- safeAreaInsets are based on the view’s initial location
- safeAreaInsets of all edges are frozen once the view goes off screen (superview bounds are ignored it seems)

I could see the use for freezing safeAreaInsets when it comes to animating views on and off screen, as you probably wouldn’t want the content to shift internally too during that time. Perhaps a better approach here would be to extend the API to allow controlling this behaviour.

You may have noticed me using the term “frozen” throughout this post, this is because it appears to be the term found in the UIKit private headers 🙂.

Even with all these inconsistencies, I still have high hopes for this API as it’s a far superior and cleaner API than its predecessors. The ability to set custom safe areas (via additionalSafeAreaInsets on UIViewController) is fantastic! It allows us to create our own container view controllers with translucent views and achieve a similar effect to those found within UIKit.

Please reach out or comment if you have further insights on this.

Live Reset For UI Tests

Wed, 30 May 2018 18:00:00 +0000

Overview

A typical test case involves using our test subject from a clean (or perhaps some pre-determined) state, perform some action(s) and verify some state. UI tests should follow this pattern too. Each test case should re-launch the app and reset it prior to conducting the test to ensure we have deterministic test cases.

Resetting or pre-configuring the app on launch is easily achieved by specifying some launchArguments and launchEnvironment on XCUIApplication from within the test target. John Sundell covered examples of how this can be achieved in his UIKonf talk about the Magic of UI testing which is worth a watch!

Re-launching the app each time however has one small snag! This re-launch business takes up time, ~6 Seconds per re-launch! This figure is for a dummy app, the actual launch time could be worse for larger applications. That’s a whole minute for 10 test cases, ten minutes for 100!

The Short Version

During UI testing, introducing a mechanism to reset our app while it’s running will give us the best of both worlds, a clean slate each time and a faster transition to subsequent tests!

Here’s a demo of how such a technique compares:

The following sections will cover some of ways this reset mechanism can be implemented, ranging from simple to slightly more complex ones.

How much time is wasted?

In the intro I mentioned the 6 seconds figure, that’s what I measured for a sample app. If you’re curious how much time is wasted for your test cases you could inspect the raw logs in Xcode. Those can be found by navigating to the Report Navigator tab (⌘+9) and selecting Log. From there you could either expand the log in Xcode or copy it out to a file.

Note: to avoid copying out duplicate log lines, copy the section that starts with Run test suite...

The log lines look something like this:

t =    14.20s Open net.matrixprojects.trials.LiveReset
t =    14.23s     Launch net.matrixprojects.trials.LiveReset
t =    14.23s         Terminate net.matrixprojects.trials.LiveReset:37874
t =    17.76s         Wait for net.matrixprojects.trials.LiveReset to idle
t =    20.87s Tap "List" Button
t =    20.87s     Wait for net.matrixprojects.trials.LiveReset to idle
t =    20.91s     Find the "List" Button
t =    21.05s     Synthesize event
t =    21.15s     Wait for net.matrixprojects.trials.LiveReset to idle

In this example, the launch of the app takes place between Open net.matrixprojects.trials.LiveReset log line and the first action Tap "List" Button.

Bashing some python and regex together, we could work out the total launch time taken:

import re

log = open("/path/to/raw-ui-test.log", "r").read()
regex = "=\s*([0-9]+\.[0-9][0-9])s Open .*\n" \
        ".*Launch.*\n" \
        ".*Terminate.*\n" \
        ".*Wait.*\n" \
        ".*=\s*([0-9]+\.[0-9][0-9])s"
results = re.findall(regex, log)

total_launch_time = 0
for r in results: 
    launch_time = float(r[1]) - float(r[0])
    total_launch_time = total_launch_time + launch_time

print "%.2f Seconds" % total_launch_time

Live Reset

To pull this off, at a high level here’s what we’ll need:

Gracefully handle a “reset” event while the application is running
Build out a mechanism to get notified about reset events
Trigger a reset from the UI tests instead of re-launching the app for each test case

The UI test runner (where our UI test code is running) is actually it’s own app/process. This means we can’t simply call out to our application classes directly to trigger our reset logic. Sadly there aren’t any options available out of the box when using XCTest to overcome this limitation, so we’ll need to get a bit creative to find some solutions.

Handling a live reset

We’ll need to ensure the view and data states are both reset while the application is running. By view state here I mean the view hierarchies. A simple way to achieve this is to re-create the window from scratch when we need to reset:

extension AppDelegate {
    func reset() {
        tearDown()
        window = createWindow()
    }

    func tearDown() {
        window?.rootViewController = nil
        window?.isHidden = true
        window = nil
    }

    func createWindow() -> UIWindow {
        let storyboard = UIStoryboard(name: "Main", bundle: nil)
        
        let window = UIWindow(frame: UIScreen.main.bounds)
        window.rootViewController = storyboard.instantiateInitialViewController()
        window.makeKeyAndVisible()
        
        return window
    }
}

Regarding the data state, it’s just a matter of re-creating your models / dependencies (e.g. Networking, storage, business logic models, etc…). This will of course vary app by app, for the sake of this blog post, I’ll be using a class called AppDependencies to act as the conglomerate of models / dependencies the app needs to function.

extension AppDelegate {
    func reset() {
        tearDown()
        appDependencies = createAppDependencies()
        window = createWindow()
    }
    // ...
}

We can then hook this all up our didFinishLaunchingWithOptions method:

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    
    var window: UIWindow?
    
    var appDependencies: AppDependencies?
    var resetNotifier: ResetNotifier?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

        setup()
        
        return true
    }

    // ...
}

extension AppDelegate {
    func setup() {
        reset()
    }

    // ...
}

Note: In the event the main interface setting is specified in the target setting, a UIWindow will automatically be created and it’s rootViewController will be set to the initial view controller of the specified Storyboard file. To avoid creating a redundant window and seeing we’re now manually creating and setting it up, we could opt out of the automatic behavior by simply clearing that setting.

Reset Notifier

As we explore the different techniques of triggering a live reset, it’s helpful to model our “Reset Notifier” as a protocol:

// ResetNotifier.swift

protocol ResetNotifier {
    func add(handler: @escaping () -> Void)
}

extension AppDelegate {
    // ...

    func setupResetNotifier() {
        resetNotifier = createResetNotifier()
        resetNotifier?.add { [weak self] in
            self?.reset()
        }
    }

    // ...
}

This helps keep our AppDelegate clean and isolate our reset mechanism in separate classes. This will also allow us to swap implementations as needed.

Reset Trigger

To trigger the yet to be determined “reset” mechanism from our UI test target we’ll need to tweak our test cases to call out to a custom reset() method instead of the typical launch() method:

extension XCUIApplication {
    func reset() {
        if state != .runningForeground {
            launch()
        } else {
            resetAction()
        }
    }
}

In the event the application isn’t running, we will still need to launch it first, but to hide that concern from the individual test cases we can work it out within our reset() method by checking the current XCUIApplication.State.

1) Floating Button Reset Notifier

The idea here is quite simple, when launching the app under test, we could inject a small floating reset button in our main UIWindow.

class FloatingButtonResetNotifier: ResetNotifier {
    var handlers: [() -> Void] = []
    var buttonTargetAction = TargetAction()
    
    init(window: UIWindow) {
        let button = createButton()
        embed(button: button, within: window)
        setupTapAction(for: button)
    }
    
    func add(handler: @escaping () -> Void) {
        handlers.append(handler)
    }
    
    func handleTap() {
        handlers.forEach { $0() }
    }
    
    func createButton() -> UIButton {
        let button = UIButton(type: .custom)
        button.setTitle("[Reset]", for: .normal)
        button.backgroundColor = UIColor.red.withAlphaComponent(0.4)
        button.accessibilityIdentifier = Reset.Button.accessibilityIdentifier
        return button
    }
    
    func setupTapAction(for button: UIButton) {
        buttonTargetAction.onTap = { [weak self] in
            self?.handleTap()
        }
        
        button.addTarget(buttonTargetAction,
                         action: #selector(TargetAction.didTap(_:)),
                         for: .touchUpInside)
    }
    
    func embed(button: UIButton, within window: UIWindow) {
        window.addSubview(button)
        button.translatesAutoresizingMaskIntoConstraints = false
        NSLayoutConstraint.activate([
            button.trailingAnchor.constraint(equalTo: window.safeAreaLayoutGuide.trailingAnchor, constant: -10),
            button.bottomAnchor.constraint(equalTo: window.safeAreaLayoutGuide.bottomAnchor, constant: -10),
        ])
    }
    
    class TargetAction: NSObject {
        var onTap: (() -> Void)?
        
        @objc func didTap(_ sender: UIButton) {
            onTap?()
        }
    }
}

Due to this notifier’s dependency on the current UIWindow which we re-create each time, we’ll also need to re-create the reset notifier alongside it:

extension AppDelegate {
    func reset()  {
        tearDown()
        appDependencies = createAppDependencies()
        window = createWindow()
        setupResetNotifier()
    }
}

To trigger a reset from the UI tests, we simply tap that button:

extension XCUIApplication {
    func resetAction() {
        buttons[Reset.Button.accessibilityIdentifier].tap()
    }
}

Pros:

Simple to implement and manually test

Cons:

Quite intrusive, and could obstruct other views which may need to be tested
It isn’t possible to pass in new launchArguments or launchEnvironment when resetting for each test case

2) Gesture Reset Notifier

Instead of having a visible view this time, we could perhaps introduce a special gesture on the main window which triggers our reset.

class GestureBasedResetNotifier: ResetNotifier {
    var gestureHandler = ResetGestureHandler()
    var handlers: [() -> Void] = []
    
    init(window: UIWindow) {
        let gesture = createTapGesture(with: gestureHandler)
        setup(gesture: gesture, within: window)
        setupTriggerAction(for: gestureHandler)
    }
    
    func add(handler: @escaping () -> Void) {
        handlers.append(handler)
    }
    
    func didTrigger() {
        let handlers = self.handlers
        handlers.forEach { $0() }
    }
    
    func setupTriggerAction(for gestureHandler: ResetGestureHandler) {
        gestureHandler.onTrigger = { [weak self] in
            self?.didTrigger()
        }
    }
    
    func setup(gesture: UIGestureRecognizer, within window: UIWindow) {
        window.addGestureRecognizer(gesture)
        window.accessibilityIdentifier = Reset.Gesture.hostWindowAccessibilityIdentifier
    }
    
    func createTapGesture(with gestureHandler: ResetGestureHandler) -> UITapGestureRecognizer {
        let resetGesture = UITapGestureRecognizer(target: gestureHandler, action: #selector(ResetGestureHandler.didTrigger(_:)))
        resetGesture.numberOfTapsRequired = Reset.Gesture.numberOfTaps
        resetGesture.numberOfTouchesRequired = Reset.Gesture.numberOfTouches
        resetGesture.delaysTouchesBegan = false
        resetGesture.delaysTouchesEnded = false
        return resetGesture
    }
    
    class ResetGestureHandler: NSObject {
        var onTrigger: (() -> Void)?
        
        @objc func didTrigger(_ gestureRecognizer: UIGestureRecognizer) {
            guard gestureRecognizer.state == .recognized else {
                return
            }
            onTrigger?()
        }
    }
}

Similarly to the floating button, due to this notifier’s dependency on the current UIWindow, we’ll also need to re-create whenever we re-create the window:

extension AppDelegate {
    func reset()  {
        tearDown()
        appDependencies = createAppDependencies()
        window = createWindow()
        setupResetNotifier()
    }
}

To trigger the reset, we can attempt to perform the gesture, for example if it was a multiple tap based gesture:

extension  XCUIApplication {
    func resetAction() {
        let window = windows[Reset.Gesture.hostWindowAccessibilityIdentifier]
        window.tap(withNumberOfTaps: Reset.Gesture.numberOfTaps,
                   numberOfTouches: Reset.Gesture.numberOfTouches)
    }
}

Pros:

Not as obstructive as a floating button

Cons:

UI tests aren’t able to reliably trigger complex gestures (e.g. with multiple touches)
It’s easy to accidentally trigger the reset gesture during the test
As with the floating button, we aren’t able to pass new launchArguments or launchEnvironment when resetting

3) Darwin Notification Reset Notifier

You might be surprised to learn there’s actually a low-level API available within iOS that actually allows cross app communication! DarwinNotifyCenter. All-be-it a simple trigger without any means to pass data, for the purposes of a reset, it does the trick.

I’ve actually covered this in a previous post if you’re interested in details. Be warned it’s quite an old post and with many of the code snippets written in Swift 2 syntax! The good news is that the associated github project was recently updated to Swift 4.

In this example, I’ll be using the “beeper” class (I know, naming is hard …) from github. This class will need to be part of both the main application and UI test targets.

class DarwinNotifyCenterResetNotifier: ResetNotifier {
    var handlers: [() -> Void] = []
    let beeper = DarwinNotificationCenterBeeper()
    
    init() {
        beeper.registerBeepHandler(identifier: Reset.triggerKey) { [weak self] in
            self?.handlers.forEach { $0() }
        }
    }
    
    func add(handler: @escaping () -> Void) {
        handlers.append(handler)
    }
}

Since there is no dependency on the window here, the reset notifier only needs to be setup once and does not need to be re-created on every reset.

extension AppDelegate {
    func setup() {
        reset()
        setupResetNotifier()
    }
}

On the UI test side, we could trigger a reset via:

extension XCUIApplication {
    func resetAction() {
        DarwinNotificationCenterBeeper().beep(identifier: Reset.triggerKey)
    }
}

Pros:

This offers a real trigger mechanism without requiring us to inject elements into our hierarchy that could content with the elements being tested

Cons:

Like the previous techniques, we still aren’t able to pass new launchArguments or launchEnvironment when resetting
- That said, if there’s only a handful of settings we need (e.g. “launch with mock data” and “launch with real data”), we could extend our reset notifier to have two distinct reset methods which have their own notification identifiers. This of course will not scale with more settings!
This API seems too permissive, given how within the iOS eco-system there is heavy sandboxing to prevent apps from interfering with each other, it wouldn’t come as a surprise if this API were to no longer function or be supported in the future.

4) HTTP Request Reset Notifier

This sounds quite extreme but actually unlocks a whole load of possibilities while UI testing. A lightweight http server (e.g. Swifter or Embassy) can be installed within the main application. This server effectively creates another communication channel for us to send custom requests to control the behavior of the app during runtime. Thus enabling us to send a “reset” request from the test target (e.g. http://localhost:8080/reset).

This is not a wildly new concept, see Stubbing Apple’s UI Tests by Tomas Camin and Embedded web server for iOS UI testing by Fang-Pen Lin for examples of what is possible with such a setup beyond a simple “reset”.

For this example, I’ll be using Swifter:

import Swifter

class SwifterResetNotifier: ResetNotifier {
    var handlers: [() -> Void] = []
    let server: HttpServer
    
    init() {
        server = HttpServer()
        registerPathCallbacks(in: server)
        try! server.start(in_port_t(Reset.HttpServer.port))
    }
    
    func add(handler: @escaping () -> Void) {
        handlers.append(handler)
    }
    
    func handleReset() {
        DispatchQueue.main.sync {
            handlers.forEach { $0() }
        }
    }
    
    func registerPathCallbacks(in server: HttpServer) {
        server[Reset.HttpServer.resetPath] = { [weak self] _ in
            self?.handleReset()
            return .ok(.html("Reset triggered!"))
        }
    }
}

Similarly to the previous notifier, as there is no dependency on the window, the reset notifier only needs to be setup once and does not need be re-created on every reset.

extension AppDelegate {
    func setup() {
        reset()
        setupResetNotifier()
    }
}

Within the UI tests, it’s a matter of sending an http request to trigger a reset:

extension XCUIApplication {
    func resetAction() {
        guard let url = URL(string: Reset.HttpServer.resetUrl) else {
            return
        }
        
        let e = XCTestExpectation(description: "Reset request should complete")
        URLSession.shared.dataTask(with: url) { _, _, _  in
            e.fulfill()
        }.resume()
        
        XCTAssertEqual(XCTWaiter.wait(for: [e], timeout: 5.0), .completed)
    }
}

Another option within the same concept is to leverage a dedicated testing framework like SBTUITestTunnel by Tomas Camin. It leverages GCDWebServer under the hood and offers a mechanism to pass data between the UI test target and the main application via Custom Commands.

Pros:

Http requests are capable of also carrying extra data within the request body. Using some simple Codable structures we can easily pass new launchArguments or launchEnvironment equivalents to the application as part of the reset request. This will not only allow us to reset the app, but also re-configure it on demand based on our test requirements
In addition to resetting the application via our UI tests, we can craft a small html which can have buttons to reset and configure our application to the various states we’re interested in. Effectively we craft our own Hot Reload functionality!
- The html can actually be served from the embeded server when visiting a special link such as http://localhost:8080/debug

Cons:

Having an http server for testing purposes baked into the app could be a hard sell, we wouldn’t want to accidentally ship it to the App Store!
For the time being, the UI test runner is capable of initiating URLSession requests, that however may change as there are no guarantees provided by testing framework about the behavior of the test runner app. It’s been working thus far, let’s hope it carries on!

Interesting Side Effects

An interesting side effect of utilizing live reset is how the UI tests suddenly become a memory leak detector! Keeping the app alive between test cases means any leaks will reside and build up throughout the entire test run and eventually may cause some random crashes.

This actually presents a great opportunity to add some basic tooling to check for leaks and report them proactively (e.g. a weak references array of core components that should be empty on reset).

Mitigating Risk

Many of the techniques described come with some level of risk, as we could be polluting our app with test scaffolding code that we wouldn’t want to ship.

To mitigate this, we could ensure we have some compile time protection by wrapping all the reset code with #if DEBUG statements. To keep things manageable, we would need to minimize the surface area of our reset code to avoid littering #if DEBUG statements everywhere.

Another “safer” option is to perhaps create a dedicated “Sample” application target which includes all the additional test scaffolding while keeping our main application untouched. This does require the core logic of our app to reside within independent frameworks so they can be included by both application targets. The nice thing about this option is that we’re not restricted to just the one sample application, we can create as many as we need based on functionality. This can work really well for larger applications that are managed by multiple teams.

Conclusion

With a bit of creativity we’re able to optimize a small aspect of how our UI tests can run, it may not be for all projects but is certainly worth a try.

Happy testing!

Leveraging xcconfig files in shared projects

Sun, 06 May 2018 15:30:00 +0000

Overview

The best way to try out new libraries or frameworks is often through sample projects or even small scoped apps. Recently I’ve been toying with CloudKit in a small app, and wanted to pair with a friend who was also interested in learning more about it.

We setup a small project in a shared git repository which we were both able to build and run on our simulators. However when it got to adding the CloudKit bit to our project and start testing on our devices, that’s when the fun began.

Both of us have our own individual developer accounts, which allowed us to individually select our team in the project settings to get the app running on our devices. However that tweaked the project settings which was in source control and seeing we’re not part of a shared developer account (e.g. a team account), those changes were incompatible with one another!

In this post, I’ll share how we solved this issue by leveraging xcconfig configuration files.

The short version

In order to leverage automatic signing in Xcode, the PRODUCT_BUNDLE_IDENTIFIER and DEVELOPMENT_TEAM settings need to be set. Those will differ between developer accounts.

xcconfig files can be used to declare these kind of settings. The optional include syntax #include? can then be used within these files to allow referencing other xcconfig files that can host local overrides for each developer which can be excluded from source control.

In addition, we can specify our own custom settings like MY_CLOUDKIT_CONTAINER_ID which can then be used within the entitlements file of the app.

Read on for the details …

Setup

1) Create a new config file

Config files have the extension .xcconfig, they can be created manually or via Xcode.

For this example, let’s name this file CustomConfig.xcconfig

2) Declare overridable settings

This file should declare the settings we’d like to override but shouldn’t include the final values. This will allow us to safely commit it to the repository.

// Overridable settings with some defaults

PRODUCT_BUNDLE_IDENTIFIER = com.mydomain.myapps.AppName
DEVELOPMENT_TEAM = ""
CODE_SIGN_STYLE = Manual

// Optionally include `LocalConfig.xcconfig`
// that includes local overrides if it exists.
// `#include?` is supported as of Xcode 8

#include? "LocalConfig.xcconfig"

#include allows pulling in settings from other configuration files, a warning will be generated if the referenced file doesn’t exist. #include? was introduced in Xcode 8 and similarly pulls in settings from other configuration files, but will not generate a warning if the referenced file is missing.

Pro Tip: If you want to figure out the setting name, simply select the corresponding build setting line in Xcode, copy (cmd+c) and paste it in the xcconfig file

3) Create a local configuration file

In finder duplicate the configuration file under a different name (e.g. LocalConfig.xcconfig) without adding it Xcode. This is the file that will host our final values for the specified settings.

// Local Config 
// 
// - Update the values below as needed for your specific developer account
// - Avoid keeping the same IDs as it will clash with other developers
// - Remember to add this file to `.gitignore`

PRODUCT_BUNDLE_IDENTIFIER = com.myOtherDomain.myApps.MyOtherAppName
DEVELOPMENT_TEAM = ABCDEF
CODE_SIGN_STYLE = Automatic

To ensure this file remains local, add it to .gitignore

echo "LocalConfig.xcconfig" >> .gitignore

See gitignore documentation for more details on how that works.

4) Link the config files with the Xcode project

Within the info tab of the project, under the configuration section assign CustomConfig to the project for both Debug & Release.

5) Clear any project or target setting overrides

You may notice some settings specified within the configuration file not taking effect. This could be due to having overrides specified at the project or target level.

To investigate further, navigate to the build settings tab and select the Levels view. This view will show the final resolved setting value and where it originated from.

In the event there’s a value specified at the target or project level for the setting in question, select it and simply hit backspace or delete to clear the override. The resolved setting should then reflect the value specified in the configuration file.

Entitlements

A few additional settings like which CloudKit container to use aren’t part of the project build settings, but can be found within the entitlements file.

By default Xcode attempts to create and use a container with an id iCloud.$(CFBundleIdentifier). This should work in our case without further modification as one of the local overrides that we have already specified is a different bundle identifier. As such, we will end up with different container IDs that don’t clash.

However in the event an explicit ID is needed, a custom setting can be added to the configuration file (e.g. CLOUDKIT_CONTAINER_ID) and can then be used in the entitlements file.

// CustomConfig.xcconfig

// ...

CLOUDKIT_CONTAINER_ID = iCloud.$(CFBundleIdentifier)

// LocalConfig.xcconfig

// ...

CLOUDKIT_CONTAINER_ID = iCloud.com.mydomain.myapps.AppName

Note : Be careful when specifying explicit IDs like the CloudKit container ID and committing it into a shared repository. A different developer working on the same project can accidentally reserve your container ID before you!

What about CocoaPods?

CocoaPods by default will link its own configuration files to your project when used. Specifying our own custom configuration files is still possible, it just requires a few extra steps.

We need to ensure we reference the CocoaPods configuration files within our own using #include. A clean way to do so is to create another configuration file that links both, the CocoaPods one as well as our own and linking that to our project.

e.g.

// Debug.xcconfig
#include "../Pods/Target Support Files/Pods-MyApp/Pods-MyApp.debug.xcconfig"
#include "CustomConfig.xcconfig"

See this useful Guide by Julia Geist for details.

Conclusion

This post only covered a handful of settings, the same technique can however be applied to many other settings that may need to differ locally or even remotely on a build server. Using configuration files in this capacity isn’t a new or revolutionary idea, it’s just another use case worth highlighting!

References

Xcode Release Notes
Guide To Organizing Your iOS Debug, Development, and Release States With .xcconfig Files by Julia Geist
Using xcconfig files in Xcode to Manage signing identities by Pradeep Kumar

UIBarButtonItem & iOS 11

Sat, 21 Oct 2017 12:00:00 +0000

Overview

iOS 11 and Xcode 9 have officially been out for just over a month now and one interesting area that had some changes is the behaviour of UIBarButtonItems within UINavigationBar.

Here are my findings so far …

Changes

In summary the highlights are:

Tap areas of custom view UIBarButtonItems are now smaller
The back button’s tap area is also smaller
The back button label no longer automatically updates if the previous screen title changes
Custom views need to be auto layout friendly
Negative fixed space items no longer work and now have a minimum width of 8 points
Overriding alignmentRectInsets may cause custom views to fall outside the tap region

The following sections will dive into the details of those points.

Tap Areas

Take for example the screen below from iOS 10 with two UIBarButtonItems with custom views. Inspecting the screen in the view debugger reveals the custom views’ true size.

Their tap area is actually much larger, and is approximated by the overlaid red boxes:

On iOS 11 however, this behaviour has changed. The tap area now matches the custom view size!

This does hinder usability somewhat as users will find those buttons harder to tap. To restore the larger tap areas, the custom views now need to be sized with extra padding. An alternate solution is to create a wrapper view that has a minimum size constraint.

class WrapperView: UIView {
    let minimumSize: CGSize = CGSize(width: 44.0, height: 44.0)
    let underlyingView: UIView
    init(underlyingView: UIView) {
        self.underlyingView = underlyingView
        super.init(frame: underlyingView.bounds)
        
        underlyingView.translatesAutoresizingMaskIntoConstraints = false
        addSubview(underlyingView)
        
        NSLayoutConstraint.activate([
            underlyingView.leadingAnchor.constraint(equalTo: leadingAnchor),
            underlyingView.trailingAnchor.constraint(equalTo: trailingAnchor),
            underlyingView.topAnchor.constraint(equalTo: topAnchor),
            underlyingView.bottomAnchor.constraint(equalTo: bottomAnchor),
            heightAnchor.constraint(greaterThanOrEqualToConstant: minimumSize.height),
            widthAnchor.constraint(greaterThanOrEqualToConstant: minimumSize.width)
        ])
    }
    // ...
}

Not quite what iOS 10 offered alignment wise, but does restore the larger tap areas.

Back Button

Tap Area

Tap areas are now also smaller on back buttons when the title is really long. For example, on iOS 10 the back button had a generous minimum size and tap area.

While on iOS 11 it has a much smaller size and tap area. What’s worse is it looks like the title of the current screen is the back button’s label.

One option to prevent this scenario from occurring is to manually set a backBarButtonItem on the previous screen.

navigationItem.backBarButtonItem = UIBarButtonItem(title: "First Screen", style: .plain, target: nil, action: nil)

This solution isn’t ideal however for several reasons:

If we know what the titles of all our screens are in advance, we’d need to “litter” back buttons in screen’s that come prior to them.
If we don’t know the titles in advance, we’d need to set it everywhere.
We’d loose out on the default back button’s rendering behaviour which adapts to the space available (see Apple Docs)
- < First Screen
- < Back
- <

Update: A radar was filed (36223743).

Dynamic Label Updates

Another change in behaviour in iOS 11, is the back button label itself. For example, if the first screen had a title with a count that updates dynamically

On iOS 10, if the title updates, so will the back button label

On iOS 11 however, the button label appears to be static and no longer updates automatically.

A simple fix for this issue would be to manually manage the backBarButtonItem in the first screen.

navigationItem.backBarButtonItem = UIBarButtonItem(title: "First (\(counter))", style: .plain, target: nil, action: nil)

Note: A new bar button item instance is needed each time, simply updating the title on an existing instance will not work.

Update #1: A radar was filed (35119951).

Update #2: An alternate solution is to simply “toggle” the backBarButtonItem

func updateTitle() {
    title = "First (\(counter))"
    navigationItem.backBarButtonItem = UIBarButtonItem(title: title, style: .plain, target: nil, action: nil)
    navigationItem.backBarButtonItem = nil
}

This will ensure the back button retains its default rendering behaviour (described in the previous section).

Auto Layout

UINavigationBar now leverages auto layout internally to layout its subviews including custom views. This was actually mentioned in the Updating Your Apps for iOS 11 WWDC talk earlier this year.

Inspecting the navigation bar on iOS 11 in the view debugger reveals that the buttons are now internally managed by a stack view.

Provided custom views implement the sizeThatFits and intrinsicContentSize correctly, everything should work as before.

A word of caution however, setting translatesAutoresizingMaskIntoConstraints to false on the custom view can result in ambiguous constraints when running on iOS 10 (if you still support it). This can lead to your custom views getting misplaced in the top left corner. A simple solution here is to guard that with an iOS 11 availability runtime check.

let customView = createCustomView()
if #available(iOS 11, *) {
    customView.translatesAutoresizingMaskIntoConstraints = false
}
navigationItem.rightBarButtonItem = UIBarButtonIte(customView: customView)

Custom Alignment

For those of us who needed finer control of the alignment of their custom UIBarButtonItems especially the trailing margin to the edge of the screen. Prior to iOS 11, two “tricks” were often used:

The first was using fixed a space item UIBarButtonItem(barButtonSystemItem: .fixedSpace …) with a negative width
The other was to override alignmentRectInsets on the custom view

Sadly the behaviour of both of these has changed in iOS 11

Fixed Space Items

When using custom views, the default margin applied is 16 points

Suppose we wanted to reduce that to 8 points, using a fixed space UIBarButtonItem with -8 width would achieve the desired effect on iOS 10:

let spacer = UIBarButtonItem(barButtonSystemItem: .fixedSpace, target: nil, action: nil)
spacer.width = -8
let barButtonsItems = [
    spacer,
    UIBarButtonItem(customView: createCustomButton()),
    UIBarButtonItem(customView: createCustomButton())
]
navigationItem.rightBarButtonItems = barButtonItems

Unfortunately on iOS 11 this not longer works.

Furthermore, it appears that leading and trailing fixed space items ignore any value less than 8 points. That actually makes it consistent with the behaviour fixed space items have when used in-between items.

Alignment Rect Insets

The second trick to control button alignments was to override alignmentRectInsets.

class CustomView: UIView {
    var alignmentRectInsetsOverride: UIEdgeInsets?
    override var alignmentRectInsets: UIEdgeInsets {
        return alignmentRectInsetsOverride ?? super.alignmentRectInsets
    }
    // ...
}

Setting a value of of UIEdgeInsets(top: 0, left: -8, bottom: 0, right: 8) would achieve the desired alignment for our previous example.

This somewhat still works on iOS 11, however there is a small caveat. Upon taking a closer look, it appears that a small part of the trailing item now falls outside of the internal stack view’s bounds. That part no longer receives touches, which results in reducing the tap area of that item!

Workaround

Taking a look back at our previous fixed space example on iOS 11 we discover an interesting side effect, the margin is smaller than usual:

Turns out, this occurs whenever the trailing item is a non custom view UIBarButtonItem as opposed to a custom view item.

Take for example the following non custom view UIBarButtonItems, the margin from the edge of the screen is 8 points

Versus when custom views are used, the margin is 16 points

Combining these observations, our goal of an 8 point margin for custom views can still be achieved on iOS 11. Adding a trailing fix space item will make the internal stack view have a reduced margin, then shifting the custom views using alignmentRectInsets by an offset equivalent to the fixed space width would align them to the trailing edge of the internal stack view.

func alignedBarButtonItems() -> [UIBarButtonItem] {
    let spacer = UIBarButtonItem(barButtonSystemItem: .fixedSpace, target: nil, action: nil)
    spacer.width = 8
    let barButtonsItems = [
        spacer,
        UIBarButtonItem(customView: createCustomButton(offset: spacer.width)),
        UIBarButtonItem(customView: createCustomButton(offset: spacer.width)),
        ]
    return barButtonsItems
}

func createCustomButton(offset: CGFloat = 0) -> UIButton {
    let button = CustomButton(frame: CGRect(x:0, y: 0, width: 24, height: 24))
    button.alignmentRectInsetsOverride = UIEdgeInsets(top: 0, left: -offset, bottom: 0, right: offset)
    button.translatesAutoresizingMaskIntoConstraints = false
    return button
}

Though quite interesting, this workaround only works up to 8 points, anything further will be outside the stack view bounds. In addition it relies on a side effect of undocumented UIKit behavior that may very well change in the future (much like the negative fixed space trick).

On the Developer Forums there are a few suggestion for other workarounds to eliminate the internal stack view margins completely - though they do require a custom UINavigationBar subclass and some medeling with it’s internals which is not ideal either.

Conclusion

Who would have thought there would be this much to write about UIBarButtonItems, but here we are. Feel free to leave a comment if you find any other issues or spot any elegant solutions!

Styling In Storyboards Using Swift

Fri, 10 Mar 2017 19:00:00 +0000

Overview

Storyboards are fantastic for creating screens fairly quickly. The final appearance of those screens however may differ greatly at runtime. This is to be somewhat expected, as many of our apps will use one or more custom UI components in addition to leveraging a distinct theme and color palette that may be defined in code.

In this post I will be sharing a technique I found that can help adopt custom styling within a Storyboard, by using IBDesignable, IBInspectable and reflection in Swift!

Sample Use Case

Let’s consider a sample use case. The goal is to produce the following screen:

Our designers have provided us with the following color palette:

(Palette generated by coolors.co)

Which we can use to style our fancy UIButton subclass RoundedRectButton to achieve the desired design.

class RoundedRectButton: UIButton {

    var cornerRadius: CGFloat = 4 {
        didSet {
            updateStyle()
        }
    }

    var imageBackgroundColor: UIColor? {
        didSet {
            updateStyle()
        }
    }

    func updateStyle() {
        if let color = imageBackgroundColor {
            setBackgroundImage(SimpleImages.roundedRect(radius: cornerRadius, color: color), for: .normal)
        }
    }
}

Basic Solution

One common way to achieve this is to add three buttons in interface builder, change their class type to RoundedRectButton and connect them to IBOutlets in our view controller subclass. We can then apply our custom styling when the view loads:

class ButtonsViewController: UIViewController {

    @IBOutlet var redButton: RoundedRectButton!
    @IBOutlet var orangeButton: RoundedRectButton!
    @IBOutlet var greenButton: RoundedRectButton!

    override func viewDidLoad() {
        super.viewDidLoad()

        // Apply custom theme colors
        view.backgroundColor = Theme.palette.darkBlue

        redButton.imageBackgroundColor = Theme.palette.red
        orangeButton.imageBackgroundColor = Theme.palette.orange
        greenButton.imageBackgroundColor = Theme.palette.green
    }
}

Where we have defined our color palette as:

struct Theme {
    static let palette = Palette()
}

struct Palette {
    let red = UIColor(red: (217.0/255.0), green: (31.0/255.0), blue: (54.0/255.0), alpha: 1)
    let orange = UIColor(red: (245.0/255.0), green: (102.0/255.0), blue: (23.0/255.0), alpha: 1)
    let green = UIColor(red: (168.0/255.0), green: (194.0/255.0), blue: (87.0/255.0), alpha: 1)
    let darkBlue = UIColor(red: (44.0/255.0), green: (48.0/255.0), blue: (71.0/255.0), alpha: 1)
}

A helper method or extension on UIColor can tidy up all those inline calculations, but this will do for now.

Leveraging IBDesignable & IBInspectable

IBDesignable and IBInspectable allow custom UI components to be rendered and customized in interface builder (Nate Cook did a great write up on them here). They are exactly what we need to get our views in interface builder looking closer to final result.

@IBDesignable
class RoundedRectButton: UIButton {

    @IBInspectable var cornerRadius: CGFloat = 4 {
        didSet {
            updateStyle()
        }
    }

    @IBInspectable var imageBackgroundColor: UIColor? {
        didSet {
            updateStyle()
        }
    }

    func updateStyle() {
        if let color = imageBackgroundColor {
            setBackgroundImage(SimpleImages.roundedRect(radius: cornerRadius, color: color), for: .normal)
        }
    }
}

By making those tweaks, our buttons can now be customized and rendered directly from within interface builder!

That’s great but what about our color palette?

One option we have is replicate the palette in Xcode (see Natasha’s post).

Sadly that palette is fairly static and can’t be exposed to the code should we need to reference the colors there. Additionally, any visual overhauls that result in tweaking our master palette wouldn’t automatically be picked up by our buttons!

Exposing Our Palette

Ideally we’d like to define some enum we expose as an IBInspectable, unfortunately IBInspectable does not yet support enums.

We can however workaround this by using IBInspectable compatible values and map them to our palette. For example, we can map our colors using a String:

extension Palette {
    func color(from string: String) -> UIColor? {
        switch string {
            case "red": return red
            case "orange": return orange
            case "green": return green
            case "darkBlue": return darkBlue
            default: return nil
        }
    }
}

A new inspectable property can then be added to our button:

 @IBInspectable var paletteBackgroundColor: String? {
        didSet {
            imageBackgroundColor = paletteBackgroundColor.flatMap{ Theme.palette.color(from: $0) }
        }
    }

This achieves what we’re after! The best part is, should we ever change the palette color values, everything will automatically pick it up!

Automatically Mapping Colors

This seems reasonable given we only have four colors, but what if our palette grows to 30 colors and what if we wanted to adopt this approach for fonts and other properties too? This will certainly become unmanageable and quite error prone!

Luckily, we can make our solution more scalable using reflection in Swift (yes Swift does support some reflection capabilities!). Using Mirror we can construct a dictionary with property names and their values [String: Any]:

class Reflection {
    /// Return a dictionary representation of an item's member variables
    /// in the form of key value pairs
    static func propertiesAndValues(of item: Any) -> [String: Any] {
        let type = Mirror(reflecting: item)
        var properties = [String: Any]()
        for child in type.children {
            if let key = child.label {
                properties[key] = child.value
            }
        }

        return properties
    }
}

The palette can then be updated to leverage the reflection utility:

extension Palette {
    func color(from string: String) -> UIColor? {
        let colorsMap = Reflection.propertiesAndValues(of: self)
        return colorsMap[string] as? UIColor
    }
}

Now we can add as many colors as we want without needing to manually update the mapping.

Making It Generic

Our solution can actually be made more generic, we can define a protocol with a generic function to return a MemeberType for a given String and provide a default implementation in a protocol extension:

protocol StringConvertibleMembers {
    func member<MemberType>(from string: String) -> MemberType?
}

extension StringConvertibleMembers {
    func member<MemberType>(from string: String) -> MemberType? {
        let keyValues = Reflection.propertiesAndValues(of: self)
        return keyValues[string] as? MemberType
    }
}

By making our Palette adopt the StringConvertibleMembers protocol, it automatically gets this behaviour!

extension Palette: StringConvertibleMembers {

}

Finally, the our button is updated to use the new generic method:

@IBInspectable var paletteBackgroundColor: String? {
        didSet {
            imageBackgroundColor = paletteBackgroundColor.flatMap{ Theme.palette.member(from: $0) }
        }
    }

This technique can now be used with any property type and not just UIColor.

Conclusion

This solution is far from perfect as it is still error prone, mistyping the color name can easily be missed and the compiler won’t be able to assist us there. Nevertheless it can help us get the most out of Storyboards, here’s the final outcome once we style all our buttons and our main view.

This really becomes powerful when you have Style structures to describe several styling properties together, for example:

struct LabelStyle {
    var color: UIColor
    var font: UIFont
}

struct LabelStyles {
    let title = Style(color: Theme.palette.darkBlue, font: UIFont.preferredFont(forTextStyle: .title1))
    let subtitle = Style(color: Theme.palette.darkBlue, font: UIFont.preferredFont(forTextStyle: .title3))
    ...
}

extension LabelStyles: StringConvertibleMembers {

}

@IBDesignable
class StyledLabel: UILabel {
    var style: LabelStyle? {
        didSet {
            updateStyle()
        }
    }

    @IBInspectable var styleName: String? {
        didSet {
            style = styleName.flatMap{ Theme.styles.member(from: $0) }
        }
    }

    func updateStyle() {
        if let style = style {
            font = style.font
            textColor = style.color
        }
    }
}

Happy Styling!

Cleaner asynchronous tests with XCTest

Sun, 26 Feb 2017 12:00:00 +0000

Overview

This week I participated at a code dojo at work organised by @mikeweller where the theme was test driven development, more specifically about using test doubles to test our components.

The exercise revolved around designing an oxygen regulator for a space ship that needs to ensure oxygen levels are within a specified range. The catch was, we did not yet have access to any of the other components of the system as they were still in development (such as the oxygen meter and alarm).

For the purposes of this post, I will focus on a subset of the requirements and use it to highlight some testing tips I’ve come across especially around writing cleaner asynchronous tests.

Requirements

The regulator will have a tick() method that is regularly called
When the oxygen levels are below 20.3% an alarm needs to be triggered

Types

With the information we have so far, the only type requirement was for the regulator to have a tick() method, we also know our minimum oxygen level.

protocol Regulator {
    func tick()
}

struct Config {
    var minLevel: Double
}

extension Config {
    static var defaultConfig: Config {
        return Config(minLevel: 0.203)
    }
}

For our other dependencies however, there wasn’t anything concrete, as such we had to come up with our own

protocol Alarm {
    func notify()
}

protocol Meter {
    var level: Double { get }
}

The Test

At a high level our test needs to look like this:

func testAlarmIsTriggeredWhenLevelsAreLow() {  
    // Verify the alarm is not triggered

    // Set Meter level lower than the minimum level

    // Tick the regulator

    // Verify the alarm was triggered
}

A first pass of a test could look like this

var lowLevel: Double {
    return Config.defaultConfig.minLevel - 0.01
}

func testAlarmIsTriggeredWhenLevelsAreLow() {  
    let alarm = MockAlarm()
    let meter = MockMeter()
    let regulator = OxygenRegulator(meter: meter, alarm: alarm)

    XCTAssertFalse(alarm.notified)

    meter.level = lowLevel
    regulator.tick()

    XCTAssertTrue(alarm.notified)
}

Where our mocks are:

class MockMeter: Meter {
    var level: Double = Config.defaultConfig.minLevel
}

class MockAlarm: Alarm {
    var notified = false
    func notify() {
        notified = true
    }
}

Asynchronous Cases

The mock alarm we used utilises a boolean to keep track of its state, which works well in the synchronous cases but if our component is asynchronous this simple mock won’t quite cut it. A closure would be more suitable.

class MockAlarm: Alarm {
    var didNotify: (()->Void)?
    func notify() {
        didNotify?()
    }
}

This would allow the usage of XCTestExpectation to wait until the alarm is triggered.

func testAsyncAlarmIsTriggeredWhenLevelsAreLow() {
    let alarm = MockAlarm()
    let meter = MockMeter()
    let regulator = OxygenRegulator(meter: meter, alarm: alarm)

    let e = expectation(description: "Alarm should be triggered")
    alarm.didNotify = {
        e.fulfill()
    }

    meter.level = lowLevel
    regulator.tick()

    waitForExpectations(timeout: 1, handler: nil)
}

Cleaner Asynchronous Cases

So far everything covered is pretty straight forward, however as more and more requirements around when to trigger the alarm come in we’ll find quite a bit of repetition around setting up the expectations and waiting. While nothing is wrong with that, there are a few steps that can be taken to clean it up.

Helper Methods

We can create a helper method that does all the expectations setup:

func verifyAlarmTriggers(alarm: MockAlarm,
                         file: StaticString = #file,
                         line: UInt = #line,
                         when action: ()->Void) {
    // Setup expectations
    let e = expectation(description: “Alarm is triggered")
    alarm.didNotify = {
        e.fulfill()
    }

    // Perform action
    action()

    // Wait for expectations
    waitForExpectations(timeout: 1) { error in
        if let _ = error {
            XCTFail(“Alarm was not triggered", file: file, line: line)
        }
    }
}

Which would allow us to refactor our test to look like this:

func testAsyncAlarmIsTriggeredWhenLevelsAreLow() {

    let alarm = MockAlarm()
    let meter = MockMeter()
    let regulator = OxygenRegulator(meter: meter, alarm: alarm)

    verifyAlarmTriggers(alarm: alarm) {
        meter.level = lowLevel
        regulator.tick()
    }
}

If you haven’t run into #file & #line before, they are your new best friends when creating helper test methods! They will capture the file and line number of the caller which can then be passed to the XCTest suite of methods and end up showing the error at that particular line instead of the helper!

Note the when closure parameter is placed at the end of the parameters list of our helper method. At first glance it may look odd as its preceded by the file and line parameters with default values, but doing so allows us to leverage the trailing closure syntax.

Using `setup()`

This has already reduced quite a bit of repetition, but we can reduce it even further by leveraging setup() to setup our components:

var alarm: MockAlarm!
var meter: MockMeter!
var regulator: OxygenRegulator!

override func setUp() {
    super.setUp()

    alarm = MockAlarm()
    meter = MockMeter()
    regulator = OxygenRegulator(meter: meter, alarm: alarm)
}

Seeing our mocks are now a property of the test case, our helper method would be able to access the alarm mock without needing it to be passed in:

func verifyAlarmTriggers(file: StaticString = #file,
                         line: UInt = #line,
                         when action: ()->Void) {
    // Setup expectations
    let e = expectation(description: “Alarm is triggered")
    alarm.didNotify = {
        e.fulfill()
    }

    // Perform action
    action()

    // Wait for expectations
    waitForExpectations(timeout: 1) { error in
        if let _ = error {
            XCTFail(“Alarm was not triggered", file: file, line: line)
        }
    }
}

Finally our test can now be reduced down to this:

func testAsyncAlarmIsTriggeredWhenLevelsAreLow() {
    verifyAlarmTriggers {
        meter.level = lowLevel
        regulator.tick()
    }
}

Conclusion

There are actually a few frameworks out there that introduce a wide variety of utilities to help you write cleaner tests, for example Nimble has a few asynchronous helpers like toEventually and toEventuallyNot. However if you are not quite ready to adopt a third party framework for whatever reason, there’s nothing stopping you from writing cleaner tests with XCTest.

Happy testing!

What's really new with UI Testing in iOS 10

Sun, 02 Oct 2016 10:00:00 +0000

Overview

Now Xcode 8 is out it was time to migrate some UI testing code over to Swift 3 as well ensure all the tests continued to work in iOS 10. Doing so uncovered some interesting changes in behaviour that weren’t necessarily advertised in this year’s WWDC (or perhaps I just missed them).

API wise, there hasn’t been any new additions or deprecations, on the surface it appears unchanged. The behaviour however, has changed slightly. Here are my findings so far:

1) Hidden elements no longer exist
2) Elements beneath modals are no longer hittable
3) Landscape coordinates are inverted
4) Tests are slower!

1) Hidden elements no longer exist

In the past (and by past I mean Xcode 7 & iOS 9 days) all elements in the view hierarchy were available to query. This included hidden and non hidden elements. They all “exist” and the only distinction between them was whether they were “hittable”.

for example take this simple story board, with three buttons.

Visible
Hidden
- hidden = true
Alpha 0
- alpha = 0

Running the following test passes when running on iOS 9

    func testVisibility() {

        let app = XCUIApplication()

        XCTAssertTrue(app.buttons["Visible"].exists)
        XCTAssertTrue(app.buttons["Hidden"].exists)
        XCTAssertTrue(app.buttons["Alpha 0"].exists)
    }

In iOS 10 however, hidden elements no longer exist, they are completely omitted from the accessibility tree exposed to the test. Oddly enough, the same occurs for elements with an alpha or frame of zero.

2) Elements beneath modals are no longer hittable

Arguably this used to be a bug in the previous iteration of the API. Whenever a modal element appears on screen (a popover or action sheet on iPad for example) visible elements beneath the modal were still hittable.

Suppose our app now presents an action sheet on tapping the “Visible” button, the following test passes when running on iOS 9:

    func testActionSheets() {
        let app = XCUIApplication()
        let button = app.buttons["Visible"]

        button.tap()
        XCTAssertTrue(button.isHittable)
    }

In iOS 10 however, the test above will fail due to the button not being hittable.

This brings on an interesting question, how does one dismiss an action sheet or popover on iPad ??

It’s handy to record tests or inspect the debug information of XCUIApplication. You’ll find the overlay background is an accessibility element of its own with an identifier of “PopoverDismissRegion”.

As such dismissing popovers can be achieved by simply tapping that element:

let popoverDismissRegion = app.otherElements["PopoverDismissRegion"]
popoverDismissRegion.tap()

If you find you need to do this often, adding this to an extension may be useful:

extension XCUIApplication {
    func dismissPopover() {
       otherElements["PopoverDismissRegion"].tap()
    }
}

3) Landscape coordinates are inverted

This is probably a regression in iOS 10, XCUICoordinates don’t seem to respect orientation changes any more.

for example, suppose our app now draws touches and we have the following test code:

   func testCoordinates() {
        let app = XCUIApplication()
        let v = app.otherElements["view.container"]

        XCUIDevice.shared().orientation = .landscapeLeft

        let c = v.coordinate(withNormalizedOffset: CGVector(dx: 0, dy: 0.5))
        let d = c.withOffset(CGVector(dx: 100, dy: 0))
        c.press(forDuration: 0.5, thenDragTo: d)
    }

in iOS 9, regardless of orientation a horizontal line is drawn as you’d expect from the centre left edge of the screen.

on iOS 10 however, when in landscape the coordinates are inverted.

The current workaround is to ensure portrait orientation when performing the test or to manually account for orientation changes when dealing with coordinates.

4) Tests are slower!

This was one of the saddest discoveries which I hope will be improved. Tests running on iOS 10 appear to be a little slower than those run on iOS 9.

Let’s take a test that simply taps a button a 100 times:

    func testSpeed() {
        let app = XCUIApplication()
        let button = app.buttons["Visible"]

        for _ in 0..<100 {
            button.tap()
        }
    }

When running in iOS 10 Simulator:

iPad Air 2: 177 Seconds
iPhone 6s: 141 Seconds

When running in iOS 9 Simulator:

iPad Air 2: 152 Seconds
iPhone 6s: 113 Seconds

These figures will vary based on the machine the tests are run on, however iOS 10 results are consistently slower than iOS 9. What’s odd here is, you’d think the changes made for item 1 above would mean an improved performance due to having less elements to process now hidden ones are taken out of the equation.

While a small difference, it does add up over a large number of tests.