matrixprojects.net - ios Posts

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))
        }
    }
}

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.

Triggering Events while UI Testing

Sun, 28 Aug 2016 20:00:00 +0000

Overview

In this post, I’ll be sharing two techniques to trigger events in your application while performing UI tests in XCTest without needing to do so via the UI.

Why?

My previous posts on this topic go over a slightly different style of UI testing that is not exactly full integration testing, but rather a smaller subset of it using mocks and stubs. This allows testing the UI without needing to ever hit the network or navigate through a labyrinth of steps to reach a particular testing check point. Triggering events without using the UI help further these goals.

Example

Taking our example from last time (a login screen backed by a view model). Suppose we now would like to add a welcome prompt to greet first time users.

  protocol LoginViewModel {
    var showWelcomePrompt: (() -> Void)? { get set }
    ...
  }

The login view controller displays an alert controller with a welcome message when told so by it’s view model:

  class LoginViewController: UIViewController {

    var viewModel: LoginViewModel?
    ...
    override func viewDidLoad() {
        super.viewDidLoad()

        // bind to view model events
        //
        // best to use an FRP framework like RxSwift, SwiftBond etc...
        // for demo purposes a simple closure will suffice
        viewModel?.showWelcomePrompt = { [weak self] in
            let alert = UIAlertController(title: "Welcome", message: "Welcome to this awesome app!", preferredStyle: .Alert)

            let close = UIAlertAction(title: "Close", style: .Cancel, handler: nil)
            alert.addAction(close)

            self?.showViewController(alert, sender: self)
        }
    }
    ...
}

The logic of when best to display the dialog based on various factors can be easily unit tested in the view model (see the sample GitHub project for an example). In addition, it would be great to have a UI test that verifies the login screen is in fact displaying this welcome message appropriately. In this example, gaining the ability to trigger events that aren’t necessarily linked to UI components like a button would make UI testing much simpler.

Establishing Communication

Before we dive in, here’s a quick recap on how UI testing works on iOS. The UI testing code is run in a separate target (it actually is a separate app) that spins up your main application target and interacts with it as a user would, using the UI. Out of the box there isn’t any other form of communication available post launch.

The test target is a full fledged application, it has access to the same APIs available to any normal application. As such building something to establish communication is fairly possible.

Technique #1: Darwin Notifications

The first technique I’d like to cover is inspired by the MMWormhole project and is hidden deep within CoreFoundation.

Have you ever heard of CFNotificationCenter? more specifically DarwinNotifyCenter? turns out this low level API allows sending notifications between applications! that’s right … between applications!! Before we all get too excited, there is a caveat and it’s a big one. Notifications sent from DarwinNotifyCenter can’t contain any additional data (such as a userInfo dictionary like in NSNotifcationCenter).

That being said, even in this restrictive form, for the purposes of triggering events in the main application from a UI test it is still quite valuable. As such a basic “Beeper” utility can be created. Let’s sketch that up first with a protocol to see how it can be leveraged

typealias BeepHandler = () -> Void

protocol Beeper {
    func beep(identifier: String)
    func register(identifier: String, handler: BeepHandler)
    func unregister(identifier: String)
}

Continuing with our example, we can configure the app to use a testing stub view model that will trigger the welcome prompt event upon receiving a “beep” with the appropriate identifier.

  protocol LoginViewModel {
    var showWelcomePrompt: (() -> Void)? { get set }
    // ...
  }

 class TestingLoginViewModel: LoginViewModel {

    var showWelcomePrompt: (() -> Void)? = nil
    let beeper: Beeper = DarwinNotificationCenterBeeper()

    init() {
        beeper.register(BeeperConstants.triggerWelcomePrompt) { [unowned self] in
            self.showWelcomePrompt?()
        }
    }
   ...
  }

The UI test can then be written:

    func testWelcomePrompt() {
        launch(usingTestingViewModel: true)
        
        let alert = app.alerts["Welcome"]
        XCTAssertFalse(alert.exists)
        
        beeper.beep(identifier: BeeperConstants.triggerWelcomePrompt)
        XCTAssertTrue(alert.waitForExistence(timeout: 2))
        
        alert.buttons["Close"].tap()
        XCTAssertFalse(alert.exists)
    }

