qmpass-test-agent 1.0.10__tar.gz

qmpass_test_agent-1.0.10/LICENSE

@@ -0,0 +1,15 @@
+Qmpass Test Agent
+Copyright (c) 2026 Qmpass. All rights reserved.
+
+This software is proprietary. It is made available solely for use with a Qmpass subscription, to
+connect machines you control to the Qmpass platform and run tests on them.
+
+You may install and run unmodified copies of this software for that purpose. You may not modify,
+redistribute, sublicense, sell, reverse engineer (except where the law permits it), or use this
+software, or any part of it, to build a competing product or service.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT
+SHALL QMPASS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM THE USE OF THE
+SOFTWARE.
+
+Use of the software is also subject to the Qmpass terms of service.

qmpass_test_agent-1.0.10/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: qmpass-test-agent
+Version: 1.0.10
+Summary: Run your Qmpass automated tests on your own machines, securely connected to your Jira projects.
+Author: Qmpass
+License-Expression: LicenseRef-Proprietary
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets==15.0.1
+Requires-Dist: requests==2.34.2
+Requires-Dist: psutil==6.1.1
+Requires-Dist: truststore==0.10.4
+Requires-Dist: robotframework==7.4.2
+Requires-Dist: robotframework-browser==19.10.1
+Requires-Dist: robotframework-requests==0.9.7
+Requires-Dist: robotframework-datadriver==1.11.2
+Requires-Dist: robotframework-faker==6.0.0
+Requires-Dist: robotframework-databaselibrary==2.3.1
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary==2.9.10; extra == "postgres"
+Provides-Extra: mysql
+Requires-Dist: pymysql==1.1.1; extra == "mysql"
+Provides-Extra: salesforce
+Requires-Dist: rpaframework==33.0.1; extra == "salesforce"
+Provides-Extra: desktop
+Requires-Dist: pystray==0.19.5; extra == "desktop"
+Requires-Dist: Pillow==11.3.0; extra == "desktop"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: pip-tools>=7.0.0; extra == "dev"
+Dynamic: license-file
+
+# Qmpass Test Agent
+
+Run your [Qmpass](https://qmpass.ai) automated tests on your own laptops, servers or virtual
+machines — faster feedback, safer releases, and full control over your test environments.
+
+## Requirements
+
+- Python 3.10 or newer
+- Node.js 18 or newer (for Browser tests)
+- An agent token from Qmpass: **Project settings → Agents → Add agent**
+
+## Install
+
+```bash
+pipx install qmpass-test-agent          # or: pipx install "qmpass-test-agent[postgres]" / [mysql] / [salesforce]
+qmpass-agent setup                      # one time: installs the browser used by Browser tests
+qmpass-agent doctor                     # checks everything below, with a fix for each problem
+```
+
+`doctor` checks Python, Robot, Node.js and Chromium, your `QMPASS_TOKEN` / `QMPASS_URL`, that
+Qmpass can be reached, and that the token is accepted — without starting a session, so it's safe to
+run while an agent is already running.
+
+Optional add-ons, only needed if your tests use them:
+
+| Add-on | Install | For tests that |
+|---|---|---|
+| `postgres` | `pipx install "qmpass-test-agent[postgres]"` | query a PostgreSQL database |
+| `mysql` | `pipx install "qmpass-test-agent[mysql]"` | query a MySQL / MariaDB database |
+| `salesforce` | `pipx install "qmpass-test-agent[salesforce]"` | work with Salesforce (large install) |
+
+No pipx yet? `brew install pipx` (macOS), `python3 -m pip install --user pipx` (Windows / Linux),
+then `pipx ensurepath`.
+
+## Run
+
+Copy the command shown with your agent token in Qmpass, or:
+
+```bash
+export QMPASS_TOKEN=qmp_agent_…
+qmpass-agent run
+```
+
+The agent connects to `https://api.qmpass.ai` (set `QMPASS_URL` for other deployments), waits for
+jobs, and logs one line when each run starts and finishes.
+
+Useful options: `--worker N` (parallel jobs, up to 5), `--log-file PATH`, `--log-format json`,
+`--log-level DEBUG`. Run `qmpass-agent --help` for all commands.
+
+## Update
+
+```bash
+pipx upgrade qmpass-test-agent
+```
+
+When a newer version is available, `qmpass-agent run` says so in one line at startup (and `doctor`
+shows it). The agent never updates itself. Set `QMPASS_AGENT_UPDATE_CHECK=0` to turn the check off.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Stopped normally |
+| 2 | Configuration error |
+| 3 | Refused by the platform (invalid or expired token, agent disabled) — the log says which |
+| 4 | Agent too old — run `pipx upgrade qmpass-test-agent` |
+| 5 | A prerequisite is missing (e.g. Node.js) — run `qmpass-agent setup` |
+
+## License
+
+Proprietary — for use with a Qmpass subscription. See `LICENSE`.

qmpass_test_agent-1.0.10/README.md

@@ -0,0 +1,433 @@
+# Qmpass Test Agent
+
+Python agent that connects to the **Qmpass platform gateway** via **WebSocket** and executes test jobs locally. Package namespace: `qmpass.*`.
+
+Product Robot suite **codegen** is platform-side (`qmpass-robot-compiler`). This agent writes precompiled `robotSuites`, runs Robot Framework, and publishes results.
+
+## How to run the agent
+
+| Path | When to use |
+|------|-------------|
+| **pipx** (laptops, from PyPI) | `pipx install qmpass-test-agent`, `qmpass-agent setup` (Browser / Chromium), `qmpass-agent doctor` (checks everything) — see `README.pypi.md`, the PyPI page. |
+| **Docker** (preferred for shared runners / CI) | Isolated image; no host Python. See [Deployment Options](#deployment-options). |
+| **Local install in a dedicated venv** | QA laptops that must use **local browsers** (Robot Browser / Playwright on this machine). |
+
+Do **not** install into the system Python or rely on a bare `python` on `PATH`. On many Macs that points at Python 2.7 and Robot will fail with `No module named Browser`. Always use an isolated environment so `qmpass-agent` and Robot share the same interpreter.
+
+## Prerequisites
+
+- **Python 3.10+** (3.11 or 3.12 recommended) — used only to create the venv below
+- **Node.js ≥ 18** on `PATH` (required by Robot Framework Browser / Playwright)
+- **QMPASS_TOKEN** (from the Qmpass UI when creating an agent)
+- **QMPASS_URL** (optional; defaults to `https://api.qmpass.ai`): set it for dev / staging / other deployments — the URL is shown with your agent token in Qmpass (Project settings → Agents → **Copy command**); plain `http://` only for a local stack such as `http://localhost:30085`
+
+## Quick Start (local browsers — isolated `qmpass-agent` env)
+
+Full path for a laptop that needs local Browser/Playwright. Create a **new** venv named for Qmpass, activate it, install into that env, then run. Do not use system Python.
+
+You can create the venv from **any directory**. You only need the agent repo checkout when installing from source (`pip install -e .`). Once the agent is published as a package, install by name — no clone required.
+
+### macOS / Linux — first-time setup
+
+```bash
+# 1) Confirm a real Python 3.10+ (do not use bare `python` if it is 2.x)
+python3 --version
+
+# 2) Create a dedicated env (any working directory is fine)
+python3 -m venv ~/.venvs/qmpass-agent
+
+# 3) Activate it (required for all following steps)
+source ~/.venvs/qmpass-agent/bin/activate
+# Prompt should show (qmpass-agent); `which python` → ~/.venvs/qmpass-agent/bin/python
+
+# 4) Upgrade pip inside the venv only
+python -m pip install --upgrade pip setuptools wheel
+
+# 5) Install agent + Robot / Browser deps into this env
+#
+# From a source checkout (current / development):
+cd /path/to/qmpass-test-agent
+pip install -e .
+#
+# Later, when distributed as a package (no repo needed):
+# pip install qmpass-test-agent
+#
+# Optional tray app (same env):
+# pip install -e ".[desktop]"
+# # or: pip install "qmpass-test-agent[desktop]"
+# Salesforce REST (RPA.Salesforce / rpaframework) — large optional install:
+# pip install -e ".[salesforce]"
+# # or: pip install "qmpass-test-agent[salesforce]"
+
+# 6) Install Playwright browsers used by Robot Framework Browser (same env)
+python -m Browser.entry init
+
+# 7) Configure and start (venv still activated)
+export QMPASS_TOKEN="qmp_agent_xxxx"
+# export QMPASS_URL="http://localhost:30085"   # only off production; default is https://api.qmpass.ai
+qmpass-agent run
+```
+
+### macOS / Linux — every later session
+
+```bash
+source ~/.venvs/qmpass-agent/bin/activate
+export QMPASS_TOKEN="qmp_agent_xxxx"
+qmpass-agent run
+```
+
+(No need to `cd` into the repo unless you are reinstalling or developing.)
+
+### Windows (PowerShell) — first-time setup
+
+```powershell
+py -3.11 --version
+py -3.11 -m venv $HOME\venvs\qmpass-agent
+$HOME\venvs\qmpass-agent\Scripts\Activate.ps1
+
+python -m pip install --upgrade pip setuptools wheel
+
+# From source (current):
+cd C:\path\to\qmpass-test-agent
+pip install -e .
+# Packaged release (later): pip install qmpass-test-agent
+
+python -m Browser.entry init
+
+$env:QMPASS_TOKEN = "qmp_agent_xxxx"
+qmpass-agent run
+```
+
+### Verify (optional)
+
+With `qmpass-agent` venv activated:
+
+```bash
+which python          # .../qmpass-agent/bin/python  (not system 2.7)
+which qmpass-agent    # .../qmpass-agent/bin/qmpass-agent
+python -c "import Browser, robot; print('ok', robot.__version__)"
+node --version        # >= 18
+```
+
+Robot uses the same interpreter as the agent (`sys.executable`). You normally do **not** set `QMPASS_AGENT_PYTHON_BIN` when running from this venv.
+
+## Configuration
+
+Contributor conventions: see **[AGENTS.md](./AGENTS.md)** (includes how to add platform library adapters: Browser, RequestsLibrary, DatabaseLibrary, …).
+
+| Variable | Required | Description |
+| --------------------------- | -------- | --------------------------------------------------------------------------- |
+| QMPASS_TOKEN | Yes | Token shown once when creating an agent in the UI |
+| QMPASS_URL | No | Base URL of the gateway (shown with the agent token); default `https://api.qmpass.ai`. Must be `https://` except for localhost / 127.0.0.1 / host.docker.internal |
+| MAX_PARALLEL_JOBS | No | Same as `--worker` / `--concurrency` when the CLI flag is omitted (default **1**, max **5**) |
+| QMPASS_AGENT_KEEP_ROBOT_ARTIFACTS | No | If `true`, keep per-job temp dirs with Robot logs instead of deleting them |
+| QMPASS_AGENT_RUN_ROOT | No | Base directory for per-job run artifacts (default: system temp dir) |
+| QMPASS_AGENT_LAST_RUN_DIR | No | Fixed dir for local debug (`--worker=1` only). GATE: keeps `{target}.zip` per target |
+| QMPASS_AGENT_PYTHON_BIN | No | Python for `python -m robot` (default: agent `sys.executable`) |
+| QMPASS_AGENT_UPLOAD_ARTIFACTS | No | If `true`, upload Robot artifacts for DRY runs (GATE always uploads) |
+| QMPASS_AGENT_ARTIFACT_MAX_SIZE_MB | No | Max per-file size (MB) for uploads (default 50) |
+| QMPASS_AGENT_ROBOT_TIMEOUT_SEC | No | Default Robot timeout seconds when payload has no `timeoutMs` (default 600) |
+| QMPASS_AGENT_ROBOT_EXIT_ON_FAILURE | No | Pass `--exitonfailure` to Robot |
+| QMPASS_AGENT_ROBOT_INCLUDE_STEPS | No | Enrich results with `robot.steps[]` |
+
+**Breaking change:** older env prefixes from earlier agent builds are no longer read. Use `QMPASS_AGENT_*` only.
+
+The agent connects to `QMPASS_URL` over WebSocket at `/api/v1/agent/ws`, sending its token as `Authorization: Bearer <QMPASS_TOKEN>` (never in the URL). Jobs are pushed by the platform over the socket; results are sent back the same way. If the connection drops, running jobs carry on: the agent reconnects (backoff 2–30s, reset after a good connection) and sends any results that finished meanwhile.
+
+## Deployment Options
+
+- **Docker** (recommended for shared runners / CI): build from `docker/Dockerfile` using frozen locks under `requirements/` (see [`requirements/README.md`](./requirements/README.md)).
+
+```bash
+# Base image (default) — Browser / Requests / Database / DataDriver / Faker
+docker build -f docker/Dockerfile -t qmpass-test-agent:base .
+
+# Salesforce image — base + RPA.Salesforce (rpaframework)
+docker build -f docker/Dockerfile --build-arg AGENT_VARIANT=salesforce -t qmpass-test-agent:salesforce .
+
+docker run --rm -e QMPASS_TOKEN=… -e QMPASS_URL=… qmpass-test-agent:base
+# Includes Node.js and Playwright Chromium; Browser environments must run headless in containers.
+```
+
+  Runs as non-root. Laptop/dev can still `pip install -e .` without the lock; Docker/CI **must** use the lock files.
+
+- **CLI (venv)**: follow [Quick Start](#quick-start-local-browsers--isolated-qmpass-agent-env). Ctrl+C triggers graceful disconnect.
+- **Desktop**: `qmpass-agent desktop` or `qmpass-agent-desktop` — tray app; install with `pip install -e ".[desktop]"` **inside the same venv**.
+
+## Logs and exit codes
+
+The agent logs one line per event that matters: a startup summary, connection changes, and one
+line when each run starts and finishes (result, duration, tests, artifacts). Robot's own console
+output and the platform protocol are at `DEBUG`.
+
+```
+2026-10-05T09:12:03+05:30 INFO  Connected as agent "QA-Laptop-01" (project DEMO). Waiting for jobs.
+2026-10-05T09:14:10+05:30 INFO  [run 3f2a1c9e] Run 3f2a1c9e started: runbook "Checkout smoke" on "Staging" (timeout 10m)
+2026-10-05T09:14:53+05:30 INFO  [run 3f2a1c9e] Run 3f2a1c9e passed in 43s: 12/12 tests passed · 5 artifacts uploaded (2.1 MB)
+```
+
+| Option | Env var | Default |
+|--------|---------|---------|
+| `--log-level DEBUG\|INFO\|WARNING\|ERROR` | `QMPASS_AGENT_LOG_LEVEL` | `INFO` |
+| `--log-file PATH` (rotated, 10 MB × 5) | `QMPASS_AGENT_LOG_FILE` | none (desktop app: `~/Library/Logs/Qmpass/agent.log`, `%LOCALAPPDATA%\Qmpass\Logs\agent.log`, `~/.local/state/qmpass/agent.log`) |
+| `--log-format text\|json` (JSON: one object per line) | `QMPASS_AGENT_LOG_FORMAT` | `text` |
+
+Agent and project tokens, presigned URL signatures and the current runs' secret values are masked
+(`********`) in every log line.
+
+| Exit code | Meaning |
+|-----------|---------|
+| 0 | Stopped normally |
+| 2 | Configuration error (e.g. `QMPASS_URL` invalid) |
+| 3 | The platform refused this agent: invalid or expired token, or agent disabled — the log says which |
+| 4 | Agent too old for the platform — update `qmpass-test-agent` |
+| 5 | A prerequisite is missing (e.g. Node.js) |
+
+Network problems, a platform restart or another process using the token are retried (the reason is
+logged once, then a reminder every 5 minutes).
+
+## Security
+
+- **Environment secrets** (database / API / Salesforce passwords and tokens) never appear in the
+  suite: it reads them as `%{QMPASS_…}`, and the agent passes their values to Robot only as
+  environment variables. After each run their values are masked (`********`) in `output.xml` and the
+  text artifacts, and `log.html` / `report.html` are rebuilt from the masked output before upload.
+- **The agent token** never reaches Robot: runbooks can't read `%{QMPASS_TOKEN}`.
+- **`QMPASS_URL`** defaults to production (`https://api.qmpass.ai`); a token only works on the platform
+  that issued it, so dev / staging agents set it. It must be `https://` (plain `http://` only for
+  localhost / `host.docker.internal`).
+- **TLS** is verified against the operating system's trust store (macOS Keychain, Windows store,
+  `/etc/ssl`), so company proxies with their own root CA work and python.org Python needs no
+  "Install Certificates" step. `SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE` override it; certifi is the
+  fallback. Verification is never disabled.
+- **Run folders** under `QMPASS_AGENT_RUN_ROOT` are private to the agent's user (`0700`).
+- **The recorder socket** (`127.0.0.1`) accepts only the Qmpass browser extension, not web pages.
+- **Version:** the platform refuses agents older than its minimum (currently 1.0.0); update the agent
+  when it says so.
+
+## CLI Commands
+
+| Command | Description |
+| ----------------------- | -------------------------------------------------------- |
+| `qmpass-agent run` | Run agent (WebSocket connection; default **1** concurrent checkpoint job) |
+| `qmpass-agent run --worker=N` | Up to **N** concurrent checkpoint jobs (max **5**; aliases `--workers`, `--concurrency`) |
+| `qmpass-agent run-robot` | Run a `.robot` file using the agent's Python (libraries resolve) |
+| `qmpass-agent desktop` | Launch desktop tray application |
+| `qmpass-agent version` | Print version |
+
+### Running generated .robot files
+
+At runtime, each job is executed in its **own temporary directory** with a predictable structure.
+
+- **Root directory**:
+  - Defaults to the system temp directory from `tempfile.gettempdir()` (e.g. `/tmp`).
+  - Can be overridden via `QMPASS_AGENT_RUN_ROOT`.
+- **Per-job structure**:
+
+```text
+<QMPASS_AGENT_RUN_ROOT or /tmp>/qmpass/<scriptId>/<correlationId>/
+    runbook.robot
+    logs/
+      output.xml
+      log.html
+      report.html
+      playwright-log.txt
+      ...
+```
+
+The agent:
+
+- Builds `runbook.robot` under the per-job directory.
+- Runs `<agent-python> -m robot --outputdir <job-dir>/logs <job-dir>/runbook.robot`.
+- Parses `<job-dir>/logs/output.xml` into the job result.
+
+By default, the per-job directory is **deleted** after the result is built.
+
+This uses the agent's Python environment so `Browser` and `RequestsLibrary` resolve correctly. Extra args are passed through to Robot Framework:
+
+```bash
+qmpass-agent run-robot runbook.robot --loglevel DEBUG
+```
+
+If you want to inspect full Robot artifacts (log.html, output.xml, report.html, playwright-log.txt) per job, set:
+
+```bash
+export QMPASS_AGENT_KEEP_ROBOT_ARTIFACTS=true
+# optional root (still creates qmpass/<scriptId>/<correlationId>/):
+export QMPASS_AGENT_RUN_ROOT=/Users/mehul/qmpass-runs
+```
+
+For **local debugging of only the latest run** (same path every time):
+
+```bash
+export QMPASS_AGENT_LAST_RUN_DIR=/Users/mehul/qmpass-runs/last
+```
+
+For **DRY / non-GATE** jobs, `$QMPASS_AGENT_LAST_RUN_DIR` keeps `runbook.robot` and `logs/` after each run (overwrites the previous job). `QMPASS_AGENT_LAST_RUN_DIR` implies keep (no cleanup).
+
+For **GATE multi-target** runs (e.g. Chrome + Firefox), each target produces `{target}.zip` under the same directory. Staging `runbook.robot` and `logs/` are removed after each target zip is built — only the zips (plus `.qmpass-last-run-scope`) remain. Sibling target zips are kept until you start a different checkpoint.
+
+In that case, the per-job temp directories are not removed and can be inspected manually.
+S3 upload still runs for GATE (and for DRY when `QMPASS_AGENT_UPLOAD_ARTIFACTS=true`); keep mode
+only skips deleting the local work dir after upload.
+
+## Robot Execution Result Schema
+
+When a job is executed via Robot Framework, `task_runner.execute(job)` returns a JSON-like structure that the platform uses to update execution state.
+
+- **Top-level shape**:
+
+```jsonc
+{
+  "status": "PASS",                // overall result: PASS / FAIL
+  "id": "6f99-...",                // correlationId from TASK_REQUEST
+  "jobId": "job-123",              // optional, from execution
+  "executionId": "exec-123",       // optional, from execution
+  "executionTestCaseId": "etc-1",  // optional, from execution
+  "runType": "DRY",                // NORMAL / DRY / ...
+  "robot": { ... }                 // Robot-specific details
+}
+```
+
+- **`robot` envelope**:
+
+```jsonc
+"robot": {
+  "status": "PASS",          // suite-level PASS / FAIL
+  "startTime": "2026-03-03T12:00:01.636578",
+  "elapsedMs": 3336,         // suite elapsed time in milliseconds
+  "statistics": {
+    "total": { "pass": 1, "fail": 0, "skip": 0 }
+  },
+  "tests": [
+    {
+      "id": "s1-t1",
+      "name": "Script 698cafa474778f72c4c09134",
+      "status": "PASS",
+      "startTime": "2026-03-03T12:00:03.483515",
+      "elapsedMs": 1455
+    }
+  ],
+  "errors": [
+    {
+      "time": "2026-03-03T12:00:04.000000",
+      "level": "ERROR",
+      "text": "Suite setup failed: ..."
+    }
+  ],
+  "robotExitCode": 0          // exit code from the Robot subprocess
+}
+```
+
+- **Notes**:
+  - `status` at the top level mirrors `robot.status`. The platform uses this to decide if the job is considered successful.
+  - `tests[*]` maps directly to `<test>` elements in `output.xml`. Today there is one test per script: `Script <scriptId>`.
+  - `errors` contains suite-level errors from the `<errors>` block in `output.xml`.
+  - When `QMPASS_AGENT_ROBOT_INCLUDE_STEPS` is enabled, an additional `robot.steps[]` collection is populated with flattened step-level data (keywords and control structures) for debugging/analytics.
+  - Additional optional fields (for example, richer step-level data) will be added under `robot` to avoid breaking existing consumers.
+
+## Startup & Preflight Checks
+
+On startup (`qmpass-agent run`), the agent performs a **preflight environment check** before connecting to the platform:
+
+- **Node.js / Browser**:
+  - Runs `node --version` and validates that:
+    - `node` is available in `PATH`.
+    - The major version is **≥ 18**.
+  - If the check fails, the agent logs a clear error like:
+    - `Browser library requires Node.js >= 18, but found 16.20.2. Agent cannot start.`
+  - In this case the agent **exits with code 1** and does not go ONLINE.
+
+At **job execution time**, an additional per-job check is performed:
+
+- If Node.js is not suitable when a job is received:
+  - The Robot subprocess is **not** started.
+  - The job result contains:
+    - `status: "FAIL"`
+    - `robot.error` with a human-readable message explaining the Node/Browsers requirement issue.
+
+These checks are designed to:
+
+- Fail fast on obvious misconfiguration at startup.
+- Prevent individual jobs from hanging when Browser/Playwright cannot be started.
+
+## Package Structure
+
+```
+qmpass/
+  __init__.py          # __version__, Settings, run
+  cli.py               # CLI entry (run, desktop, version)
+  desktop.py           # Tray app (optional)
+  __main__.py          # python -m qmpass
+  agent/
+    runtime.py         # Process bootstrap (signals + WS loop)
+    system_info.py     # x-agent-info handshake
+    client/            # WebSocket connection
+    runner/            # Job execution (execute, robot_process, work_dir, cancel)
+    robot/             # Suite generation + adapters
+    recorder/          # Recording / playback
+    artifact_upload.py
+  config/
+    settings.py        # Settings SSOT from env
+```
+
+## Recorder extension
+
+The recorder's browser extension ships inside the package at `src/qmpass/agent/recorder/sidebar/`
+(package data, so pip / pipx / Docker installs all have it). The in-page widget
+(`content-script/ui/qmpass-recorder-widget.js`) is built in **qmpass-test-recorder-web** with
+`npm run build:widget`, which copies it there; commit the rebuilt file with the change.
+
+## Releasing to PyPI
+
+PyPI never accepts the same version twice, so **any** change that reaches the package, including
+only the PyPI page (`README.pypi.md`) or `pyproject.toml` metadata, needs a new version.
+
+**1. Bump the version** (semver: patch for fixes and docs, minor for new features, major for
+breaking changes such as renamed env vars or CLI flags). It lives in two places, which must match:
+
+- `pyproject.toml` → `version = "X.Y.Z"`
+- `src/qmpass/__init__.py` → `__version__ = "X.Y.Z"` (shown by `qmpass-agent --version` and at startup)
+
+**2. Check, then build a clean wheel**
+
+```bash
+source ~/.venvs/qmpass-agent/bin/activate
+python -m pip install build twine
+ruff check src tests && pytest -q
+rm -rf build dist src/*.egg-info   # stale files would end up in the wheel
+python -m build --wheel            # wheel only: no tests or repo files in the release
+twine check dist/*                 # validates metadata and that README.pypi.md renders
+```
+
+**3. Smoke-test the wheel in a throwaway env**
+
+```bash
+python3 -m venv /tmp/qmpass-release && /tmp/qmpass-release/bin/pip install dist/*.whl
+/tmp/qmpass-release/bin/qmpass-agent --version   # prints X.Y.Z
+/tmp/qmpass-release/bin/qmpass-agent doctor      # with QMPASS_TOKEN set
+rm -rf /tmp/qmpass-release
+```
+
+**4. Commit, then upload**
+
+```bash
+git commit -am "Release X.Y.Z: <what changed>"
+twine upload dist/*                # username __token__, password = your PyPI API token
+```
+
+Check https://pypi.org/project/qmpass-test-agent/ shows the new version, then
+`pipx upgrade qmpass-test-agent` (or `pip install -U qmpass-test-agent`). Running agents mention the
+new version at startup (see `update_check.py`).
+
+## Development
+
+Use **VS Code** (or any editor). The repo ignores `.idea/` and `.vscode/` so local IDE settings stay out of git.
+
+```bash
+# Prefer the same dedicated venv as local install
+source ~/.venvs/qmpass-agent/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check src tests
+```

qmpass_test_agent-1.0.10/README.pypi.md

@@ -0,0 +1,71 @@
+# Qmpass Test Agent
+
+Run your [Qmpass](https://qmpass.ai) automated tests on your own laptops, servers or virtual
+machines — faster feedback, safer releases, and full control over your test environments.
+
+## Requirements
+
+- Python 3.10 or newer
+- Node.js 18 or newer (for Browser tests)
+- An agent token from Qmpass: **Project settings → Agents → Add agent**
+
+## Install
+
+```bash
+pipx install qmpass-test-agent          # or: pipx install "qmpass-test-agent[postgres]" / [mysql] / [salesforce]
+qmpass-agent setup                      # one time: installs the browser used by Browser tests
+qmpass-agent doctor                     # checks everything below, with a fix for each problem
+```
+
+`doctor` checks Python, Robot, Node.js and Chromium, your `QMPASS_TOKEN` / `QMPASS_URL`, that
+Qmpass can be reached, and that the token is accepted — without starting a session, so it's safe to
+run while an agent is already running.
+
+Optional add-ons, only needed if your tests use them:
+
+| Add-on | Install | For tests that |
+|---|---|---|
+| `postgres` | `pipx install "qmpass-test-agent[postgres]"` | query a PostgreSQL database |
+| `mysql` | `pipx install "qmpass-test-agent[mysql]"` | query a MySQL / MariaDB database |
+| `salesforce` | `pipx install "qmpass-test-agent[salesforce]"` | work with Salesforce (large install) |
+
+No pipx yet? `brew install pipx` (macOS), `python3 -m pip install --user pipx` (Windows / Linux),
+then `pipx ensurepath`.
+
+## Run
+
+Copy the command shown with your agent token in Qmpass, or:
+
+```bash
+export QMPASS_TOKEN=qmp_agent_…
+qmpass-agent run
+```
+
+The agent connects to `https://api.qmpass.ai` (set `QMPASS_URL` for other deployments), waits for
+jobs, and logs one line when each run starts and finishes.
+
+Useful options: `--worker N` (parallel jobs, up to 5), `--log-file PATH`, `--log-format json`,
+`--log-level DEBUG`. Run `qmpass-agent --help` for all commands.
+
+## Update
+
+```bash
+pipx upgrade qmpass-test-agent
+```
+
+When a newer version is available, `qmpass-agent run` says so in one line at startup (and `doctor`
+shows it). The agent never updates itself. Set `QMPASS_AGENT_UPDATE_CHECK=0` to turn the check off.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Stopped normally |
+| 2 | Configuration error |
+| 3 | Refused by the platform (invalid or expired token, agent disabled) — the log says which |
+| 4 | Agent too old — run `pipx upgrade qmpass-test-agent` |
+| 5 | A prerequisite is missing (e.g. Node.js) — run `qmpass-agent setup` |
+
+## License
+
+Proprietary — for use with a Qmpass subscription. See `LICENSE`.