https://github.com/lana-20/charles-setup
Configure Charles Web Proxy on Desktops and Smartphones
https://github.com/lana-20/charles-setup
charles charles-proxy debugging debugging-tool greybox greybox-testing mobile-testing network-interceptors proxy-server root-cause-analysis testing testing-tools
Last synced: 3 months ago
JSON representation
Configure Charles Web Proxy on Desktops and Smartphones
- Host: GitHub
- URL: https://github.com/lana-20/charles-setup
- Owner: lana-20
- Created: 2023-03-07T00:32:50.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-10T02:01:13.000Z (over 1 year ago)
- Last Synced: 2025-05-22T21:23:06.668Z (5 months ago)
- Topics: charles, charles-proxy, debugging, debugging-tool, greybox, greybox-testing, mobile-testing, network-interceptors, proxy-server, root-cause-analysis, testing, testing-tools
- Homepage:
- Size: 1.44 MB
- Stars: 5
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
NOTE: This repo has been refurbished and published on Medium: https://medium.com/@begunova/charles-proxy-setup-for-desktops-and-mobile-devices-03c3fd28f882.
# Configure Charles Web Proxy on Desktops and Smartphones
Some test cycles require extended logging of the internet traffic from/to your device or a connection routed through a proxy server. For that purpose, we work with some proxy server software, such as Charles Web Proxy.
Let's go through the installation and configuration steps:
🔵 [Download and install Charles](https://github.com/lana-20/charles-setup/blob/main/README.md#download-and-install)
🔵 [Connect a Smartphone or Tablet to Charles](https://github.com/lana-20/charles-setup/blob/main/README.md#connect-devices)
🔵 [Capture SSL traffic using Charles](https://github.com/lana-20/charles-setup#capture-and-decrypt-ssl-traffic)
🔵 [Export device logs for attaching them to bug reports](https://github.com/lana-20/charles-setup#capture-ssl-logs)
## Download and Install
Although Charles is not an open source software or a free tool, a demo version is available. It can be downloaded and used for free, but limits each session to 30 minutes. Consequently, we have to restart the software now and then, if we want to use it for a more extended period.
Download the OS-appropriate version of [Charles Proxy](https://www.charlesproxy.com/download/).
Once the installation is finished, start the software. We have to wait 10 seconds at every start.
## Connect Devices
As Charles is running now, we want to route all the network traffic from and to our devices through it. Depending on the device you plan to use, perform the following steps matching the device(s).
### Desktops
We are already done! As soon as Charles is running, it automatically captures and records all browser traffic. This procedure typically covers the most common browsers like Chrome, Firefox, Safari, and Edge. You can quickly check the proxy connection by following these steps:
♦ Ensure that **Windows** or **macOS** Proxy is enabled in the Proxy menu.
♦ Click the 🧹 broom button (leftmost) in the Charles toolbar to clean the logs.
♦ Open the browser and navigate to a random site.
♦ Observe new log entries popping up in the Charles log.
♦ You can also pause and resume the logging at any time using the second red/grey button in the toolbar.
If you can see your log filling up, you are good to go.
### Mobile Devices
#### Gather ② crucial pieces of information first.
Before we can configure our mobile device to use Charles, you need to know the IP address of your computer (running Charles) and the port. This can quickly be done as follows:
♦ Click **Help > Local IP Address** to locate the IP. The address consists of four blocks of one to three digits each. In the below captioned examples, it's 192.168.178.100 or 10.0.0.76.
♦ You also need to know the port that Charles is using.
We need both numbers for the next step.
‼️ Important note when connecting *new* mobile devices:
Once a new device tries to connect to your Charles session, Charles will ask you to **grant the permission** to do so. Make sure to allow your connection. We also **disable or appropriately configure any firewall or internet security** and permit incoming traffic to Charles respectively to port 8888 or the port you've determined for Charles before.
#### Connect Android Smartphone
To connect an Android smartphone, head to the WiFi settings and proceed as follows:
♦ Go to **Settings > Network & Internet > Wi-Fi**
♦ Locate the active connection, long-tap it and select **Modify network**
♦ Expand the *Advanced options*, tap at **None** below *Proxy* and select **Manual**
♦ Enter the IP address from the previous step into the *Proxy hostname* field and the port into the *Proxy port* field
♦ Tap Save. 
The settings on your device may look slightly different, but you should find the right area to modify the WiFi network. It will be located around the WiFi network, to which you are currently connected.
#### [Connect iOS Smartphone](https://youtu.be/vtSLoCC299U)
To connect an iOS device, follow these below captioned steps:
♦ Tap **Settings**
♦ Tap **WiFi**
♦ Tap **(i)** right to your selected WiFi network
♦ Scroll to the bottom to the **HTTP PROXY** section
♦ Tap **Manual**
♦ Enter the IP address from above in Server
♦ Enter the port from above in Port
## Capture and Decrypt SSL Traffic
As soon as customers require us to use Charles, they want to know what our mobile device is doing during its communication with their services. If this communication is encrypted, which is great for our day-to-day security, this traffic needs to be decrypted using a certificate. We're going to install this certificate to allow Charles to listen to that communication. Let's start with the desktops again.
### Install Desktop Certificate
Fortunately, Charles already includes this certificate and allows to install it using the menu easily. We have to circumvent a possible pitfall though. Just follow the below captioned process:
♦ Within Charles click **Help > SSL Proxying > Install Charles Root Certificate**
♦ In the new window click **Install certificate** and confirm the first screen unchanged
♦ Now select the second option **Place all certificates in the following store**
♦ Choose **Trusted Root Certification Authorities** as the store and finish the certificate installation wizard
### Install Certificate on Mobile Device
To install the certificate on a mobile device, just do the following:
♦ Be sure that the device is successfully connected to the Charles session:
- Proxy is set to *Manual* and configured in the WiFi settings
- Disconnect any active **VPNs** to avoid issues during the Charles session
- Charles is running and the permission for the device has been granted
- Browse on the phone and new logging entries appear within Charles
♦ Head to the address chls.pro/ssl (which leads to charlesproxy.com/getssl/) on the mobile device
♦ This downloads the certificate and should automatically open an installation prompt
♦ You may insert a name for the certificate like Charles Proxy, if needed, and confirm the installation
♦ Use Google and try searching for *iOS install certificate* for instance, if the installation process is unclear
#### iOS 10.3 or higher
If using iOS 10.3 or higher, additionally follow these steps to trust the certificate:
♦ Navigate to **Settings**
♦ Tap **About**
♦ Tap **Certificate Trust Settings** (bottom of the list)
♦ Trust the *Charles Root Certificate*
### Enable HTTPS Proxying
As our devices are set up for SSL logging now, we just have to enable SSL proxying within Charles as follows:
♦ Within Charles click **Proxy > SSL Proxying Settings...**
♦ In the *SSL Proxying* tab tick **Enable SSL Proxying** and click the **Add** button below
♦ Enter an asterisk * as Host and 443 as Port
♦ Now click **OK** and **OK** again
Restart Charles afterwards.
#### Tailor Coverage to Specific Needs
Above, we entered * as the *Host*. This *wildcard* character enables the SSL proxying for every possible web address or service we may visit. Though we might want to tailor the proxying, and therefore logging, to our needs via specifically including certain addresses or parts of addresses. Using wildcards provides a very versatile way of filtering specific URLs, which we want to cover.
This can become very handy, if we want to limit the coverage to an app or page under test. Let me provide some examples:
- *google* would cover every traffic from and to *google*, which includes *photos.google.com*, *google.com/mail* and so on
- photos.google would include everything from and to *photos.google.com*, but not *google.com/mail* for instance
- google.com/mail would cover the entire *mail* section, but no other section or *photos.google.com*. Though it would cover *photos.google.com/mail/...* if such websites existed.
So we take the relevant part of the address, which may include/exclude or be limited to sub-domains like *calendar* in calendar.google.com and replace the rest of the address with a * to allow every string or even no string (zero or more characters) in its place. You can also use the wildcard ?, which replaces exactly one single character. So go?gle would match *google* or *goggle*, but not *gogle* or *googgle*.
## Capture SSL Logs
Now as Charles is running with the right settings, as the certificates have been installed, as our devices are configured to use Charles on our computer, and as SSL proxying is enabled, we're good to go!
Let's conclude the steps to collect logging information and to export them for to the benefit of a bug report:
♦ Clear the Charles log using the broom button
♦ Be sure that logging is active (red button in the toolbar)
♦ Perform actions or steps to reproduce an issue
♦ Stop the logging by clicking the red button
♦ Head to **File > Save Session as...**
♦ Choose a folder and pick a file name (don't use periods in the name)
♦ Upload the log ending with .chls to the bug report
### Tidy up
After you have finished your Charles session, make sure to close the software and to revert your WiFi settings on the mobile devices to their prior state. Hence we set the Proxy to **None** again, in the WiFi settings. We also remove the certificate from the devices if they are our privately used desktops, smartphones and tablets and not only meant for testing.
If you ever want to start logging in the future, start Charles and add the IP address and port to your WiFi settings again. If the certificate was removed, remember to add it back too.
Happy logging!
____
Charles can be installed in our machines as a desktop app. We can also install it on iOS device without connecting Xcode, but the mobile app has some limitations. The iOS version of Charles covers some extra scenaros, however usually I use the desktop app which is much more feature- and functionality-rich. If interested, you can download and install the iOS version from the App Store for a one-time charge of $8.99. This will allow you decode the traffic right on the mobile device.
Most users use mobile data, not WiFi. An advantage of the iOS version of Charles is being in mobile data and measuring how long the communication takes more accurately, as compared to the desktop version of Charles which operates via the computer's WiFi network. Testing speed measurement is more accurate on the actual mobile device. Also, the iOS version of the Charles app is a little easier to configure than the desktop one. The disadvantage is that it lacks all the cool features of the desktop app, such as Breakpoints, Re-Write, Map Local, etc.
Charles configuration may be a bit complex, but its benefits are more than worth it. There's a 30-day free trial, after which a $50 life-time license is available for purchase. Without a license after a free trial, Charles still works but it shuts down every 30 minutes, which is usually enough to test. You can just restart it and keep testing.
Charles Proxy is pure joyful magic, when it's already configured. We need to download/install Charles, install/add the SSL certificate on Windows or Mac OS, as well as on mobile Android and iOS devices. Once you have the SSL certificate installed on your machine, you need to add the IP address in a couple of places, for example, in Access Control Settings and SSL Proxying Settings.
Sometimes, we configure everything and all works fine, but then we open Charles the next time and see it it not reading any traffic, eveything is encrypted. We might see a lot of red squares with white crosses. In this case, double-check Proxy > Access Control Settings and verify that your IP address is stiil listed there. Sometimes it may be gone without explicit erasure. You may need to add your IP address again. If you end up visiting a friend to showcase how cool Charles is and exiting the home network, your IP address would change. It means you'd have to change it in the Access Control Settings. When you connect your mobile device, you'd use the same IP address to connect it as well. In order to work together, your device and computer should be on the same network.
**Configuring Charles Proxy**:
- [Mac]()
- [Windows]()
- [Mac and iOS device](https://youtu.be/vtSLoCC299U)
- [iOS device]()
- [Android device]()
- [Android emulator](https://youtu.be/WJYf9nkSIKA)
- Sometimes when installing the certificate on an emulator, the page [chls.pro/ssl](chls.pro/ssl) is not loading. This tutorial (TBD), shows an alternative way of installing the certificate on the emulator.
Also you may try to head over to [charlesproxy.com/getssl](charlesproxy.com/getssl) if the short url [chls.pro/ssl](chls.pro/ssl) doesn’t work.