As for the concrete implementation of the Beeper:

class DarwinNotificationCenterBeeper: Beeper {
    
    private let darwinNotificationCenter: CFNotificationCenter
    private let prefix: String
    private var handlers = [String: BeepHandler]()
    
    init(prefix: String = "net.mxpr.utils.beeper") {
        darwinNotificationCenter = CFNotificationCenterGetDarwinNotifyCenter()
        self.prefix = prefix.appending(".")
    }
    
    deinit {
        CFNotificationCenterRemoveObserver(darwinNotificationCenter,
                                           rawPointerToSelf,
                                           nil,
                                           nil)
        
    }

    private func notificationName(from identifier: String) -> String {
        return "\(prefix)\(identifier)"
    }

    private func identifier(from name: String) -> String {
        guard let prefixRange = name.range(of: prefix) else {
            return name
        }
        return String(name[prefixRange.upperBound...])
    }
    
    fileprivate func handleNotification(name: String) {
        let handlerIdentifier = identifier(from: name)
        if let handler = handlers[handlerIdentifier] {
            handler()
        }
    }
    
    private var rawPointerToSelf: UnsafeRawPointer {
        return UnsafeRawPointer(Unmanaged.passUnretained(self).toOpaque())
    }
    
    // MARK: - Beeper
    
    func beep(identifier: String) {
        let name = notificationName(from: identifier)
        CFNotificationCenterPostNotification(darwinNotificationCenter,
                                             CFNotificationName(name as CFString),
                                             nil,
                                             nil,
                                             true)
    }
    
    func register(identifier: String, handler: @escaping BeepHandler) {
        handlers[identifier] = handler
        let name = notificationName(from: identifier)
        CFNotificationCenterAddObserver(darwinNotificationCenter,
                                        rawPointerToSelf,
                                        handleDarwinNotification,
                                        name as CFString,
                                        nil,
                                        .deliverImmediately)
        
    }
    
    func unregister(identifier: String) {
        handlers[identifier] = nil
        let name = notificationName(from: identifier)
        let cfNotificationName = CFNotificationName(name as CFString)
        CFNotificationCenterRemoveObserver(darwinNotificationCenter,
                                           rawPointerToSelf,
                                           cfNotificationName,
                                           nil)
    }
}

fileprivate func handleDarwinNotification(notificationCenteR: CFNotificationCenter?,
                                          observer: UnsafeMutableRawPointer?,
                                          notificationName: CFNotificationName?,
                                          unusedObject: UnsafeRawPointer?,
                                          unusedUserInfo: CFDictionary?) -> Void {
    guard let observer = observer,
        let notificationName = notificationName else {
            return
    }
    let beeper = Unmanaged<DarwinNotificationCenterBeeper>.fromOpaque(observer).takeUnretainedValue()
    let name = (notificationName.rawValue as String)
    beeper.handleNotification(name: name)
}

A sample project containing all the sources can be found on GitHub.

Technique #2: HTTP Server

A far more superior technique involves setting up a local http server to run in your main application (when testing). This will allow the main application to receive requests to manipulate its state and even send back information to the test target in the response.

A local http server can be easily setup using open source frameworks like Swifter. The method previously described can be followed to achieve similar advances in testing.

One fairly extensive adaptation of this technique can be seen in SBTUITestTunnel by @tomascamin. It includes various helpers and utilities geared specifically at UI Testing.

Conclusion

UI Testing is awesome, and can be more awesome once you find new ways to leverage it. I’ll add my usual disclaimer, UI testing isn’t a replacement to unit testing, it’s just another tool in our toolbox and should be used where appropriate.

Happy Testing!

Links

Update (25th-Nov-2018): Code snippets updated for Swift 4.2 syntax

Testing analytics on iOS with XCTest

Sun, 03 Apr 2016 18:00:00 +0000

Overview

Have you ever pushed a release where you accidentally removed some of your analytics logging code or just forgot to add it in the first place? In this post I’ll be sharing two techniques for testing analytics in an iOS App to help you avoid these unfortunate scenarios.

