I regularly bump into folks confused by this issue, so I thought I’d collect my thoughts on the topic into a single (hopefully) coherent post.
If you have questions or comments, put them in a new thread here on the forums. Feel free to use whatever subtopic and tags that apply to your situation, but make sure to add the Debugging tag so that I see your thread go by.
Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"
Testing and Debugging Code Running in the Background
I regularly see questions like this:
My background code works just fine in Xcode but fails when I download the app from the App Store.
or this:
… or fails when I run my app from the Home screen.
or this:
How do I step through my background code?
These suggest a fundamental misunderstanding of how the debugger interacts with iOS’s background execution model. The goal of this post is to explain that misunderstanding so that you can effectively test and debug background code.
Note The focus of this post is iOS. The advice here generally applies to any of iOS’s ‘child’ platforms, so iPadOS, tvOS, and so on. However, there will be some platform specific differences, especially on watchOS. This advice here doesn’t apply to macOS. It’s background execution model is completely different than the one used by iOS.
Understand the Fundamentals
The key point to note here is that the debugger prevents your app from suspending. This has important consequences for iOS’s background execution model. Normally:
iOS suspends your app when it’s in the background.
Once your app is suspended, it becomes eligible for termination. The most common reason for this is that the system wants to recover memory, but it can happen for various other reasons. For example, the system might terminate a suspended app in order to update it.
Under various circumstances your app can continue running after moving to the background. A great example of this is the continued processed task feature, introduced in iOS 26 beta.
Alternatively, your app can be resumed or relaunched in the background to perform some task. For example, the region monitor feature of Core Location can resume or relaunch your app in the background when the user enters or leaves a region.
If no app needs to be executing, the system can sleep the CPU.
None of this happens in the normal way if the debugger is attached to your app, and it’s vital that you take that into account when debugging code that runs in the background.
An Example of the Problem
For an example of how this can cause problems, imagine an app that uses an URLSession background session. A background session will resume or relaunch your app in the background when specific events happen. This involves two separate code paths:
If your app is suspended, the session resumes it in the background.
If your app is terminated, it relaunches it in the background.
Neither code path behaves normally if the debugger is attached. In the first case, the app never suspends, so the resume case isn’t properly exercised. Rather, your background session acts like it would if your app were in the foreground. Normally this doesn’t cause too many problems, so this isn’t a huge concern.
On the other hand, the second case is much more problematic. The debugger prevents your app from suspending, and hence from terminating, and thus you can’t exercise this code path at all.
Seek Framework-Specific Advice
The above is just an example, and there are likely other things to keep in mind when debugging background code for a specific framework. Consult the documentation for the framework you’re working with to see if it has specific advice.
Note For URLSession background sessions, check out Testing Background Session Code.
The rest of this post focuses on the general case, offering advice that applies to all frameworks that support background execution.
Run Your App Outside of Xcode
When debugging background execution, launch your app from the Home screen. For day-to-day development:
Run the app from Xcode in the normal way (Product > Run).
Stop it.
Run it again from the Home screen.
Alternatively, install a build from TestFlight. This accurately replicates the App Store install experience.
Write Code with Debugging in Mind
It’s obvious that, if you run the app without attaching the debugger, you won’t be able to use the debugger to debug it. Rather:
Extract the core logic of your code into libraries, and then write extensive unit tests for those libraries. You’ll be able to debug these unit tests with the debugger.
Add log points to help debug your integration with the system.
Treat your logging as a feature of your product. Carefully consider where to add log points and at what level to log. Check this logging code into your source code repository and ship it — or at least the bulk of it — as part of your final product. This logging will be super helpful when it comes to debugging problems that only show up in the field.
My general advice is that you use the system log for these log points. See Your Friend the System Log for lots of advice on that front.
One of the great features of the system log is that disabled log points are very cheap. In most cases it’s fine to leave these in your final product.
Attach and Detach
In some cases it really is helpful to debug with the debugger. One option here is to attach to your running app, debug a specific thing, and then detach from it. Specifically:
To attach to a running app, choose Debug > Attach to Process > YourAppName in Xcode.
To detach, choose Debug > Detach.
Understand Force Quit
iOS allows users to remove an app from the multitasking UI. This is commonly known as force quit, but that’s not a particularly accurate term:
The multitasking UI doesn’t show apps that are running, it shows apps that have been run by the user. The UI shows recently run apps regardless of whether they’re in the foreground, running in the background, suspended, or terminated. So, removing an app from the UI may not actually quit anything.
Removing an app sets a flag that prevents the app from being launched in the background. That flag gets cleared when the user next launches the app manually.
Note In some circumstances iOS will not honour this flag. The exact cases where this happens are not documented and have changed over time.
Keep these behaviours in mind as you debug your background execution code. For example, imagine you’re trying to test the URLSession background relaunch code path discussed above. If you force quit your app, you’ll never hit this code path because iOS won’t relaunch your app in the background. Rather, add a debug-only button that causes your app to call exit.
IMPORTANT This suggestion is for debugging only. Don’t include a Quit button in your final app! This is specifically proscribed by QA1561.
Alternatively, if you’re attached to your app with Xcode, simply choose Product > Stop. This is like calling exit; it has no impact on your app’s ability to run in the background.
Test With Various Background App Refresh Settings
iOS puts users in control of background execution via the options in Settings > General > Background App Refresh. Test how your app performs with the following settings:
Background app refresh turned off overall
Background app refresh turned on in general but turned off for your app
Background app refresh turned on in general and turned on for your app
IMPORTANT While these settings are labelled Background App Refresh, they affect subsystems other than background app refresh. Test all of these cases regardless of what specific background execution feature you’re using.
Test Realistic User Scenarios
In many cases you won’t be able to fully test background execution code at your desk. Rather, install a TestFlight build of your app and then use the device as a normal user would. For example:
To test Core Location background execution properly, actual leave your office and move around as a user might.
To test background app refresh, use your app regularly during the day and then put your device on charge at night.
Testing like this requires two things:
Patience
Good logging
The system log may be sufficient here, but you might need to investigate other logging solutions that are more appropriate for your product.
These testing challenges are why it’s critical that you have unit tests to exercise your core logic. It takes a lot of time to run integration tests like this, so you want to focus on integration issues. Before starting your integration tests, make sure that your unit tests have flushed out any bugs in your core logic.
Revision History
2025-08-12 Made various editorial changes.
2025-08-11 First posted.
0
0
220