Metadata-Version: 2.4
Name: susatest-agent
Version: 0.4.1
Summary: One CLI for SUSATest — autonomous QA, LLM observability, and production SRE for any product
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

One CLI for [SUSATest](https://susatest.com) — autonomous QA, LLM observability, and production SRE for any product, in your terminal.

## Install

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

## Quick start

```bash
# 1. Sign in once (opens your browser)
susatest-agent login

# 2. Test any APK or web URL — no API key flag needed
susatest-agent test my-app.apk
susatest-agent test https://example.com

# 3. Open the dashboard
susatest-agent dashboard
```

After `susatest-agent login`, every other command picks up your saved JWT from `~/.susatest/credentials`. No more `--api-key` on every invocation.

## Commands

### Auth

| Command | What it does |
|---|---|
| `susatest-agent login` | OAuth device-code flow. Opens browser, you sign in once, JWT saved locally with 30-day expiry. |
| `susatest-agent logout` | Revokes the JWT server-side and clears local credentials. |
| `susatest-agent dashboard` | Opens the SUSATest dashboard in your default browser, pre-authenticated. |

### Testing your app

| Command | What it does |
|---|---|
| `susatest-agent test <apk-or-url>` | Upload an APK or point at a web URL; SUSATest runs an autonomous exploration test with the persona you pick and returns an HTML / JSON / JUnit report. |
| `susatest-agent connect` | Bridge a locally-attached Android device to the cloud platform — tests then run against your physical phone. |
| `susatest-agent prepare-device` | One-time setup for a device that will run agent-side network capture (CA cert, frida, marker). |
| `susatest-agent fleet-prep` | Bulk-bootstrap a phone for the fleet — frida + CA + marker + SUSA SMS forwarder + phone-vault registration in one shot. |
| `susatest-agent connect-windows` | Connect this Windows machine to SUSATest as a desktop-test agent. |

### Strategist (autonomous QA brain)

| Command | What it does |
|---|---|
| `susatest-agent strategist list` | List your strategists (each one is bound to a product surface). |
| `susatest-agent strategist run <id> [--action gap_explore] [--wait]` | Fire an on-demand cognition cycle. With `--wait` the CLI blocks until the cycle row lands. |
| `susatest-agent strategist status <id>` | Show the strategist's state plus the last 5 cycle summaries. |

### Opsy (production SRE signals)

| Command | What it does |
|---|---|
| `susatest-agent opsy list-incidents [--status open --severity high]` | List incidents opsy has observed in production. |
| `susatest-agent opsy list-alerts [--status fired]` | List firing alerts. |
| `susatest-agent opsy status` | Health / status summary. |
| `susatest-agent opsy fire-incident --title T --severity S [--services svc1 svc2]` | Create a synthetic incident — verifies the reactive-to-proactive loop. The next strategist cycle ingests it via opsy_signals. |

### Susaeval (LLM observability)

| Command | What it does |
|---|---|
| `susatest-agent susaeval list-sessions [--gate-decision rollback]` | List recent LLM sessions. `gate_decision=rollback` surfaces sessions where eval judges flagged a regression. |
| `susatest-agent susaeval list-incidents` | List susaeval-side incidents. |
| `susatest-agent susaeval drift [--feature model --hours 24]` | Show distribution drift (PSI) on a feature over the last N hours. |
| `susatest-agent susaeval list-safety` | List safety / guardrail findings. |

## Authentication

After `susatest-agent login`, the saved JWT works for `test`, `strategist`, and `dashboard`. CI scripts / older deploys can keep using:

- `--api-key <key>` flag (legacy explicit)
- `SUSA_API_KEY` env var (legacy implicit)
- `OPSY_API_KEY` / `SUSAEVAL_API_KEY` env vars for the opsy / susaeval subcommands (until server-side fan-out lands; see "Known limitations" below).

## Requirements

- Python 3.9+
- ADB installed (`adb` in PATH) if you'll connect Android devices — comes with [Android Studio](https://developer.android.com/studio)

## Known limitations

These exist today and are on the roadmap:

- **Three keys for now.** `opsy` and `susaeval` subcommands still take dedicated keys; the unified user JWT from `login` works for `test` and `strategist` but doesn't yet fan out to the other two subsystems. Single-key everywhere is the next slice.
- **No auto-instrument wrapper yet.** `susatest-agent run -- python app.py` (auto-attaches LLM observability + log forwarding to your existing app, no SDK install required) is the next major feature and is not yet shipped. To get LLM observability on your own product today you still need to install the susaeval SDK by hand.
- **Three dashboards.** Strategist / opsy / susaeval each have their own UI today. Unified nav is roadmap.

## Resources

- Homepage: https://susatest.com
- Docs: https://susatest.com/docs
- Source / issues: https://github.com/monk0062006/SUSA
- Status: https://susatest.com/status

## Changelog

### 0.4.1
- Updated README with full command surface (no functional changes vs 0.4.0).

### 0.4.0
- New `login`, `logout`, `dashboard` commands with OAuth device-code browser flow
- New `strategist` / `opsy` / `susaeval` subcommands
- Saved credentials at `~/.susatest/credentials` — `test` and `strategist` no longer require `--api-key`
- Backward-compat: `--api-key` flag and `SUSA_API_KEY` env var still honored

### 0.3.x
- `connect` / `prepare-device` / `fleet-prep` / `connect-windows` device bridging.

## License

MIT.