To clarify what I mean by analytics, I’m talking about tools like GoogleAnalytics that provide you with insights on how users use your app. For example, which are the most and least used screens. This can help inform you where to focus your development efforts.

Concepts

Unit Testing

Unit testing can easily be achieved if your app adopts an MVVM architecture.

The concept is simple, we can move the analytics logging to our ViewModel. This is perhaps questionable move, as analytics logging usually takes place at the UI level. It’s worth considering either way for the benefits of testing.

Being a model, the ViewModel can easily be tested without relying on the simulator or being in a view hierarchy. Testing can commence in the usual manner, we can provide the ViewModel with a mock version of our analytics logger and verify the appropriate calls are made.

In summary:

Create a ViewModel and pass in MockAnalytics instead of the real implementation
Perform the appropriate actions on the ViewModel (that would have originated from button taps when bound with a ViewController)
Validate MockAnalytics is called with appropriate events

UI Testing

An alternate or additional method of testing can involve ui testing. This ensures the UI elements are hooked up appropriately (see my previous post for more examples on this method).

Now the challenge here is, currently there is no direct way to communicate between the main app and the ui test target other than through the UI. With that limitation in mind, here’s a solution I found. The UI Tests can inspect elements, ~~hidden or otherwise on screen~~ and read their accessibility information. As such, an invisible view can be added (during testing) which can have it’s accessibilityValue updated each time we log any analytics.

As such testing can be conducted in the following manner:

Tap a button
Verify the accessibilityValue of our special view has been updated accordingly
Repeat for all the elements of interest

That’s pretty much it! The following section goes into the details of both concepts using a demo app.

Detailed Examples

Demo App

To demo both techniques, we’ll use a simple App with a single login screen:

For our analytics requirements we want to log the following events:

When the screen is viewed
When users tap the Login button
When users tap the Sign Up button

Unit Testing

Abstracting Analytics

First, let’s ensure we have a protocol for our Analytics so that we can easily replace implementations

protocol Analytics {
    func log(screen screen: String)
    func log(event event: String, action: String)
}

For the purposes of this demo, the non-testing implementation will be a ConsoleAnalytics version. This of course can be replaced with any other implementation - one backed by GoogleAnalytics for example.

class ConsoleAnalytics: Analytics {
    func log(screen screen: String) {
        print("[analytics] screen view: \(screen)")
    }

    func log(event event: String, action: String) {
        print("[analytics] event: \(event) - action: \(action)")
    }
}

The ViewModel

Here’s a basic LoginViewModel that logs the appropriate analytics when it’s actions are performed:

struct LoginViewModel {
    let analytics: Analytics

    func wakeup() {
        analytics.log(screen: AnalyticsScreens.Login)
    }

    func login() {
        analytics.log(event: AnalyticsEvents.Login, action: AnalyticsActions.Tap)
    }

    func signup() {
        analytics.log(event: AnalyticsEvents.SignUp, action: AnalyticsActions.Tap)
    }
}

The ViewController

With the view model hooked up to our analytics, we can bind it to our LoginViewController. I recommend looking up frameworks like SwiftBond and RxSwift, however for the purposes of this demo, they are not needed.

class LoginViewController: UIViewController {
    // MARK: Dependencies
    var viewModel: LoginViewModel?

    // MARK: UIViewController overrides
    override func viewDidAppear(animated: Bool) {
        super.viewDidAppear(animated)
        viewModel?.wakeup()
    }

    // MARK: - Actions
    @IBAction func didTapLogin(sender: UIButton) {
        viewModel?.login()
    }

    @IBAction func didTapSignUp(sender: UIButton) {
        viewModel?.signup()
    }
}

The LoginViewModel will need to be injected to the LoginViewController, an example of how to achieve this can be seen in the demo app on GitHub

Mock Analytics

Next we’ll need to create MockAnalytics that we can use in place of our ConsoleAnalytics for unit testing:

class MockAnalytics: Analytics {
    var didLogScreen: ((String) -> Void)?
    var didLogEvent: ((_ event: String, _ action: String) -> Void)?
    
    // MARK: - Analytics
    func log(screen: String) {
        didLogScreen?(screen)
    }
    
    func log(event: String, action: String) {
        didLogEvent?(event, action)
    }
}

Helpers

