Testing and Debugging Your iCloud App

Although no app is finished until it has been thoroughly tested and debugged, these steps are perhaps more important when you adopt iCloud: the number of user scenarios that your app must gracefully handle is greater. A user can have different versions of your app on different devices, or run your app on more than one device simultaneously. A user can turn on Airplane mode while a large file is uploading to iCloud. In rare cases, a user might log out of iCloud or switch to a different iCloud account.

This chapter helps orient you toward thinking about iCloud when testing and debugging your app.

Make Sure Your Device is Configured for iCloud

If things aren’t working as expected, first make sure that the preliminaries are correctly in place.

• Ensure that your test devices are correctly provisioned for iCloud.
  Your device provisioning profile and app ID must be correctly configured for iCloud. Review “Adding Capabilities” in App Distribution Guide.
• Ensure that your iCloud entitlement requests are correct.
  Without the appropriate entitlement requests in place in your Xcode project, your app has no access to its ubiquity containers or to key-value storage. Carefully review the information in “Request Access to iCloud Storage By Using Entitlements.”
  Ensure that when you access your app’s ubiquity containers, you are using fully-qualified entitlement values.

Take Latency Into Account

When testing, don’t expect changes to instantly propagate from one device to another.

You can programmatically determine if a file has made it to the iCloud servers by checking the value of its URL’s NSURLUbiquitousItemIsUploadedKeykey. Do this by calling the NSURL method getResourceValue:forKey:error:. The key’s Boolean NSNumber value contains true if the file has been successfully uploaded.

Likewise, you can programmatically determine if an iCloud file is present locally. Check the value of the NSURLUbiquitousItemIsDownloadedKey key of the corresponding URL by calling the NSURL method getResourceValue:forKey:error:.

In both cases, obtain the file URLs from your app’s NSMetadataQuery object, as described in “App Responsibilities for Using iCloud Documents.”

Monitor Your App’s Network Traffic

Keep an eye on network activity while testing your app, checking for undue amounts of network traffic. For iOS, use the “Network Activity Instrument”, described in Instruments User Reference. On a Mac, you can use the OS X Network Utility app.

If your app’s network traffic seems excessive, look for optimizations in your app design. For example, you may be able to design your document file package in a way to better support incremental uploads and downloads, as described in “Design for Network Transfer Efficiency.”

Use Two Devices to Test Document Conflicts

Real world use of your iCloud-enabled app can result in a wide range of conflict scenarios between versions of a document. Beyond that unavoidable truth, issues in an app’s logic can cause needless conflicts, as described in “Design for Persistent Document State.”

Here are some ideas for simulating real-world conflicts. To prepare for these tests, set up two devices to be connected to a single iCloud account. Implement your app to handle these scenarios and others that come to mind for your particular app.

To test document version conflicts with one device offline

To test document version conflicts with two devices offline

To test forward and backward compatibility of your document format

To test document management

Start Fresh if Your iCloud Data Becomes Inconsistent During Development

While you are developing an app, it is possible for data in the app’s ubiquity container to become inconsistent. If this happens, your app’s behavior can become inconsistent as well. If previously-working code is now not working, try emptying the ubiquity container for your app to start fresh.

You can empty your app’s ubiquity container using an iOS device or a Mac.

To empty the ubiquity container for your app, using an iOS device

To empty the ubiquity container for your app, using a Mac

If you provide an OS X version of your iCloud-enabled app, and you want to start completely fresh, also delete the contents of the app’s App Sandbox container on each Mac on which your app was installed. This ensures that any other app-specific data, that might have become inconsistent, is also removed. The path for an App Sandbox container on a Mac is:

~/Library/Containers/<bundle-name-for-app>