Compose Chaos Proxy: On-Device Network Latency & HTTP Chaos Simulator for Android

Modern mobile applications must gracefully handle harsh real-world network conditions — from spotty subway tunnels and high-latency 3G networks to expired OAuth tokens (401) and server outages (500/503).

Traditionally, testing these states required desktop proxy tools like Charles Proxy, Proxyman, or mitmproxy, involving Wi-Fi proxy configurations and installing custom root SSL certificates on test devices.

compose-chaos-proxy eliminates the desktop proxy requirement by providing an on-device network chaos engine with a floating Jetpack Compose control overlay.

🏗️ Architecture: OkHttp Interceptor + Dynamic Rule Engine

Seamless OkHttp Integration: Plugs directly into your existing OkHttpClient pipeline.
Granular URL Regex Filtering: Target specific endpoints (e.g., /api/v1/checkout.* or /auth/refresh) without affecting analytics or image loading.
Configurable Failure Rates: Simulate flaky connections by failing a percentage of requests (e.g. 25% failure probability).
Custom JSON Mock Payloads: Return custom error JSON responses matching your backend error schemas.

🛠️ Step-by-Step Implementation Guide

1. Add Gradle Dependency

dependencies {
    // Debug builds: on-device network chaos simulator & UI overlay
    debugImplementation("io.github.zakayothuku:compose-chaos-proxy:1.0.0")

    // Release builds: zero-overhead no-op artifact
    releaseImplementation("io.github.zakayothuku:compose-chaos-proxy-noop:1.0.0")
}

2. Attach Interceptor to OkHttpClient

val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(ComposeChaosInterceptor(context = applicationContext))
    .connectTimeout(15, TimeUnit.SECONDS)
    .readTimeout(15, TimeUnit.SECONDS)
    .build()

3. Add the Floating Chaos Control Overlay

Add ComposeChaosOverlay to your root Composable:

@Composable
fun RootApp() {
    Box(modifier = Modifier.fillMaxSize()) {
        AppContent()

        // Draggable floating chaos control trigger
        if (BuildConfig.DEBUG) {
            ComposeChaosOverlay()
        }
    }
}

🧪 Real-World QA & Testing Scenarios

Testing Token Expiry (401 Unauthorized):
- Inject a 401 error rule on /api/v1/user/profile.
- Verify that your Authenticator or refresh token interceptor automatically triggers a refresh and replays the original request seamlessly.
Testing Optimistic UI Rollbacks:
- Inject a 500 Internal Server Error rule on "Like Tweet" or "Add to Cart".
- Verify that your UI immediately updates optimistically, catches the 500 failure, reverts the UI state, and shows a friendly snackbar.
Testing Slow 3G Connections:
- Inject a 3000ms latency rule on product search queries.
- Verify that shimmer loading placeholders display correctly without layout shifts.