To make our testing more readable and streamlined, we can add a few helper methods:

class LoginViewModelTests: XCTestCase {
    
    var mockAnalytics: MockAnalytics!
    var viewModel: LoginViewModel!
    
    override func setUp() {
        super.setUp()
        
        mockAnalytics = MockAnalytics()
        viewModel = LoginViewModel(analytics: mockAnalytics)
    }

    // MARK: - Helpers

    func verifyAnalytics(screen: String, when block:(()->Void), line: UInt = #line, file: StaticString = #file) {
        
        // setup expectations
        let e = expectation(description: "screen view analytics should be logged")
        mockAnalytics.didLogScreen = { loggedScreen in
            e.fulfill()
            XCTAssertEqual(loggedScreen, screen, file: file, line: line)
        }
        
        // perform actions
        block()
        
        // wait for expectations
        waitForExpectations(timeout: 1) { error in
            if let _ = error {
                XCTFail("Failed to log screen view analytics", file: file, line: line)
            }
        }
    }
    
    func verifyAnalytics(event: String, action: String, when block:(()->Void), line: UInt = #line, file: StaticString = #file) {
        
        // setup expectations
        let e = expectation(description: "event analytics should be logged")
        mockAnalytics.didLogEvent = { loggedEvent, loggedAction in
            e.fulfill()
            XCTAssertEqual(loggedEvent, event, file: file, line: line)
            XCTAssertEqual(loggedAction, action, file: file, line: line)
        }
        
        // perform actions
        block()
        
        // wait for expectations
        waitForExpectations(timeout: 1) { error in
            if let _ = error {
                XCTFail("Failed to log event analytics", file: file, line: line)
            }
        }
    }
}

Thanks to @masilotti for sharing his tips on how to get XCTest helper methods to display errors at the correct line when a failure occurs!

The idea behind these helpers is to allow us to state which analytics we expect to occur when we perform an action within a closure.

Tests

Finally, our clean unit tests:

class LoginViewModelTests: XCTestCase {
    // ...

    // MARK: - Tests

    func testAnalytics() {
        
        verifyAnalytics(screen: AnalyticsScreens.Login, when: {
            viewModel.wakeup()
        })
        
        verifyAnalytics(event: AnalyticsEvents.Login, action: AnalyticsActions.Tap, when: {
            viewModel.login()
        })
        
        verifyAnalytics(event: AnalyticsEvents.SignUp, action: AnalyticsActions.Tap, when: {
            viewModel.signup()
        })
    }
    // ...
}

UI Testing

Abstracting Analytics

We have to follow the same steps we did when unit testing and ensure we have an Analytics protocol abstraction.

We can now make a dummy AnalyticsDebugger implementation which will be filled in later on:

class AnalyticsDebugger: Analytics {
    func log(screen screen: String) {
        //TODO:
    }

    func log(event event: String, action: String) {
        //TODO:
    }
}

With those implementations, our app delegate can be updated to swap out the appropriate implementation based on our current mode.

class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    // MARK: -
    var analytics: Analytics!
    
    func setup() {
        let defaults = UserDefaults.standard
        let uiTesting = defaults.bool(forKey: "ui-testing")
        
        if uiTesting {
            analytics = AnalyticsDebugger()
        } else {
            analytics = ConsoleAnalytics()
        }
    }
    
    // MARK: - UIApplicationDelegate
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        window = UIWindow(frame: UIScreen.main.bounds)
        
        setup()
        
        let storyboard = UIStoryboard(name: "Main", bundle: nil)
        
        let initialViewController = storyboard.instantiateInitialViewController() as! LoginViewController
        initialViewController.viewModel = LoginViewModel(analytics: analytics)
        
        self.window?.rootViewController = initialViewController
        self.window?.makeKeyAndVisible()
        
        return true
    }
    // ...
}

Analytics Debugger

Now we need to create our special debugView which will act as our bridge to the ui test target.

class AnalyticsDebugger: Analytics {
    lazy var debugView: UIView = {
        let view = UIView(frame: CGRect(x: 0, y:0, width: 1, height: 1))
        view.accessibilityIdentifier = TestingConstants.AnalyticsDebugger
        view.accessibilityValue = ""
        return view
    }()    
    // ...
}

