mobile-qatools

Proxyman for QA: guide to inspecting and rewriting HTTP traffic

HTTP/HTTPS traffic between an app and a server is the single biggest source of mobile bugs that are hard to reproduce: analytics, IAP, ads, remote config, A/B tests, push notifications. If you only test “via the UI”, you see half of the picture. Proxyman is a macOS app that intercepts, displays and lets you modify this traffic in real time. It’s a must-have for mobile QA.

What is Proxyman

A local HTTP proxy with a GUI. You run it on your Mac, it captures traffic from the Mac itself and from any device connected to the same Wi-Fi (iOS, Android, simulators). It sees the contents of every request, including HTTPS — once you install the CA certificate.

Effectively an analogue of Charles Proxy and mitmproxy, but with a modern UI and a focus on native mobile development. proxyman.io.

Why mobile QA needs it

  • See what the app actually sends to the server: analytics events, IAP receipts, ad impressions, remote config requests.
  • Rewrite server responses (Map Local) — test the UI against configs that don’t yet exist in production.
  • Throttle the network — check how the game behaves on 3G/2G/packet loss.
  • Set a breakpoint on a request — change status code 200 → 500 on the fly to test error handling.
  • Export a request as curl — paste into a bug report so a developer can reproduce in one command.
  • Diff between builds — what changed in API calls between 1.5 and 1.6.

Installation

On the Mac

  • Download from proxyman.io/download (the free tier covers 90% of QA needs; Pro is a one-time $69).
  • On first run it asks to install a self-signed CA certificate — accept and set it to Always Trust in Keychain.
  • Menu Certificate → Install Certificate on this Mac → enter password.

Connect an iOS device

  • In Proxyman: Tools → iOS Device → Setup — you’ll see the IP and port (usually 9090).
  • On the iPhone: Settings → Wi-Fi → info icon for the current network → Configure Proxy → Manual → enter IP and port.
  • Open Safari on the phone, go to http://proxy.man/ssl — a profile downloads.
  • Settings → General → VPN & Device Management → install the profile.
  • Important: Settings → General → About → Certificate Trust Settings → enable the toggle for the Proxyman CA. Without this, HTTPS won’t decrypt.

Connect an Android device

  • Same proxy in Wi-Fi settings.
  • Download the certificate from http://proxy.man/ssl.
  • Settings → Security → Install certificate → CA certificate.
  • For Android 7+, regular user-installed certificates don’t work for an app unless the app is a debug build. You need network_security_config.xml in the manifest with trust-anchors for user CAs. If your app doesn’t have that — ask the devs to add it to the debug variant.
  • For emulator: launch with emulator -http-proxy http://<mac-ip>:9090.

Key features

SSL Proxying — HTTPS decryption

By default Proxyman shows HTTPS requests with a “green lock” — encrypted. To see the contents — right-click the domain → Enable SSL Proxying. Doing this for all domains is a bad idea (system services will flood your log). Enable it selectively: your API, analytics, ads.

Map Local — rewrite response with a local JSON

The most useful feature for QA. Workflow:

  • Capture the request (e.g. GET /api/levels-config).
  • Right-click → Tools → Map Local.
  • Point to a local JSON file that Proxyman will return instead of the server response.

Use case: the devs haven’t deployed the new config format yet, but you want to verify that the UI renders it correctly. Write the JSON, map it, test — without dependency on the backend.

Map Remote — redirect to another URL

Rewrites the request URL. Use case: your dev build hits production API by default, but you need staging. No rebuild — just add a rule.

Breakpoint — pause mid-request

The request “hangs” before being sent (Request Breakpoint) or before the response is received (Response Breakpoint). A window opens where you edit headers, body, status code, then click Execute. Use case: verify the app correctly handles 401 / 500 / timeout / empty response — without involving the backend team.

Network Conditioner — simulate poor connectivity

Tools → Network Conditions → choose a profile: 3G, Edge, 5% packet loss, high latency. Use case: verify the game doesn’t freeze when the connection drops mid-level-load and shows a proper retry popup instead.

Composer — send custom requests

A Postman-like tool inside Proxyman. Use case: take a real request from the session → duplicate → change one parameter → send → see the response. Test API edge cases without needing the app.

Compare Flows — diff requests

Pick two request/response pairs → Compare. Get a line-by-line diff. Use case: what changed between builds 1.5 and 1.6 in analytics events. What the devs accidentally added or removed.

Scripting — run JavaScript on every request

A Pro feature. Write a JS script applied to request or response: modify headers automatically, measure latency, log specific fields. Use case: an automated test that “no analytics is sent before user consent is granted”.

QA workflow: reproducible bug in 5 minutes

Typical scenario with a mobile game:

  • Connect iPhone to Proxyman, enable SSL proxying for the analytics and IAP domains.
  • Reproduce the bug — e.g., after buying a booster, the HUD counter doesn’t update.
  • In Proxyman find the request POST /v1/iap/verify — response is 200 OK, but JSON contains "granted": false.
  • Right-click → Copy as cURL — paste into the bug report.
  • Optional: Save Session — export a .prxsession file and attach to the ticket. The developer opens it locally and walks through it step by step.

Without Proxyman this bug becomes a multi-hour dance with logs and stacktraces. With Proxyman — diagnosis in 5 minutes.

Tips & tricks

  • Allow list of domains. Filter out everything unrelated to your app (macOS system updates, iCloud, AppStore, Spotlight). View → Filter Bar → type the domain. Instantly readable.
  • Save sessions for every reproduced bug. The file is light, lives locally, can be opened months later.
  • The certificate expires after a year. If one day HTTPS stops decrypting — regenerate the CA in Proxyman: Certificate → Generate New CA → reinstall on devices.
  • Custom Note on a flow. Mark weird requests with text like “bug about double-charge” — easier to search later.
  • Multiple tabs (Pro). Keep one tab for the main app, another for a specific flow like onboarding.

When Proxyman doesn’t fit

  • Non-HTTP traffic (TCP, UDP, WebSocket-binary, raw gRPC) — Wireshark is better.
  • Cross-platform team (Windows/Linux): Proxyman is Mac-only. Alternatives are Charles Proxy (also Mac-only), mitmproxy (CLI, cross-platform), Fiddler (Windows).
  • Production devices where you can’t install a CA certificate — no proxy can decrypt HTTPS, physics says so. Debug builds or freshly-built TestFlight versions only.

Alternatives and comparison

  • Charles Proxy — old standard, exists since 2002. More cluttered UI, slightly less convenient for mobile development. $50.
  • mitmproxy — open-source, CLI + web UI, cross-platform. Powerful for Python scripting, but a higher learning curve.
  • Fiddler — Windows-oriented, Telerik. Fiddler Everywhere exists for Mac, but is less mature.
  • Wireshark — low-level network analyzer. Doesn’t handle HTTPS out of the box. For anything that isn’t HTTP — it’s the tool.

For casual mobile QA on Mac — Proxyman is optimal. For aggressive automation in CI — mitmproxy.

Where to start

  • Install Proxyman on your work Mac.
  • Connect a test iPhone, catch the first HTTPS request from your app.
  • Make one Map Local change — for example, substitute a feature flag in remote config response → see how the UI behaves.
  • Enable Network Conditioner with a 3G profile for 5 minutes — you’ll discover a pile of small UX issues.

Documentation: docs.proxyman.io — official docs. proxyman.io — main site, downloads, licenses.