Introduce new @UserDefaultOverride property wrapper for better UI testing support

[liamnichols]

Background

When prototyping the integration within a real iOS app, I found using UserDefaults.ValueContainer() somewhat repetitive.

We defined a Configuration type that held a series of properties that related to UserDefaults, but to map that into the value container resulted in a lot of repetitive code:

It would be great to avoid this somehow.

Description

In this PR, I'm proposing two new types:

1. The LaunchArgumentEncodable protocol
2. The @UserDefaultOverride property wrapper

They work in conjunction with each other and build on top of the functionality already provided by UserDefaults.ValueContainer. LaunchArgumentEncodable is pretty simple:

/// A protocol used by container types that can have their representations encoded into launch arguments via the ``encodeLaunchArguments()`` method.
///
/// This protocol works exclusively in conjunction with the ``UserDefaultOverride`` property wrapper.
public protocol LaunchArgumentEncodable {
    /// Additional values to be apended to the result of `collectLaunchArguments()`.
    ///
    /// A default implementation is provided that returns an empty array.
    var additionalLaunchArguments: [String] { get }
}

public extension LaunchArgumentEncodable {
    /// Collects the complete array of launch arguments from the reciever.
    ///
    /// The contents of the return value is built by using Reflection to look for all `@UserDefaultOverride` property wrapper instances. See ``UserDefaultOverride`` for more information.
    ///
    /// In addition to overrides, the contents of `additionalLaunchArguments` is apended to the return value.
    func encodeLaunchArguments() throws -> [String]
}

But it is somewhat magic. The encodeLaunchArguments() method will use Swift's reflection apis to find and iterate all of the @UserDefaultOverride properties defined on the type. It'll then collect the keys and values and pass them into a ValueContainer that is then used to produce the array of launch arguments.

In use, it looks something like this:

class ExampleUITests: XCTestCase {
    struct Configuration: LaunchArgumentEncodable {
        @UserDefaultOverride(.contentTitle)
        var title: String = "Example App (Test)"

        @UserDefaultOverride(.contentItems)
        var items: [Date] = []

        @UserDefaultOverride(.contentSortOrder)
        var sortOrder: ContentSortOrder = .descending

        var deviceLocale: Locale = Locale(identifier: "en_US")

        var additionalLaunchArguments: [String] {
            // Type `Locale` doesn't match how we want to represent the `AppleLocale` UserDefault so we'll encode it manually
            var container = UserDefaults.ValueContainer()
            container.set(deviceLocale.identifier, forKey: UserDefaults.Key("AppleLocale"))

            return container.launchArguments
        }
    }

    func testNoItemsPlaceholder() throws {
        // Override the relevant values
        var configuration = Configuration()
        configuration.deviceLocale = Locale(identifier: "fr_FR")
        configuration.sortOrder = .ascending
        configuration.title = "Example App"

        // Launch the app with the user defaults
        let app = XCUIApplication()
        app.launchArguments = try configuration.encodeLaunchArguments()
        app.launch()

        // ...
    }
}

In addition to this change, I updated UserDefaults.ValueContainer so that launchArguments returns key value pairs ordered based on when they were inserted. This helps us predictably test the output.

[ryanpato]

🚀🚀🚀 Really cool, excited to use it!

[liamnichols]

I just pushed some slight tweaks in the last two commits - https://github.com/cookpad/swift-user-defaults/pull/8/files/f9e9c3e9a6b03a84e19c224edf26036bbb7bfac1..4c64df2a637f90dea5b1d221addb0230236e571f

They change the UserDefaultsKeyValueRepresentable protocol to a public UserDefaultsOverrideRepresentable along with some tweaks to how LaunchArgumentEncodable works internally to help make it a bit more customisable if required in the future.