Add Test Targets to an Existing Project

Of course, you don’t have to create a new project to add UI and unit tests. It’s straightforward to add tests to an existing project – just like adding any new target. To add a new test target, go to File ➤ New ➤ Target…. In the “Choose template” box that appears on the screen, look for UI Testing bundle or Unit Testing Bundle targets. You can take advantage of the search field in the top corner of the box (see Figure 2-4). Again, not all platforms have the option to add tests, so make sure the correct platform is selected.

After tapping “Next”, you are being navigated to a new dialog pretty similar to the new project dialog. Besides all the usual properties you need to fill there, such as bundle ID and name, the most important property is the “Target to be Tested.” This target is the actual “product” (app or framework) that your new test bundle tests. “Target to be Tested” can also be changed later (see Figure 2-5).

The Info Tab

Info – The Info tab contains general information about your test action in the scheme. The two most important settings here are the Build Configuration and the list of tests .

In Build Configuration, you can define if your tests run in Debug, Release, or your custom build configuration. There are cases where this is important – for example, sometimes you want to run a test against an optimized code for the App Store, or sometimes you want to run your tests with certain flags.

In the list of tests, you can see all the tests that are relevant for the executable product in the scheme. Remember, you can create as many tests as you want, but this is the place where you define what tests are executed when you test your app with this scheme.

Next to each test in the list, you have an enabled checkbox button that specifies if the list runs. On the right, you have a button named “options”. Tap on it, and you can set how the test runs (again, only in this scheme) (see Figure 2-8).

The options menu is unknown for many developers, and the button may look unimportant, but it holds extremely valuable settings.

Location

The Location option lets you simulate a specific geo-location for your test bundle or even a movement. Without the location feature, it is tough to simulate location changes or movement tracking.

The location popup menu in the editor scheme has a list of predefined locations like London, Moscow, New York, and more.

You don’t have to settle for the predefined list, but you can create your own locations using a file format named “GPX.” GPX (GPS Exchange) files contain location data such as longitude and latitude, waypoints, routes, and tracks. The basic format of GPX is XML, and you can create such a file in any text editor or online generator. Xcode itself has an option to create a GPX file, select from the menu File ➤ New ➤ File, and search for GPX in the dialog box (see Figure 2-9).

The basic format of the GPX file should look something like this:

<gpx>

    <wpt lat="40.7484" lon="73.9857">

        <name>Empire States Building</name>

    </wpt>

 </gpx>

After adding the file to your project, you can see the “Empire States Building” location in the list of locations (see Figure 2-10).

GPX files can also contain movement. The way to do it is by adding multiple locations and timestamps so that Xcode can simulate the location changes according to the required pace.

 <gpx>

   <wpt lat="40.606641" lon="-74.044835">

     <time>2020-03-01T16:25:12Z</time>

   </wpt>

   <wpt lat="40.608693" lon="-74.038514">

     <time>2020-03-01T16:25:17Z</time>

   </wpt>

   <wpt lat="40.610769" lon="-74.032217">

     <time>2020-03-01T16:25:26Z</time>

   </wpt>

</gpx>

Application Data

One of the neat features Xcode has is the ability to load the app in a specific app state, including persistent data, user defaults, and even cache. Loading the app with specific data is done using something called XCAppData file. XCAppData file is a files package that contains all the app data, including documents, Library, cache, and temporary file.

To get the XCAppData file, you need to make sure your device is connected to your Mac and go to Window ➤ Devices and Simulators. In the opened window, look for your connected device on the left and select it. Now you supposed to see the list of paired Apple Watches and installed apps (see Figure 2-11).

After selecting your app, you can download its app data container to your Mac. You should see a file with the following format:

<bundleID>.<Date>.xcappdata

For example:

www.myweatherapp.com.My-Weather-App 2020-03-10 06/32.03.037.xcappdata