For it to be seen by the ui test target, it needs to be added to the view hierarchy. The least obtrusive way to do this is to add it as a subview of our main window in the AppDelegate. This can be achieved by updating our setup() method as follows:

class AppDelegate: UIResponder, UIApplicationDelegate {
    // ...
    func setup() {
        let defaults = UserDefaults.standard
        let uiTesting = defaults.bool(forKey: "ui-testing")
        
        if uiTesting {
            let analyticsDebugger = AnalyticsDebugger()
            window?.addSubview(analyticsDebugger.debugView)
            analytics = analyticsDebugger
        } else {
            analytics = ConsoleAnalytics()
        }
    }
    // ...
}

We can verify our setup works by doing a quick test:

class LoginTests: XCTestCase {
    var app: XCUIApplication!

    override func setUp() {
        super.setUp()

        app = XCUIApplication()
        launch(app)

        // In UI tests it is usually best to stop immediately when a failure occurs.
        continueAfterFailure = false
    }

    override func tearDown() {
        // Put teardown code here. This method is called after the invocation of each test method in the class.
        super.tearDown()
    }

    // MARK: - Helpers
    func launch(app: XCUIApplication) {
        app.launchArguments = ["-ui-testing", "YES"]
        app.launch()
    }

    // MARK: - Tests
    func testAnalyticsDebuggerExists() {
        let analyticsDebugger = app.otherElements[TestingConstants.AnalyticsDebugger]
        XCTAssertTrue(analyticsDebugger.exists)
    }
}

Analytics Coder

Great, we have built our pipeline, now it’s time to fill in some blanks. We need to a mechanism to encode and decode our analytics to and from a string as the accessibilityValue type is a string. A simple option is to encode an analytics entry or record to a json string and decode it on the other end.

We’ll need some generic structure to house these records:

enum AnalyticsRecordType: String, Codable {
    case screen
    case event
}

struct AnalyticsRecord: Codable, Equatable {
    let type: AnalyticsRecordType
    let identifier: String
    let data: String?
}

This of course can be customized to suit the nature of the analytics being tested. As for the encoding and decoding aspect, here’s a basic implementation we can use:

protocol AnalyticsCoder {
    func encode(_ records: [AnalyticsRecord]) -> String
    func decode(_ string: String) -> [AnalyticsRecord]
}

class JSONAnalyticsCoder: AnalyticsCoder {
    func encode(_ records: [AnalyticsRecord]) -> String {
        let jsonData = try? JSONEncoder().encode(records)
        let jsonString = jsonData.flatMap { String(data: $0, encoding: .utf8) }
        return jsonString ?? ""
    }
    
    func decode(_ string: String) -> [AnalyticsRecord] {
        let data = string.data(using: .utf8)
        let records = data.flatMap { try? JSONDecoder().decode([AnalyticsRecord].self, from: $0) }
        return records ?? []
    }
}

With our coder implementation completed, we can now update the AnalyticsDebugger:

class AnalyticsDebugger: Analytics {  
    // ...
    
    private let encoder: AnalyticsCoder
    init(encoder: AnalyticsCoder) {
        self.encoder = encoder
    }
    
    // MARK: - Analytics
    func log(screen: String) {
        let record = AnalyticsRecord(type: .screen, identifier: screen, data: nil)
        log(record: record)
    }
    
    func log(event: String, action: String) {
        let record = AnalyticsRecord(type: .event, identifier: event, data: action)
        log(record: record)
    }
    
    // MARK: - Private
    private func log(record: AnalyticsRecord) {
        var records = encoder.decode(debugView.accessibilityValue ?? "")
        records.append(record)
        debugView.accessibilityValue = encoder.encode(records)
    }
}

Testing Helpers

We’re almost ready to write our tests, we just need to add some helper methods to allow us to extract and verify our analytics within the ui test target.

This can be improved, but will suffice for the purposes of this demo:

struct ItemOccurrence<T> {
    let item: T
    let occurs: Int
}

class AnalyticsTester {
    let app: XCUIApplication
    
    init(app: XCUIApplication) {
        self.app = app
    }
    
