Motivation
In some tests, you may need to use a web debugging proxy tool to log the data traffic between the device used for testing and the internet. One of the tools used for this purpose is called Charles Proxy and you might need to use it while testing with a few of our customers. The process to install and configure Charles Proxy properly is described below.
First step: Setting up Charles Proxy on your computer
For both Web and App testing, you will need a computer and install the program Charles Proxy on it.
Download the trial version of Charles proxy that matches your computer system here.
Install the Charles proxy app.
In the Charles app, go to the menu item Proxy > External Proxy settings….
Tick the checkbox Use external proxy servers.
Tick the checkbox for Web Proxy (HTTP) and tick Proxy server requires a password. Enter the proxy details fields as following:
Web Proxy Server: forward.test.io:3128
Domain: forward.test.io
Username: you can find this information in the test description.
Password: you can find this information in the test description.
Tick the checkbox Secure Web Proxy (HTTPS) and tick Proxy server requires a password. Repeat the details fields from the last step.
Click on the OK button to save the settings.
The Test IO proxy is now correctly saved as the external proxy in your Charles Proxy app.
Installing SSL Certificate on your Windows computer
Before attempting to navigate to the customer website you want to test, you must install an SSL certificate on your device, so the internet traffic can be correctly captured.
Prerequisite: You installed and configured Charles Proxy on your computer.
Launch the Charles Proxy app on your computer.
In the menu, navigate to Help > SSL Proxying > Install Charles Root Certificate.
Click on Install Certificate… and select Current User.
Click on Next. You will be prompted to select where the certificates will be kept in your system.
Select Place all certificates in the following store and click on Browse…
Select Trusted Root Certification Authorities and click on OK.
Click on Next and then on Finish.
Restart your computer to complete the installation.
Now Charles Proxy SSL certificate is fully installed on your device.
Setting up an iOS device
Prerequisite: You installed and configured Charles Proxy on your computer.
Make sure that your mobile device and computer are connected to the same WiFi network.
Launch the Charles Proxy app on your computer.
In the menu, navigate to the menu item Help > SSL Proxying > Install Charles Root Certificate on a Mobile Device or Remote Browser. A window will open and it will give you your local IP address and a port to use.
On your iOS device, go to your Wifi Settings and click the blue “i” icon next to your Wifi.
At the bottom of the screen, tap on Configure Proxy and tap on the option Manual.
Enter the local IP address into the server field and the port given by the Charles Proxy app in the step 3.
Save the settings > A dialog should prompt on your computer to ask for permission to allow this new access.
Give permission.
Your device’s internet traffic is now routed through Charles Proxy. From now on, the internet on your device will only work while the Charles Proxy app is opened in your computer.
Installing SSL Certificate on iOS
Before you attempt to launch the customer app you want to test, you must install an SSL certificate on your device so the internet traffic can be correctly captured.
Prerequisites:
You installed and configured Charles Proxy on your computer.
You installed and configured Charles Proxy on your iOS device.
Navigate to chls.pro/ssl using the Safari Browser on your mobile device. A dialog should prompt on your device to install the SSL certificate.
Allow the certificate to be installed. A dialog should prompt explaining you must review the profile in Settings app on your device.
Close the modal and the Safari browser.
Navigate to the Settings app on your device and follow the path General > VPN & Device Management > Downloaded Profile and select the Charles Proxy CA.
Tap on Install to install the certificate on your device. You will be prompted to enter your device’s password. After a successful authentication, a warning screen will be shown. Tap on Install to complete the installation of the certificate.
A Profile Installed confirmation window will be shown. Just press Done.
Return to the Settings > General submenu and navigate to About > Certificate Trust Settings.
Enable the Charles Proxy CA certificate.
A warning screen will pop up. Tap on Continue.
Now Charles Proxy SSL certificate is fully installed on your device.
Setting up an Android device
Prerequisite: You installed and configured Charles Proxy on your computer.
Make sure that your mobile device and computer are on the same WiFi network.
Launch the Charles Proxy app on your computer.
In the menu, navigate to Help > SSL Proxying > Install Charles Root Certificate on a Mobile Device or Remote Browser.
A window will open and it will give you your local IP address and a port to use.On your Android device, go to your Wifi Settings and select to edit the current network.
Look for the Proxy option and select Manual.
Enter the local IP address into the Proxy host name field and the port given by the Charles Proxy app in the step 3.
Save the settings > A dialog should prompt on your computer to ask for permission to allow this new access.
Give permission.
Your device’s internet traffic is now routed through Charles Proxy. From now on, the internet on your device will only work while the Charles Proxy app is opened in your computer.
Installing SSL Certificate on Android 10 or less
Prerequisites:
You installed and configured Charles Proxy on your computer.
You installed and configured Charles Proxy on your Android device.
Before you attempt to launch the customer app you want to test, you must install an SSL certificate on your device so the internet traffic can be correctly captured by completing the following steps:
Navigate to chls.pro/ssl using the Chrome Browser on your mobile device. The “*.crt” certificate file will start to download to your device.
Open the downloaded file and authenticate.
Provide any name for the certificate and make sure the option VPN and apps is selected under the Credential use.
Tap on OK.
Now Charles Proxy SSL certificate is fully installed on your device.
Installing SSL Certificate on Android 11+
Before you attempt to launch the customer app you want to test, you must install an SSL certificate on your device so the internet traffic can be correctly captured by completing the following steps:
Prerequisites:
You installed and configured Charles Proxy on your computer.
You installed and configured Charles Proxy on your Android device.
Navigate to chls.pro/ssl using the Chrome Browser on your mobile device. The “*.crt” certificate file will start to download to your device.
After the file downloads, navigate to your device Settings app and look for a similar option to Install from device storage (it’s usually located in the Advanced Security settings on your device).
Select CA Certificate and then Install anyway in case a warning screen is shown.
Authenticate and look for the downloaded “*.crt” file.
Select the downloaded file and tap on Done.
Now Charles Proxy SSL certificate is fully installed on your device.
Capturing a log
Prerequisite: Make sure you installed and configured Charles Proxy on your computer as explained above. Also make sure the SSL certificate is correctly installed in the device you’re using for testing.
Prerequisites:
Capturing a log of your computer traffic: Make sure the Windows Proxy option under the menu item Proxy is enabled.
Capturing a log of your mobile traffic: Make sure the Windows Proxy option under the menu item Proxy is disabled.
Note: Always make sure only one device is connected to Charles Proxy each time when capturing a log, otherwise traffic data from all devices will be recorded in your log.
Launch the Charles Proxy app on your computer.
In the menu, navigate to Proxy > SSL Proxying Settings…
Make sure to tick the checkbox Enable SSL Proxying and under the Include section, click on Add.
Enter the customer’s server(s) you want to watch and the port (this information will be given in each test cycle).
Click on OK to return to the SSL Proxying Settings window.
Click on OK again to save the settings.
Now Charles proxy will apply the SSL proxying to the selected server(s) only. To start a new session, you must:
Make sure the record button (the red circle located right below the main menu on the Charles Proxy app) is enabled.
Click on the brush icon to clear the past logs.
Navigate to the test environment (either open the customer app or navigate to the landing page of the website).
Reproduce the desired behaviour (mentioned in the cycle instructions, a bug report, User Story or Test Case).
Once you’ve done, disable the record button to stop capturing the log.
In the menu, navigate to File > Save Session As…, select the location to save the file, give it a proper name and make sure the Charles Session File (.chls) extension is selected.
Now you can save your Charles Proxy log file and submit it.
FAQ
How can I know Charles Proxy is working correctly?
You can check if the Charles Proxy is working for a specific server by opening the Charles Proxy app, clicking on the server you want to check, navigate to the Overview > Notes information and the value should be SSL Proxying enabled for this host.
A value of SSL Proxying is not enabled for this host. Enable in the Proxy Menu, SSL Proxying Settings means you did not add the current server to the SSL proxying list. You can either add the server manually by visiting the SSL Proxying Settings options or you can right click on the server and select the Enable SSL Proxying option.
Note: You might need to start a new log session in order to apply the new settings.
Should the screencasts captured in a bug report match the Charles Proxy logs?
Like when you’re capturing a Crash log, if you’re required to provide a screencast with your log (e.g. when submitting a bug report), the timestamps of the Charles Proxy log and the screencast must match, otherwise your log will be invalid.
Can I use Charles Proxy logs in crash reports?
Charles Proxy logs don’t replace Crash logs, so if you’re reporting a crash and using Charles Proxy is also one of the cycle’s requirements, you must attach both to your report.
I can’t find an option to install the SSL certificate in my Android device.
The location of the option to install the SSL certificate on your Android will be different depending on the device. You can use the Chat feature available inside each cycle to ask for help to locate this option on your device.
Why is my internet is not working without the Charles Proxy after I successfully completed the tutorial?
If you completed all the mentioned steps, your device’s traffic data will be routed to the Charles Proxy computer app. After you’ve finished the testing session, you can close the Charles Proxy computer app and return the proxy settings of your mobile device to None (Android) or Off (iOS). This way you’ll close the connection to your computer and your internet will work normally again.
The Charles Proxy app closed in a middle of a session. What happened?
The Charles Proxy computer app can only be used for 30 minutes at most, starting from the time you’ve opened the app. So, if your app is already opened for a while and you found a new bug, it is recommended to close the Charles Proxy program and open it again, so the 30 minutes limit will be reset and you’ll have time to record your log.
I don’t have a desktop computer or a WiFi connection. Can I still test with Charles Proxy?
Unfortunately, a Windows, MacOS or a Linux PC using to the same WiFi your mobile device is connected to is mandatory for capturing Charles Proxy logs. If you don’t match this requirement, you must skip the cycle for now.
Why the Charles Proxy app is not capturing the log of my browser even after successfully set it?
Usually a VPN and other system apps or settings (e.g. firewall or antivirus software) might interfere with Charles Proxy app. We recommend closing all VPN connections and uninstalling all browser extensions to make sure Charles Proxy app is the only proxy linked to the testing environment from your device. You can also use a different browser to monitor the traffic.