A quick guide to Charles, a web debugging proxy application

As any tester knows, software testing can be a rewarding yet tedious task. A huge setback can occur when certain features don’t respond or behave in an expected way, but typically the tester has no way of knowing what request or response was sent between the application and the Server.

Software applications like Charles prove to be extremely useful, and almost essential, in these cases.

Charles is an HTTP proxy, also known as HTTP monitor or Reverse Proxy, that allows the tester to view all of the HTTP and SSL/HTTPS traffic between their machine and the Internet. This includes requests, responses, and HTTP headers. Charles allows the tester to quickly find the source of the problem, efficiently sort through the different types of errors that come up, and duplicate various test scenarios.

A major benefit of using Charles is that it is compatible with a majority of web and mobile browsers.

Charles does not require the user to reconfigure their browser settings each time they test an application, because it performs automatic configuration with most browsers. Here’s a short guide on how Charles configures web browsers:

• For the Windows operating system and its related browsers (such as Internet Explorer and Edge), Charles can automatically configure the proxy settings so that Windows applications automatically start using Charles. Charles will configure and then reconfigure the proxy settings whenever it opens or closes.
• For the Mac OS X operating system and its related browsers (such as Safari), the first time the user installs Charles they are prompted to grant permission. Afterwards, Charles can automatically configure and reconfigure the proxy settings whenever Charles opens or closes.
• For the Mozilla Firefox browser, the user will need to download the Firefox Add-On, after which Charles will be able to automatically configure the proxy settings.
• For all browsers, Charles settings can be adjusted in the proxy menu.

For mobile browsers, Charles works a little differently. Here’s a quick breakdown of some of the major differences:

• The mobile device and the machine running Charles both need to be on the same wireless network.
• The tester has to change the HTTP proxy settings from Off to Manual and enter the port that Charles is running on in their Wi-Fi settings. In most cases, Charles runs on port 8888 but can be configured by the tester if desired. For the majority of devices, modifying the HTTP settings can be done from the Wi-Fi settings under the general settings menu.
• The first time the device connects to Charles, the tester is prompted to allow or not allow the network traffic. Once allowed, Charles will be able to display the Internet traffic going through the mobile device.
• The tester has to manually turn off the HTTP proxy settings when they’re done using Charles. If they don’t, once Charles is closed and testing is done, the mobile device will throw error messages when applications attempt to connect with the Internet. This is because the proxy server, Charles, being used to access the Internet is no longer running.

Steps for turning the HTTP proxy setting on/off for mobile devices in Charles are: For iPhone:

1. Tap the Settings app
2. Tap Wi-Fi
3. For the Wi-Fi network to which the iPhone is connected, tap the blue information icon
4. Scroll down, and under HTTP PROXY, tap Manual
5. Next to Server, enter the IP address of the machine running Charles
6. Under Server, enter Charles’ port number into Port (usually 8888)

‍

‍

For Android:

1. Tap the Settings icon
2. Tap Wi-Fi
3. Long tap the name of the connected network. A menu will appear with options to customize the network settings
4. Tap Modify network
5. Check the Advanced options box and hit Enter
6. Change the Proxy from None to Manual
7. Under Proxy hostname, enter the IP address of the machine running Charles
8. Enter Charles’ port number into Proxy port (usually 8888)Charles Android

‍

‍

Charles generates its own unique SSL certificates for websites during installation. The tester can choose to permanently trust every certificate issued by Charles for both web and mobile browsers. Here’s a brief guide to setting up automatic trusting for Charles’ SSL certificates:

For the Windows operating system and its related browsers such as Internet Explorer and Edge:

1. In Charles, click on the Help menu and choose SSL Proxying > Install Charles Root Certificate. A window will appear warning that the CA Root certificate is not trusted.
2. Click the Install Certificate button to launch the Certificate Import Wizard. The certificate must be imported into the “Trusted Root Certification Authorities” certificate store, so override the automatic certificate store selection.
3. Complete the Certificate Import Wizard and then the Charles Root Certificate is installed. Internet Explorer may need to restart before the installation takes effect.
   ‍

For the Mac OS X operating system and its related browsers (such as Safari):

1. In Charles, click the Help menu and choose SSL Proxying > Install Charles Root Certificate.
2. Keychain Access will open and prompt you about the certificate.
3. Click the Always Trust button. You will be prompted for the administrator password in order to update the system trust settings. Safari may need to quit and reopen before the change takes place.
   ‍

For the Mozilla Firefox browser:

1. (After downloading the Add-on:) In the Firefox browser, go to the Tools Menu > the Charles submenu, and choose Install Charles Root Certificate.
2. A certificate import dialog will appear. Check Trust this CA to identify websites.
   ‍

For iOS devices:

1. (After setting the HTTP proxy:) Open Safari and browse to http://www.charlesproxy.com/getssl.
2. Safari will prompt you to install the SSL certificate, which you should accept.

For Android devices:

• You can only use SSL Proxying with apps that you control. In order to configure the app to trust Charles, you need to add a Network Security Configuration File to the app.
• This file can override the system default, enabling the app to trust user-installed CA certificates.
• To do this:

1. Add a file, res/xml/network_security_config.xml, to your app:

‍
2. Then add a reference to this file in your app’s manifest, as follows:

‍
At WillowTree, we’ve found Charles invaluable for testing, because it allows us to easily test across a spectrum of web and mobile browsers. Charles’ features include being compatible with the majority of web and mobile browsers, and automatically reconfiguring web settings. If software testing is part of your job description, we highly recommend you check it out!