Charles web debugging Proxy for your iOS/macOS Application
Read how to use Charles to debug and test your application. This straightforward and powerful tool can be in your hands and save you time.
Apps grow in volume every day, and it becomes more challenging to test them. And there comes a time when we need to create tools for debugging, or we no longer have enough standard ones. In this article, we will look at the use of Charles for debugging network requests in iOS applications and some of its additional features. This article is also suitable for testing macOS applications.
Charles allows you to manage and monitor requests from your application to a remote or even local server. So no need for us to use or even create our tools for monitoring requests. And if we do not do this, we can spend the saved time developing new functionality.
Meet Charles
First, we need to download and install Charles from the link. On the first launch, Charles will ask for permission to configure network settings automatically. If it doesn’t, press Command-Shift-P to have Charles request this permission again.
Each time you start Charles, it creates a session in which you will be working. You can save and reopen each session, which can help you share with colleagues.
In the Request list area, you can see a tree with events. Each node represents the website or the host you visit. Click on one of the recorded events, and you will see the details, look at the tabs in the Detail area and the information they display. Figure 1 shows a standard view when opened with an already selected HTTP request. Take the time to research the Request List area and how it works.
Note: If something does not work for you or you do not see activity in the request tree zone, then I advise you to visit the FAQ page on the official website.
Toolbar area
The Toolbar area contains the main tool buttons that you will often use while working. We will try some of the tools in practice. For now, let’s take a look at them:
- “Broom” clears the current session, the query tree, and all recorded actions.
- “Record / Pause” when active is red and all events are recorded and gray when stopped.
- “Block” starts / stops SSL proxying.
- The next buttons up to the checkmark provide access to general actions, including throttling, breakpoints, and querying.
- The last two buttons provide access to frequently used tools and settings.
Request List area
This zone displays all requests passing through Charles. At the top is the Structures / Sequence switcher. If we select Structures, then all requests will be grouped into a tree with nodes. Also, for convenience, you can right-click on the request and choose Focus, and then all requests not in Focus will be under the “Other hosts” node. The focus feature is handy when working with a particular set of hosts and not interested in others.
When you select Sequence, you will receive a sequential list of requests and additional information. I want to note that the interface will change a little, but the essence and functionality remain the same.
Detail area
Next, go to the zone with detailed information about the selected request. If you choose Structures and host (not API method), you will see three tabs: Overview, Summary, Chart. These tabs show statistics for the selected host, such as the number of successful requests, failed requests, request list, request timelines, and other helpful info.
For the selected request, you will have a Content tab to see the headers, body, cookies of the request, and response. Depending on the content, you can choose the display format.
Also, spend 5–10 minutes learning tabs and the interface. It will help you quickly navigate in the future. Also, you will notice that in HTTPS requests you cannot view the content. It has to do with SSL / TLS encryption. Requests are encrypted using certificates created by trusted third parties called certificate issuers. With the help of Charles, we can also create a certificate, but we need to install it on our devices, which will work through the Proxy. After that, we can decrypt the SSL events.
Real device connecting
We’ll start by connecting your device and then the simulator.
To do this, we need to find out our IP address. You can do it in any way you know or click on “Help” in the menu and select “local IP Address.”
Now we need to take the device that we will connect. On the device, open the settings and go to the Wi-Fi settings. Make sure your computer and device are on the same network. Otherwise, switch to the same network as your computer. Click on the “info” icon of the current network. Find the HTTP PROXY section in Configure Proxy and select Manual. In the Server field, enter your current IP. In the Port field, enter your actual port. Usually, the port is 8888 by default. You can change it in the proxy settings. And click on the Save button.
Do not forget to update your IP address. When you reconnect your computer to the network, the computer’s IP address may change. Otherwise, you can use a static IP.
In Charles, you will see an access request window. Let’s allow it. If it does not appear, try to open any site in the browser, and if this does not help, then check the IP address and all settings again.
Installing a certificate on a device
To install the certificate, open Safari and go to chls.pro/ssl. Next, we give a permit to download the configuration profile and go to the settings.
In the settings, go to the downloaded profiles and install the just downloaded one. If you have a password, then enter it. The video shows the whole process.
Then go to About -> Certificate Trust Settings and enable our certificate as shown in the video.
Simulator connecting
To connect the simulator, we need to enable it in Settings -> Proxy Settings and enable Enable macOS Proxy. Next, go to Help -> SSL Proxying -> Install Charles Root Certificate to iOS Simulators. You may have to reopen the simulator if no prompts appear.
Now let’s go to Charles, select the address, click the right mouse button, and select Enable SSL Proxying in the context menu.
For each subsequent request, you can now see the content sent and received. Also, via Proxy -> Enable SSL Proxying (Shift + Command + L) can provide you with more flexible instruments for managing. Spend 5 minutes learning it will be helpful to use Charles more confidently.
Note: For the test on an actual device, I used the AppStore application — AccuWeather, which is entirely free.
Advanced usage
Throttle
Sometimes developers or testers need to test their application with a bad internet connection. Click on the turtle icon in the Toolbox area to activate the Throttle tool and go to Proxy -> Throttle Settings. As you can see, you have many parameters that can simulate data loss, high latency, and reliability issues.
Network Link Conditioner provides similar network throttling capabilities, but Charles allows more advanced network settings.
Note: Remember to turn off Throttle when you don’t need it. It was funny when I once spent a whole hour debugging an application!
Modifying
Now we will consider the possibility of changing the request or response from the server. This ability will come in handy more than once while working on your application.
Find the request you want to change and use the context menu to enable Breakpoints (or via Proxy -> Breakpoints Settings). Charles will now pause the request each time. And it will allow you to change the data on the Edit Request tab. Try it. Click Execute at the bottom, and after receiving a response, you will see a window that allows you to edit the request-response. You can play with this and see how the data changes on your device make an effect. Additionally, you can set breakpoints specific for a request or a response. Take some time to master this tool.
Sometimes there is a need to redirect your requests to a remote server or a local file. To do this, create a JSON file, copy the data from the old answer into it, change the values and save. Further, in the context menu, press Map Local (or Tools -> “Map Local…”). Select the path to our JSON file in the local path field. And we execute the request from the application. As you can see, now each time, we receive data from our JSON file. Try the “Map Remote” feature yourself.
Also, other tools in the Toolbox area allow you to resend the request and optionally change the request data. Still, the iOS application will not respond to these responses in any way since Charles himself sends and receives them. Try these tools yourself. They are intuitive and straightforward.
We have explored Charles’s essential tools and capabilities, and it’s up to you to dive into it deeply. Try to change various fields and properties, take the time to study, and you will master this application as an advanced user. Charles is a straightforward yet very advanced tool in the hands of a developer or tester. And if you want to learn more about Charles, I advise you to visit the official documentation, where all the possibilities are well described.
Thank you for taking the time to read my story and for your support. If you enjoyed this article, please clap it to let me know. I will be sharing more stories in the future, so be sure to follow me to stay updated. Your feedback and support are greatly appreciated!
Follow Me: Twitter | LinkedIn
