Metadata-Version: 2.5
Name: quash-api
Version: 0.2.1
Summary: Quash API test runner: run your Quash API test suites from CI with JUnit results, and reach private APIs through the Quash Connector.
Project-URL: Homepage, https://studio.quashbugs.com
Author: Quash
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: jsonpath-ng>=1.6
Requires-Dist: jsonschema>=4.21
Requires-Dist: langchain-core>=1.2.10
Requires-Dist: pydantic>=2.11.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: websockets>=15.0
Provides-Extra: dev
Requires-Dist: fastapi>=0.110; extra == 'dev'
Requires-Dist: import-linter>=2.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: uvicorn>=0.29; extra == 'dev'
Description-Content-Type: text/markdown

# quash-api

`quash-api` is the CI runner for [Quash API](https://studio.quashbugs.com). It runs
your app's API test suites, exported from Quash as a bundle, against one environment,
writes a JUnit report and exits with a code your pipeline can gate on. It is
deterministic: no model runs in the loop.

## Install

```bash
python3 -m pip install quash-api   # Python 3.11 or newer
quash-api --help
```

It carries the execution engine Quash's own runs use: nothing else to install.

## Run

```bash
quash-api run quash-bundle --env=staging --junit quash-report.xml
```

* `quash-bundle` is a directory holding a bundle exported from your app in Quash
  (Apps > *your app* > CI/CD), which also generates a ready-made config for seven CI
  providers.
* `--env` names one of the bundle's environments. Pass it as `--env=NAME`.
* Environment secrets never travel in the bundle: set each as an
  `API_TEST_SECRET_<NAME>` variable, and the runner names any that are missing before it
  sends a request.
* `--junit PATH` writes the JUnit report your CI displays; `--json PATH` writes a
  machine-readable result. `quash-api run --help` lists every flag.

**Exit codes:** `0` every test passed · `1` a test failed · `2` configuration error
(nothing was sent) · `3` runtime error (the API was unreachable; retry) · `130`
interrupted.

## Reach a private API: the Quash Connector

Quash can test an API that only your network can reach (localhost, a VPN, a private
subnet) through the Quash Connector, a command you leave running next to that API. It
opens only outbound HTTPS to Quash, so no inbound port is needed, and it contacts only the
hosts you allow.

1. A workspace owner opens **Connectors** in Quash, creates a connector (for one project,
   or the whole workspace) and copies its key (it is shown once). Quash shows the commands
   below with your address and key filled in.
2. Start it on a machine that can reach your API:

   ```bash
   read -rs QUASH_CONNECTOR_KEY && export QUASH_CONNECTOR_KEY   # paste the qcn_… key
   quash-api connector --server https://<your Quash API address> --allow api.example.com:8080
   ```

3. In your app's environment, choose the connector under **Network**. That environment's
   runs and test generation then go through it.

* `--allow HOST[:PORT]` names a host the connector may reach. Repeat it for more;
  `*.corp.example` matches sub-domains. A host without a port means its default port only
  (80 for `http`, 443 for `https`); write `HOST:PORT` for any other. Nothing else is ever
  contacted.
* `--server` must be an `https://` address (`http://` is accepted only for this machine:
  `localhost`, `127.0.0.1`, `::1`), so the key never crosses a network in clear.
* The connector verifies every TLS certificate. An environment set not to verify TLS (a
  self-signed internal certificate) is honoured only when you start the connector with
  `--insecure-tls`.
* The key is read from `QUASH_CONNECTOR_KEY`, so it stays off the command line and out of
  `ps`. `read -rs` keeps it out of your shell history too; typing
  `export QUASH_CONNECTOR_KEY=qcn_…` would put it there.
* It stops and says why when its key is refused: the connector was revoked, or the owner
  who created it is no longer a workspace owner. A workspace owner then creates a new one.
  A suspended workspace is not a refused key: the connector says so once, waits, and
  serves again when the workspace is approved.

## License

Proprietary. Copyright (c) 2026 Quash. For use with Quash API only. See `LICENSE`.
