Debug Your App

After you click the Run button in the workspace toolbar and your app builds successfully, Xcode runs your app and starts a debugging session. You can debug your app directly within the source editor with graphical tools such as data tips and the variables Quick Look.

The debug area and the debug navigator let you inspect the current state of your running application and control its execution.


Creating a quality app requires that you minimize your application’s impact on your users’ systems. Use the debug gauges in the debug navigator to gain insight into your app’s resource consumption, and when you spot a problem, use Instruments to measure and analyze your app’s performance.

If you are developing an iOS app, use iOS Simulator to find major problems during design and early testing.

You can configure Xcode to help you better focus on your debugging tasks. For example, when your code hits a breakpoint, you can make Xcode automatically play an alert sound and create a window tab named Debug, where Xcode displays the debug area, the debug navigator, and your code at the breakpoint.

Control Execution and View State Information

Xcode lets you step through your code line by line to view your program’s state at a particular stage of execution. Use the debug area to control the execution of your code, view program variables and registers, view its console output, and interact with the debugger. You can also use the debug area to navigate the OpenGL calls that render a frame and to view the rendering-state information at a particular call.

Display the debug area by clicking the center button (../art/TB_ViewDebugger_2x.png) in the view selector in the workspace window toolbar.


You can suspend the execution of your app by clicking the pause button (which toggles between ../art/DebugPause_2x.png to pause and ../art/DebugRun_2x.png to continue) in the debug area toolbar. To set a breakpoint, open a source code file and click the gutter next to the line where you want execution to pause. A blue arrow (../art/breakpoint_icon_2x.png) in the gutter indicates the breakpoint.

When execution pauses, the debug navigator opens to display a stack trace. Select an item in the debug navigator to view information about the item in the editor area and in the debug area. As you debug, expand or collapse threads to show or hide stack frames.


Hover over any variable in the source code editor to see a data tip displaying the value for the variable. Click the inspector icon (../art/QuickLookInspectorIcon_2x.png) next to the variable to print the Objective-C description of the object to the debug area console and to display that description in an additional popover.


Click the Quick Look icon (../art/QuickLookVarIcon_2x.png) to see a graphical display of the variable’s contents.


When you build and run an OpenGL ES application on a connected device, the debug area toolbar includes a frame capture button (../art/CaptureFramebutton.png). Click that button to capture a frame. You can use OpenGL ES frame capture to:


Examine Your App’s Impact on System Resources

The debug navigator displays gauges that provide insight into how your app is performing. For example, the CPU gauge shows a readout of your app’s CPU usage, making it easy to spot unexpected spikes. Depending on the capabilities of your app and the characteristics of its destination, gauges can report your app’s impact on memory, iCloud, OpenGL ES, energy, and the CPU.


To see a full report, click a gauge in the debug area. To perform a deeper analysis of your app’s performance, click the “Profile in Instruments” button.


For problem areas, the energy report offers a preliminary diagnosis of what may be plaguing your app.


Measure Your App’s Performance

The Instruments app, which is included with Xcode, gathers data from your running app and presents it in a graphical timeline. With Instruments, you can gather data about such performance areas as your app’s memory usage, disk activity, network activity, and graphics operations. By viewing the data together, you can analyze different aspects of your app’s performance to identify potential areas of improvement. You can also automate the testing of your iOS app’s user interface elements.


There are several ways to start Instruments from Xcode. For example:

The Instruments app uses individual data collection modules, known as instruments, to gather data about a process over time. The Instruments app includes a library of templates. Each template contains instruments for obtaining a set of related information.

Perform Early Testing in iOS Simulator

iOS Simulator helps you find major problems in your app during design and early testing. For example, the Debug menu in iOS Simulator offers tools that help you:


In every simulated environment in iOS Simulator, the Home screen provides access to apps—such as Safari, Contacts, Maps, and Passbook—that are included with iOS on the device. You can perform preliminary testing of your app’s interaction with these apps in iOS Simulator. For example, if you are testing a game, you can use iOS Simulator to test that the game uses Game Center correctly.

The Accessibility Inspector in iOS Simulator helps you test the usability of your app regardless of a person’s limitations or disabilities. The Accessibility Inspector displays information about each accessible element in your app, and you can use the Accessibility Inspector to simulate VoiceOver interaction with those elements. To start the Accessibility Inspector, click the Home button on iOS Simulator. Click Settings and go to General > Accessibility. Slide the Accessibility Inspector switch to On.

You can test your app’s localizations in iOS Simulator by changing the language. In Settings, go to General > International > Language.

Although you can test your app’s basic behavior in iOS Simulator, the simulator is limited as a test platform for multiple reasons. For example:

While developing your app, run and test it on all of the iOS devices and iOS versions that you intend to support.

Customize Your Debugging Workflow

You can specify behaviors that affect your workflow through the Xcode Behaviors preferences. Choose Xcode > Behaviors to specify what should happen when a variety of events occur while building, running, and debugging your app.

For example, you can have Xcode display the debug area when your code pauses at a breakpoint, and you can have Xcode display the issue navigator when a build fails.

In the screenshot below, behaviors are customized for whenever the code pauses. Here are some examples of customized behaviors:


As a result, when the code in the project hits a breakpoint, Xcode creates a Debug tab in the workspace window with the specified content.


You can design custom behaviors that are triggered by menu items or their keyboard equivalents. Click the Add button (+) at the bottom of the Behaviors preferences pane. Type the name of the new behavior, and press Return. Select checkboxes to specify what should happen when you invoke this behavior. For example, you can create a Unit Testing behavior that saves a snapshot of your project and runs your unit tests. After you’ve created a behavior, it appears in the Xcode > Behaviors menu.

To assign a keyboard equivalent to a custom behavior, choose Xcode > Preferences and click Key Bindings. In the Key Bindings preferences pane, select the Customized tab to find the custom behavior you want. In the text field, enter the keys you want to use for the key binding in the text field, and click outside the text field to complete the operation.