    func verify(count: Int,
                file: StaticString = #file,
                line: UInt = #line) {
        let records = extractAnalytics()
        XCTAssertEqual(records.count, count, file: file, line: line)
    }
    
    func verify(type occurrence: ItemOccurrence<AnalyticsRecordType>,
                file: StaticString = #file,
                line: UInt = #line) {
        let records = extractAnalytics()
        let matchingRecords = records.filter { $0.type.rawValue == occurrence.item.rawValue }
        XCTAssertEqual(matchingRecords.count, occurrence.occurs, file: file, line: line)
    }
    
    func verify(id occurrence: ItemOccurrence<String>,
                file: StaticString = #file,
                line: UInt = #line) {
        let records = extractAnalytics()
        let matchingRecords = records.filter { $0.identifier == occurrence.item }
        XCTAssertEqual(matchingRecords.count, occurrence.occurs, file: file, line: line)
    }
    
    func verify(data occurrence: ItemOccurrence<String>,
                file: StaticString = #file,
                line: UInt = #line) {
        let records = extractAnalytics()
        let matchingRecords = records.filter { $0.data == occurrence.item }
        XCTAssertEqual(matchingRecords.count, occurrence.occurs, file: file, line: line)
    }
    
    func verify(idAndData occurrence: ItemOccurrence<(id: String, data: String)>,
                file: StaticString = #file,
                line: UInt = #line) {
        let records = extractAnalytics()
        let matchingRecords = records.filter { $0.identifier == occurrence.item.id && $0.data == occurrence.item.data }
        XCTAssertEqual(matchingRecords.count, occurrence.occurs, file: file, line: line)
    }
    
    private func extractAnalytics() -> [AnalyticsRecord] {
        let analyticsDebugger = app.otherElements[TestingConstants.AnalyticsDebugger]
        let decoder = JSONAnalyticsCoder()
        return decoder.decode(analyticsDebugger.value as! String)
    }
}

These helper methods, allow scanning through the analytics records attached to the accessibilityValue of our debugView and verify the appropriate occurrences took place. For example, we can verify a total of n analytics records are logged using verify(count: n) or we can drill in further and verify that out of these n records, m records are screen view analytics using verify(type: ItemOccurrence(item: .screen, occurs: m)) etc…

The Tests

Finally, we can now write our tests!

class LoginTests: XCTestCase {
    // ...
     func testAnalytics() {
        
        // verify screen view is logged on load
        analyticsTester.verify(count: 1)
        analyticsTester.verify(type: ItemOccurrence(item: .screen, occurs: 1))
        analyticsTester.verify(id: ItemOccurrence(item: AnalyticsScreens.Login, occurs: 1))
        
        // tap the login button and verify the tap event is logged
        app.buttons[TestingConstants.LoginButton].tap()
        
        analyticsTester.verify(count: 2)
        analyticsTester.verify(type: ItemOccurrence(item: .event, occurs: 1))
        analyticsTester.verify(idAndData: ItemOccurrence(item: (AnalyticsEvents.Login, AnalyticsActions.Tap), occurs: 1))
        
        // tap the sign up button and verify the tap event is logged
        app.buttons[TestingConstants.SignUpButton].tap()
        
        analyticsTester.verify(count: 3)
        analyticsTester.verify(type: ItemOccurrence(item: .event, occurs: 2))
        analyticsTester.verify(idAndData: ItemOccurrence(item: (AnalyticsEvents.SignUp, AnalyticsActions.Tap), occurs: 1))
    }
    // ...
}

Final Thoughts

Adopting something like this requires the use of best practices like dependency injection and adding abstractions where appropriate. In the demo I have a single screen so it was easy to inject the analytics and viewModel instances. Your app will of course be much larger and there are a few options out there on how to help out. Swinject is an example of a dependency injection framework for Swift apps that also supports injecting dependencies to UIViewController instances created by a UIStoryboard.

Testing analytics is important, especially if you base any business decisions on their results. The two techniques I outlined will certainly help ensure you are logging and propagating the appropriate events, however won’t be able to catch cases where the analytics framework itself fails to send data for example. Smoke testing before release is still needed, but at least you only need to verify one or two cases manually and rely on the tests for the rest.

Happy Testing!