Working with watchOS Simulators

The idea of a multi-platform project won’t come as a surprise to Apple Watch developers, because a watchOS project must always have multiple platform targets: one for the iOS app, and at least one for watchOS. In fact, there are usually several watchOS targets: one for the app, one for a notification handler, and possibly another for a complication.

Because watchOS apps are bundled with iOS apps, you don’t use the same-name scheme as described for tvOS apps that have iOS counterparts. Instead, you use a naming convention for the bundle identifiers: for app com.app.foo.FooApp, the watch app would be com.app.foo.FooApp.watchkitapp and its extensions (notification handler and complication) would be com.app.foo.FooApp.watchkitextension.

One thing that is unique and unusual about watchOS development is the use of multiple devices or simulators. This is a must because you install your iOS app to the iPhone, and then the watchOS app is installed to the watch. A given Apple Watch can only be paired with one iPhone. But going in the other direction, a given iPhone can be paired with multiple Apple Watches (good news for those of you fashionable enough to need different watches for different looks). However, only one watch can be active at a time, meaning it’s the one that receives notifications or exchanges files via WKWatchConnectivity. With real devices, you make one of your paired watches active just by putting it on. In the simulator, it’s another story, as seen in the figure.

When you go to run your watchOS app or an extension, the scheme selector shows a pairing of an iPhone model and a watch model. By default, these are arranged as a large and small phone of the same model, coupled with the large and small watch released around the same time. For example, one destination will be “iPhone 8 + Apple Watch Series 3 38mm”, and another will be “iPhone 8 Plus + Apple Watch Series 3 42mm”. These simuated devices are paired: only this simulated phone works with this simulated watch, and vice versa.

These parings are sensible enough as a default, but they’re kind of limiting. What if you want to test on a new phone but an old watch (or vice versa)? Furthermore, Xcode 9 doesn’t include any option for testing a simulated iPhone X with an Apple Watch. What are you supposed to do to test that combination?

As it turns out, the combinations of simulated phone and watch models shown in the scheme selector are entirely customizable. The settings are in Windows > Devices and Simulators (⇧⌘2), which was introduced back in ​Packaging App Data for Tests​. The Simulators tab is where you can customize your watch schemes, albeit indirectly. The left side shows every iPhone and iPad model with an installed simulator (keep in mind that you can download additional simulators and older iOS versions from Xcode’s Settings window). If you select one, you’ll see it has a list of paired watches, just like physical iPhones do. However, this list also has a plus (+) button, which lets you add simulators. So, if you wanted to combine an iPhone X with a first-generation Apple Watch, you’d just select iPhone X from the list of simulators, and then click the plus (+) button. This slides out a sheet (shown in the figure) that lets you select a watch model and optionally give it an easy-to-remember name:

Once a given phone model has any paired watch simulators, it shows up as a destination in the scheme selector, as seen in the following figure:

It’s also possible to create multiple watch simulators for use with a given phone model. Once you use the plus (+) button to create a second watch simulator, the watch models in the list get radio buttons to determine which one is currently active, i.e., which one will be shown in the scheme selector.