You should be aware of the fact that .xcappdata is a package, meaning it’s a system directory displayed as a standard file and it contains additional files and directories. To open the package, right-click on the package in the Finder and select “Show Package Contents”. After that, you can see the app data files hierarchy (see Figure 2-12).

As you can see in Figure 2-12, the package contains all the app data that your device stores, including documents, temporary files, states, and even app screenshots the system uses for app switching user experience.

If you want to use the app data package (.xcappdata file) in your Xcode settings, you need to add it to your project.

Create a new group in your project, let’s say “Tests Data,” and add the package to that folder. Make sure the xcappdata doesn’t belong to any target.

Note

Files that you want to use in your scheme such as GPX files and data packages should not be added to any target, not even your test target. If a file belongs to a certain target, it will be bundled with the final product and not only will increase the application size, but it can also reveal security and sensitive privacy information.

The Arguments Tab

Xcode has another neat and unknown features in their scheme editor, hidden under the arguments tab, called Launch Arguments and Environments Variables (see Figure 2-13).

The Arguments tab lets you control the runtime of your app by setting arguments and variables that applied to the app only in this scheme.

Launch Arguments

Let’s say we want to add an “In-App Purchase” capability to our “My Weather” app, and we want to run integration and UI tests when the user is already registered to our premium subscription.

The typical way many developers test their In-App Purchase is by returning “true” in the function that checks if the user is registered or not (look at the following code):

func isTheUserRegistered()->Bool {

return true

// The rest of the "real code", checking if the keychain contains information about the user purchase

...

}

Returning “true” might work fine when you do your checks during development, but running tests like that may not be the right solution.

Fortunately, we can change values in runtime easily using the “Arguments Passed on Launch ” list.

Arguments are a list of values passed to the app on launch and can be read in the code easily.

Your app can use arguments to run with specific flags without recompiling or using different targets. Arguments can be handy in testing because there are times when you want to mock different layers in your app, such as network, database, and more.

To add a new argument, go to the Arguments tab in the scheme editor, and under the list of arguments, tap on the plus button (see Figure 2-14).

If you don’t want an argument to pass on launch, you don’t need to delete it from the list; uncheck the checkbox near its name.

There are two similar ways to read the list of arguments in your code, CommandLine and ProcessInfo .

Look at the following code:

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

        var purchasedIAP = CommandLine.arguments.contains("PURCHASED_IAP")

        // or we can use ProcessInfo

        purchasedIAP = ProcessInfo.processInfo.arguments.contains("PURCHASED_IAP")

        if purchasedIAP {

            // do something useful here...

        }

        return true

    }

To clarify the differences between the two, CommandLine is part of Swift, and its primary goal is to read the command-line arguments, and, in this case, Arguments passed on launch.

ProcessInfo is part of foundation, and it contains information about the current process, including variables, host name, and also, just like CommandLine, the list of arguments.

For the goal of reading the arguments, you can use both of them.

Environment Variables

Just like many other development environments, iOS also has something similar called “Environment Variables.” An environment variable is a collection of key–value which let you configure your app not just with a list of argument but also with values.

Adding an environment variable is just like adding an argument. Tap on the plus button under the variables list and add a new variable (see Figure 2-15).

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

        let printInfoLogs = ProcessInfo.processInfo.environment["PRINT_INFO_LOGS"]

        return true

    }

Adding Environment Variables is also a great way to configure UI Tests by launching the app dynamically with different arguments each time. UI Tests will be covered later in this book.

The Options Tab

The options tab includes different settings related to your tests (see Figure 2-16).

The Diagnostics Tab

The diagnostics tab is almost similar to the diagnostics tab you can find under “Run”. This tab contains tools that can help determine issues with your app while running your tests, such as memory corrupts and thread issues (see Figure 2-19).

Since those tools are not explicitly related to testing, I will go over them in short.

Disable Tests from the Scheme Editor

If you want to disable a test in a specific scheme, unchecking it from the scheme editor is one way of doing that. Open the scheme editor, and under Test ➤ Info, expand the test bundle in the list of test bundles (see Figure 2-20).

