Metadata-Version: 2.4
Name: susatest-agent
Version: 0.3.0
Summary: Local agent for SUSATest — connects your Android or Windows device to the cloud testing platform
Author-email: SUSATest <support@susatest.com>
License: MIT
Project-URL: Homepage, https://susatest.com
Project-URL: Documentation, https://susatest.com/docs
Project-URL: Repository, https://github.com/modernmysitc/SUSA
Keywords: testing,android,qa,automation,adb,mobile-testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Testing
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Provides-Extra: windows
Requires-Dist: uiautomation==2.0.20; extra == "windows"
Requires-Dist: pywinauto==0.6.8; extra == "windows"
Requires-Dist: psutil>=5.9.0; extra == "windows"
Requires-Dist: Pillow>=10.0.0; extra == "windows"

# susatest-agent

Local agent for [SUSATest](https://susatest.com) — connects your Android device to the cloud testing platform.

## Install

```bash
pip install susatest-agent
```

## Usage

1. Get your API key at: https://susatest.com/app/settings
2. Connect your Android device via USB (USB debugging enabled)
3. Run:

```bash
susatest-agent connect --api-key susa_YOUR_API_KEY
```

Your device will appear in the SUSATest dashboard. Upload an APK and tests run directly on your phone.

## Requirements

- Python 3.9+
- ADB installed (`adb` in PATH) — comes with [Android Studio](https://developer.android.com/studio)
- Android device connected via USB with USB debugging enabled

## Commands

```bash
# Connect to SUSATest (default server)
susatest-agent connect --api-key susa_xxxx

# Connect specific device (if multiple)
susatest-agent connect --api-key susa_xxxx --device R5CR1234567

# Custom server URL
susatest-agent connect --api-key susa_xxxx --server https://your-server.com

# Custom ADB path
susatest-agent connect --api-key susa_xxxx --adb-path /path/to/adb

# Agent-side network capture (SPEC-114, see below)
susatest-agent prepare-device --device <serial>
susatest-agent connect --api-key susa_xxxx --device <serial> --with-proxy
```

## How It Works

The agent runs an HTTP long-poll loop against susatest.com (no WebSocket;
App Runner doesn't support WS). When you start a test on the website:

1. Server queues commands (tap, screenshot, swipe, etc.) for your agent
2. Agent polls `/api/agent/poll` (blocks up to 30s)
3. Agent executes commands via ADB on your local device
4. Agent POSTs results back to the server

No inbound ports needed — the connection is outbound only.

## Agent-side network capture (SPEC-114)

For HTTPS traffic capture during mobile sessions (feeds the pentest layer),
the agent can run a local mitmproxy that the test device is configured to
proxy through. This needs one-time prep per device.

### One-time prep

```bash
pip install -U mitmproxy frida-tools requests
susatest-agent prepare-device --device <serial>
```

`prepare-device` walks you through:

1. Generating the mitmproxy CA cert (auto-runs `mitmdump --version`).
2. Pushing the CA to `/sdcard/mitmproxy-ca-cert.cer`.
3. Opening the device's certificate-install screen (you tap through:
   name the cert → OK).
4. Detecting the device CPU arch + pushing the matching frida-server
   binary to `/data/local/tmp/frida-server`.
5. Creating `/sdcard/.susatest-test-rig` marker so subsequent runs
   know this is a prepared rig.

### Per session

```bash
susatest-agent connect --api-key susa_xxxx --device <serial> --with-proxy
```

The `--with-proxy` flag runs preflight on startup; if any check fails
(mitmdump missing, CA cert missing, marker file absent), the agent
prints actionable fix steps and exits non-zero rather than starting
in a broken state.

When a session starts on the server, the agent receives `start_proxy`,
spawns mitmdump on a free local port (9100+), configures the device's
HTTP proxy via `adb reverse`, optionally injects a Frida SSL pinning
bypass on app spawn, and the mitmproxy addon POSTs each captured flow
to the SUSA backend's ingest endpoint. Flows include the full request
+ response (headers, bodies up to 10KB, status, response time).

For the operator validation runbook see `docs/SPEC-114-PHASE-4-RUNBOOK.md`
in the SUSA repo.

### Force flag (NOT recommended for daily-driver phones)

```bash
susatest-agent connect --api-key susa_xxxx --device <serial> --with-proxy --force
```

`--force` skips the test-rig marker check. Use only on devices you've
manually prepared. **Do not use on a phone you use for normal browsing**
— the proxy setting would route all your HTTP traffic through a defunct
proxy after the agent stops.

## License

MIT