Remember , the disabling test only disables it from the specific scheme, so make sure you are doing this operation on the desired scheme.

Also, you can disable the whole class by unchecking the checkbox near the class name or disable the whole test bundle by unchecking the checkbox near the test bundle name.

Disable Tests from the Test Navigator

Maybe the easiest way to disable a test is from the Test Navigator or the code editor.

From the Navigator pane, open the Test Navigator by selecting it or pressing ⌘-6.

Search the test you want to disable and right-click it (see Figure 2-21).

Select “Disable <name of the test>” from the popup menu. Disabling can be done for classes and test bundles as well. In case the test is already disabled, you can re-enable it again from the same menu.

This approach also works from the code editor – right-click the function of the class you want to disable and choose “Disable <name of the function>”.

Disable Tests by Renaming Them

In the preceding example, Xcode ignores the third function since we changed its prefix.

In general, renaming test functions is considered to be an anti-pattern, and you should follow the natural way of disabling the tests using the scheme editor or the Test Navigator. The renaming test function does have one advantage, though – you can set a different prefix for a different reason and then relocate them by searching their prefix. Renaming a function name is a convenient way when you’re doing a big refactor and want to disable tests by categories.

Test Plans to Make Your Life Easier

Test Plans take the power of the test run customization in Xcode to the next level by giving you the flexibility to run your tests with different settings multiple times. Each Test Plan can test different issues that you may have in your app. Maybe the most common problem developers have with their apps is localization – you can create a test plan dedicated to localization and run the same tests over and over again but with different languages and regions.

The same goes for almost every option you currently have in your scheme editor.

Create Your First Test Plan

The easiest way to start with the Test Plan’s feature is right from the scheme editor. Go to your scheme editor, and in the Test action, you can find a button called “Convert to user Test Plans…” under the list of your test bundles (see Figure 2-22).

After tapping the button, you’ll have a dialog when you need to choose how to convert your new scheme to use test plans instead (see Figure 2-23).

After creating the test plan, it is saved to your project, and the Xcode upgrades the scheme to use Test Plans instead of the old Info/Arguments/Options/Diagnostics screen we covered earlier (see Figure 2-24).

Scheme can contain multiple test plans. In each test plan, you can see how many test targets it runs and how many different configurations it has.

When you select “Test” for this scheme (Command + U), the test plan, which is marked as default, runs according to its configuration.

Test Plan Configurations

Although we are not supposed to edit the .xctestplan file directly, we can learn that Test Plan is quite simple. It contains an array of configurations and an array of test targets. Test Plan also has a default options section in case they are not set in the configurations themselves.

Tapping on the test plan in the project navigator will open the test plan edit screen (see Figure 2-25).

As you can see, you can enable/disable test bundles, classes, and functions just like you can do in your scheme editor. If you notice, you also have a new tab named “Configurations”. If the “Tests” define what your test plan runs, “Configurations” define how your test plan runs it. A test plan configuration contains a list of values like location, region, and more, very similar to the options you had in your scheme editor. The significant difference here is that you can create as many configurations as you want (see Figure 2-26).

The test plan in Figure 2-26 tries to test the app in different localization. Localization is one example of how a Test Plan can be useful. You can have several test plans that can handle different issues such as memory and performance issues, localization, and more. Whenever you run a test plan, Xcode runs the selected tests one time for each configuration, and there’s no limit on the number of configurations you can create. This is something tough to do without using a test plan.

If you want to disable a test configuration from running, right-click the configuration name and select “Disable”.

Running Your Test Plans

Because we added a new layer of complexity, let’s try to simplify what we have learned till now and how everything is linked together (see Figure 2-27).

As you can see from the preceding diagram, a scheme can have multiple test plans, but when you run a test, only one of them executes.

To run the test plan selected for the scheme, press Command + U or run it from the Test Navigator.