ignition-test 0.1.0__tar.gz

ignition_test-0.1.0/PKG-INFO

@@ -0,0 +1,316 @@
+Metadata-Version: 2.4
+Name: ignition-test
+Version: 0.1.0
+Summary: CI client for the Ignition Test Framework module: provision a token, wait for the gateway, run suites over REST, download JUnit/lcov, exit like pytest.
+Author: BW Design Group
+License: MIT
+Project-URL: Homepage, https://github.com/bw-design-group/ignition.modules.test-framework
+Project-URL: Documentation, https://github.com/bw-design-group/ignition.modules.test-framework/tree/main/cli
+Keywords: ignition,testing,ci,pytest,scada
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: click>=8.1
+Provides-Extra: ws
+Requires-Dist: websocket-client>=1.6; extra == "ws"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+# ignition-test
+
+Command-line client for the [Ignition Test Framework](../README.md) module. It
+is what a CI job (or a developer without a Designer open) uses to provision a
+gateway API token, wait for the gateway, register the Playwright browser agent,
+run test suites over the module's REST API with pytest-like output, download
+JUnit / lcov reports and exit with pytest-like codes.
+
+- Python 3.9+, depends on `requests` and `click` only.
+- Importable package: `ignition_test_cli` (`ignition_test` is the Jython
+  framework that runs inside the gateway; the two never meet).
+- Talks to `/data/test-framework` on an Ignition 8.3 or 8.1 gateway running the module;
+  plain polling of `GET /runs/:id/events?since=` is the contract, no WebSocket
+  is needed.
+
+## Install
+
+```bash
+pip install ignition-test                     # from PyPI; bundles the offline runner (run --offline)
+pip install -e cli/                           # from a checkout of this repository
+# source install from GitHub, pinned by ref (branch, tag or commit); the repository is
+# private, so pip needs credentials that can read it
+pip install "git+https://github.com/bw-design-group/ignition.modules.test-framework@main#subdirectory=cli"
+```
+
+`ignition-test` is published on PyPI from `cli-v*` tags; pin it (`ignition-test==0.1.0` or
+`"ignition-test>=0.1,<1"`) in CI. Only the PyPI wheel carries the offline runtime: a source
+install runs every gateway command, and `run --offline` after `./gradlew :offline:cliRuntime`.
+The GitHub Action's `cli-source: auto` and the sample workflow still default to the source install
+beside the action; `cli-source: pypi` and `IGNITION_TEST_CLI_FROM_PYPI: "true"` switch to PyPI.
+
+## Five-minute tour
+
+```bash
+export IGT_GATEWAY=http://localhost:8088
+export IGT_API_TOKEN=ci:...                    # the value X-Ignition-API-Token expects
+
+ignition-test info                             # module/gateway versions, caller, schemaVersion
+ignition-test discover --project DemoPlant     # the static test tree, no code executed
+ignition-test run --project DemoPlant --suite smoke
+ignition-test run --project DemoPlant unit --coverage --fail-under 70 \
+    --junit out/junit.xml --lcov out/lcov.info --results out/results.json --run-json out/run.json
+ignition-test runs                             # recent runs
+ignition-test results r-20260926-121922-c011ee --exit-code   # exit with the run's verdict
+ignition-test agents add default --url http://browser-agent:7311 --secret-env AGENT_TOKEN --gateway-base-url http://gateway:8088
+```
+
+What a run looks like:
+
+```
+gateway http://localhost:8088  Ignition 8.3.9  module 0.1.0 (b26092604)  transport=polling
+run r-20260926-121918-09526e  project=DemoPlant  running
+collected 21 items
+unit/test_recipes ...................xs    skipped: designer scope
+wrote out/junit.xml
+wrote out/lcov.info
+coverage 46.3% (19/41 lines)
+19 passed, 0 failed, 0 error, 1 skipped, 1 xfailed in 2.38s   exit 0
+```
+
+`--verbose` prints one line per test (`unit/test_recipes::test_scale_total[50.0-51.0] PASSED  1 ms`).
+Failures are printed at the end with the assertion explanation and the
+resource-mapped traceback, then collection errors, the coverage line and the
+summary line.
+
+## Commands
+
+| Command | What it does | Routes |
+|---|---|---|
+| `info` | Module, gateway, caller (`kind actor  canRead canWrite`) and schema facts; refuses an `/info` `schemaVersion` the CLI does not know | `GET /info` |
+| `provision` | 8.3: writes a security level, its gateway grant and an API token into a `data/config` directory (offline; nothing is restarted). 8.1 (`--target 8.1`): prints the `IGT_BOOTSTRAP_*` environment the module seeds its token from | filesystem (8.3), none (8.1) |
+| `wait-ready` | `/StatusPing` RUNNING, then `/health`, then `/info` with the token (`--module`, `--project` add checks); exit 3 on timeout with the last state, 4 at once on a refused token or for `--project` without a token (the project rung needs one) | `/StatusPing`, `/health`, `/info`, `/projects/:p/tests` |
+| `run` | `POST /runs`, follow the events, download reports, exit like pytest | `POST /runs`, `/runs/:id/events`, `/runs/:id`, `/runs/:id/results`, `junit.xml`, `lcov.info` |
+| `discover` | Static tree of a project (`--json`, `--ids`) | `GET /projects/:p/tests` |
+| `runs` | Table of recent runs (`--project`, `--limit`, `--json`) | `GET /runs` |
+| `results RUN_ID` | Summary and failures of a run (`--all`, `--json`); exits 0 and names the verdict, or exits with it under `--exit-code` | `GET /runs/:id`, `/runs/:id/results` |
+| `cancel RUN_ID` | Cancel a queued or running run (already finished is not an error) | `POST /runs/:id/cancel` |
+| `scan` | Rescan `data/projects` for files written after boot | `POST /scan?timeout=N` |
+| `push SRC` | Write a folder of `.py` files as `test-python` resources into a mounted project, then scan | filesystem, `POST /scan` |
+| `agents list` | Table of the configured browser agents (`--json`); a `gateway url` column appears when a record carries `gatewayBaseUrl`; secrets are never returned | `GET /agents` |
+| `agents add NAME --url URL` | Create (or `--replace`) a `browser-agents` record; the secret is encrypted by the gateway first; `--gateway-base-url`, `--default`, `--disabled`, `--description`, `--ping` | `POST /data/api/v1/encryption/encrypt`, `/data/api/v1/resources/...` |
+| `agents ping NAME` | The gateway probes `<url>/health` with the stored secret; exit 0 reachable, 3 not, 4 unknown | `POST /agents/:name/ping` |
+| `agents remove NAME` | Delete the record by name and signature (`--if-exists` makes a missing name a no-op) | `/data/api/v1/resources/...` |
+
+Every command accepts `--gateway URL` / `--token NAME:SECRET` (or `IGT_GATEWAY` /
+`IGT_API_TOKEN`), `--insecure` for self-signed TLS and `--http-timeout`. `run`,
+`discover` and `push` also read `IGT_PROJECT`.
+
+### `run` options
+
+| Option | Maps to |
+|---|---|
+| `--suite S` | `RunRequest.suite`; the suite's selection and options are the base, flags win field by field |
+| `PATHS...`, `--node-id`, `-k`, `-m` | `select.paths`, `select.nodeIds`, `select.keywords`, `select.markers` |
+| `--coverage/--no-coverage`, `--coverage-include M`, `--fail-under N` | `options.coverage.{enabled,include,thresholdLines}`; `--fail-under` and `--coverage-include` imply coverage |
+| `--timeout-per-test S`, `--timeout-run S`, `--fail-fast` | `options.timeoutPerTestMs`, `options.timeoutRunMs` (also the client wall clock: on expiry the run is cancelled and the CLI exits 2), `options.failFast` |
+| `--policy development\|production` | `options.policy` (a suite that says `production` cannot be loosened by the request) |
+| `--label K=V` (repeatable) | `RunRequest.label`, joined with commas |
+| `--junit`, `--lcov`, `--results`, `--run-json PATH` | files downloaded after the terminal event |
+| `--scan` | `POST /scan` before the run (files dropped into `data/projects` after boot) |
+| `--wait/--no-wait`, `--poll-interval S` | follow the run (default) or print `{"runId": ...}` as the only stdout line (the banner goes to stderr) and exit 0 |
+| `--require-browser` | exit 7 when a `browser`-marked test was skipped or errored for want of an agent, even with `--allow-degraded` |
+| `--allow-degraded` | exit 0 instead of 7 for a degraded run; the summary still says `degraded` |
+| `--collect-only` | `kind: collect`: collect without running; exit 1 on collection errors, else 0 |
+| `--offline` | run from the project folder without a gateway (see [Offline runs](#offline-runs)) |
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | passed |
+| 1 | failures, errors, or any collection error (a syntax error never yields a green run with fewer tests); `aborted` with `collection-error` |
+| 2 | cancelled or interrupted; `aborted` with `run-timeout`, `pytest-exit`, `library-changed`; the client `--timeout-run` expired |
+| 3 | cannot reach the gateway, HTTP 5xx, `wait-ready` timeout, `queue-full`/`indexing` still refused after the retry window, `runner-unavailable`, `redundancy-inactive`; `aborted` with `run-error` or `leaked-threads` |
+| 4 | usage: bad flags, 401/403, every 400/404/413/422 refusal, 409 `policy-refused`, an unknown `/info` schema |
+| 5 | no tests collected |
+| 6 | coverage below `--fail-under`, everything else green |
+| 7 | degraded: `run.json.limitations[]` non-empty (unless `--allow-degraded`), or `--require-browser` and a browser item skipped for the agent |
+
+Precedence when several conditions hold: 3, 4, 2, 1, 6, 7, 5, 0. The 409
+`queue-full` and 503 `indexing` answers to `POST /runs` are retried every 5 s for
+up to a minute before they count as 3.
+
+## Provisioning a token
+
+`provision` is the one implementation of the API-token recipe (a port of
+Flint's verified `provision-api-token.mjs`) as plain file writes:
+
+```bash
+ignition-test provision --config-dir ci-stage/config --token-name ci --format env
+# IGT_API_TOKEN=ci:<secret>
+```
+
+It writes, under `<config-dir>/resources/core/ignition/`:
+
+- `security-levels/config.json`: a custom grantable level (`--security-level`,
+  default `Test Framework`; `A/B` creates a nested level) appended to whatever
+  the file already holds;
+- `security-properties/config.json`: that level added to the gateway
+  Access/Read/Write permissions (`AnyOf`). The module's routes check the platform
+  READ/WRITE permission today, so this grant is what lets the token start runs;
+  `--no-grant-gateway-permissions` skips it for the least-privilege design of the
+  security document;
+- `api-token/<name>/config.json`: a `basic-token` profile holding `Authenticated`
+  plus the level, with `tokenHash = base64url(sha256(base64url_decode(secret)))`.
+  The secret is printed once; the gateway stores only its hash.
+
+Each folder gets a `resource.json` (`scope A`, `files: [config.json]`,
+`attributes.uuid`). `--settings '{"policy": "development"}'` (or `@file.json`)
+additionally writes the module's `test-framework-settings` config resource.
+`--token-file docker/.api-token` reuses the stored secret for the same token
+name, so re-provisioning after a container recreate keeps callers working.
+
+Two ways to get the files into a gateway:
+
+1. **Before first boot**: mount the directory as the container's
+   `data/config` (`examples/ci/docker-compose.yaml` does this; `chmod -R 0777`
+   the staged tree because the stock image runs as a non-root user).
+2. **Into a running container**: copy the container's existing
+   `security-levels` and `security-properties` folders out, run `provision`
+   against them (existing entries are merged, never replaced), copy the three
+   folders back and restart the gateway. `docker/provision-token.sh` does exactly
+   this for the compose stack (dev and the `integration-test.yaml` lane), calling
+   `provision` for the file writes; the CLI never restarts anything.
+
+### Ignition 8.1
+
+8.1 has no platform API tokens, so the module owns its tokens: it stores
+`NAME` with `base64url(sha256(base64url_decode(SECRET)))` (the same hash as above)
+and accepts the same `X-Ignition-API-Token: NAME:SECRET` header. The token is
+seeded from the gateway container's environment at startup, so nothing is
+written to disk:
+
+```bash
+set -a   # the printed NAME=value lines carry no export; compose must see IGT_BOOTSTRAP_*
+eval "$(ignition-test provision --target 8.1 --format env --token-file docker/.api-token)"
+set +a
+# IGT_BOOTSTRAP_TOKEN=ci:<secret>          -> gateway container (hashed and stored at startup)
+# IGT_BOOTSTRAP_TOKEN_SCOPE=admin           -> gateway container (read | run | admin)
+# IGT_API_TOKEN=ci:<secret>                 -> this shell, for the CLI and tests/ci
+docker compose -f docker/docker-compose.yaml -f docker/docker-compose.ci.yaml up -d --wait
+```
+
+Scopes: `read` allows the GET routes; `run` adds `POST /runs`, `/scan` and
+cancel; `admin` adds browser-agent and settings management (what `agents add`
+needs). `--settings JSON|@file` adds `IGT_BOOTSTRAP_SETTINGS`, applied only while
+the gateway has no settings row. On 8.1 the `agents` commands use the module's
+own `POST /agents`, `PUT`/`DELETE /agents/:name` and `PUT /config/settings`
+routes instead of the platform config API; `info` shows which platform answered.
+
+## Registering the browser agent
+
+Browser tests need a `browser-agents` config record that tells the gateway where
+the Playwright agent listens and the shared secret it was started with. The
+gateway web page can create one by hand; in CI use the CLI after `wait-ready`:
+
+```bash
+export AGENT_TOKEN="$(openssl rand -hex 32)"          # the value the agent container gets as IGT_AGENT_SECRET
+docker compose -f examples/ci/docker-compose.yaml --profile browser up -d --wait
+ignition-test wait-ready --module dev.bwdesigngroup.testing.TestFramework --project DemoPlant
+ignition-test agents add default --url http://browser-agent:7311 --secret-env AGENT_TOKEN --gateway-base-url http://gateway:8088 --description "CI agent" --ping
+ignition-test agents list
+```
+
+`add` sends the secret once to the gateway's `POST /data/api/v1/encryption/encrypt`
+and writes only the encrypted `{"type": "Embedded", "data": ...}` form into the
+record, exactly as the module's web page does; the plaintext is never printed.
+The secret comes from one of `--secret VALUE`, `--secret-env VAR`,
+`--secret-file PATH` or `--secret-stdin` (prefer the last three in CI so the
+value stays out of the process list). An existing name is an error unless
+`--replace` is given; `--replace` without a new secret keeps the stored one.
+`--gateway-base-url URL` writes the record's `gatewayBaseUrl`: what the browser
+inside the agent container calls the gateway (`http://gateway:8088`, the compose
+network alias, in the example lane; it must match the agent's `ALLOWED_GATEWAYS`).
+The key travels only when the flag is given, so a gateway build without the field
+keeps accepting the record and the gateway's own base URL applies; `--replace`
+without the flag keeps the stored value. `agents list` adds a `gateway url`
+column when any record carries one.
+`--default` also writes `defaultBrowserAgent=NAME` into the
+`test-framework-settings` resource; without it the gateway picks the only
+configured agent, so a second record without `--default` leaves no default.
+`--disabled` stores the record but keeps it out of runs. `agents ping NAME` (or
+`add --ping`) asks the gateway to `GET <url>/health` with the stored secret and
+exits 0 when the agent answered 2xx, 3 when it did not, 4 when no such agent
+exists. The agent's `/health` is an unauthenticated liveness probe, so a
+reachable answer proves the URL, not the secret; a wrong secret surfaces when a
+browser run opens its session. HTTP 401/403 exit 4 with the usual token hint; a 422 validation answer
+(for example a URL without a scheme) exits 4 with the platform's field messages.
+`agents remove NAME` looks the signature up and deletes the record;
+`--if-exists` makes a missing name a no-op for idempotent teardown.
+
+## Offline runs
+
+```bash
+ignition-test run --offline --project-dir examples/project/DemoPlant --suite smoke
+ignition-test run --offline --projects-dir examples/project --project DemoPlant --target 8.1 --collect-only
+```
+
+`--offline` runs the project's suites in a local runtime instead of on a gateway, with
+the same request flags, reports, output and exit codes. It uses `jython-ia`, IA's
+interpreter, and IA's own `system.dataset`, `system.date`, `system.math` and
+`system.util` JSON and logger functions. Tests marked `requires_gateway`, `requires_db`,
+`requires_tag_provider`, `requires_perspective`, `requires_module` or `browser` skip. Any
+other `system.*` call that needs a gateway fails with `OfflineUnavailable`, unless the test
+patches it or a conftest registers a stand-in with `ignition_test.offline.stub`.
+
+| Option | |
+|---|---|
+| `--project-dir DIR`, or `--projects-dir DIR --project NAME` | the project folder; parents come from the projects folder (`IGT_PROJECTS_DIR`) |
+| `--target 8.1\|8.3` | the Ignition the runtime stands for (default 8.3, `IGT_TARGET`) |
+| `--pylib DIR` | extra `sys.path` folder, like `user-lib/pylib` (repeatable) |
+| `--java PATH` | Java 17+ (default `JAVA_HOME`, then `PATH`) |
+| `--runtime DIR` | a local `./gradlew :offline:installDist` tree instead of the bundled runtime (`IGT_OFFLINE_RUNTIME`) |
+
+The wheel bundles the runner jar and a manifest per target. The first offline run
+downloads the jars that manifest lists (IA's `common` and `jython-ia`, upstream
+`jython-standalone`; about 150 MB) from Maven Central and IA's public Nexus into
+`~/.cache/ignition-test` (`IGT_CACHE_DIR`), and every later run checks their sha256.
+A source install has no bundled runtime until `./gradlew :offline:cliRuntime` has
+run. The user guide page is `docs/guide/ci/offline-runs.md`.
+
+## Pushing tests from a folder
+
+```bash
+ignition-test push ./tests --project DemoPlant --projects-dir docker/data/projects
+ignition-test push ./tests --project DemoPlant --projects-dir ci-stage/projects --no-scan   # before boot
+```
+
+`tests/unit/test_a.py` becomes
+`DemoPlant/dev.bwdesigngroup.testing.TestFramework/test-python/unit/test_a/{code.py,resource.json}`,
+`tests/conftest.py` becomes the `conftest` resource, sub-folders are plain
+folders. `--dest generated` nests everything under one folder and `--prune`
+removes resources there that the source no longer has. The written
+`resource.json` carries `enabled`, `lastModification.actor/timestamp` and no
+`lastModificationSignature` (a Designer-side hash the CLI cannot reproduce);
+Designer-authored trees committed with the project do not need `push` at all.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e "cli[test]"
+pytest cli/tests            # 140+ tests against a scripted fake of the REST surface; no gateway needed
+```
+
+The fake gateway lives in `cli/tests/conftest.py` and speaks the wire shapes the
+module serves today (`{error, code}` error bodies, `EventPage` with
+`lastSeq`/`terminal`, the platform's config resource CRUD, encrypt endpoint and
+`{messages, fieldMessages}` 422 bodies for the `agents` commands). When the
+module's REST contract changes, change the fake and the CLI in the same pull
+request.

ignition_test-0.1.0/README.md

@@ -0,0 +1,291 @@
+# ignition-test
+
+Command-line client for the [Ignition Test Framework](../README.md) module. It
+is what a CI job (or a developer without a Designer open) uses to provision a
+gateway API token, wait for the gateway, register the Playwright browser agent,
+run test suites over the module's REST API with pytest-like output, download
+JUnit / lcov reports and exit with pytest-like codes.
+
+- Python 3.9+, depends on `requests` and `click` only.
+- Importable package: `ignition_test_cli` (`ignition_test` is the Jython
+  framework that runs inside the gateway; the two never meet).
+- Talks to `/data/test-framework` on an Ignition 8.3 or 8.1 gateway running the module;
+  plain polling of `GET /runs/:id/events?since=` is the contract, no WebSocket
+  is needed.
+
+## Install
+
+```bash
+pip install ignition-test                     # from PyPI; bundles the offline runner (run --offline)
+pip install -e cli/                           # from a checkout of this repository
+# source install from GitHub, pinned by ref (branch, tag or commit); the repository is
+# private, so pip needs credentials that can read it
+pip install "git+https://github.com/bw-design-group/ignition.modules.test-framework@main#subdirectory=cli"
+```
+
+`ignition-test` is published on PyPI from `cli-v*` tags; pin it (`ignition-test==0.1.0` or
+`"ignition-test>=0.1,<1"`) in CI. Only the PyPI wheel carries the offline runtime: a source
+install runs every gateway command, and `run --offline` after `./gradlew :offline:cliRuntime`.
+The GitHub Action's `cli-source: auto` and the sample workflow still default to the source install
+beside the action; `cli-source: pypi` and `IGNITION_TEST_CLI_FROM_PYPI: "true"` switch to PyPI.
+
+## Five-minute tour
+
+```bash
+export IGT_GATEWAY=http://localhost:8088
+export IGT_API_TOKEN=ci:...                    # the value X-Ignition-API-Token expects
+
+ignition-test info                             # module/gateway versions, caller, schemaVersion
+ignition-test discover --project DemoPlant     # the static test tree, no code executed
+ignition-test run --project DemoPlant --suite smoke
+ignition-test run --project DemoPlant unit --coverage --fail-under 70 \
+    --junit out/junit.xml --lcov out/lcov.info --results out/results.json --run-json out/run.json
+ignition-test runs                             # recent runs
+ignition-test results r-20260926-121922-c011ee --exit-code   # exit with the run's verdict
+ignition-test agents add default --url http://browser-agent:7311 --secret-env AGENT_TOKEN --gateway-base-url http://gateway:8088
+```
+
+What a run looks like:
+
+```
+gateway http://localhost:8088  Ignition 8.3.9  module 0.1.0 (b26092604)  transport=polling
+run r-20260926-121918-09526e  project=DemoPlant  running
+collected 21 items
+unit/test_recipes ...................xs    skipped: designer scope
+wrote out/junit.xml
+wrote out/lcov.info
+coverage 46.3% (19/41 lines)
+19 passed, 0 failed, 0 error, 1 skipped, 1 xfailed in 2.38s   exit 0
+```
+
+`--verbose` prints one line per test (`unit/test_recipes::test_scale_total[50.0-51.0] PASSED  1 ms`).
+Failures are printed at the end with the assertion explanation and the
+resource-mapped traceback, then collection errors, the coverage line and the
+summary line.
+
+## Commands
+
+| Command | What it does | Routes |
+|---|---|---|
+| `info` | Module, gateway, caller (`kind actor  canRead canWrite`) and schema facts; refuses an `/info` `schemaVersion` the CLI does not know | `GET /info` |
+| `provision` | 8.3: writes a security level, its gateway grant and an API token into a `data/config` directory (offline; nothing is restarted). 8.1 (`--target 8.1`): prints the `IGT_BOOTSTRAP_*` environment the module seeds its token from | filesystem (8.3), none (8.1) |
+| `wait-ready` | `/StatusPing` RUNNING, then `/health`, then `/info` with the token (`--module`, `--project` add checks); exit 3 on timeout with the last state, 4 at once on a refused token or for `--project` without a token (the project rung needs one) | `/StatusPing`, `/health`, `/info`, `/projects/:p/tests` |
+| `run` | `POST /runs`, follow the events, download reports, exit like pytest | `POST /runs`, `/runs/:id/events`, `/runs/:id`, `/runs/:id/results`, `junit.xml`, `lcov.info` |
+| `discover` | Static tree of a project (`--json`, `--ids`) | `GET /projects/:p/tests` |
+| `runs` | Table of recent runs (`--project`, `--limit`, `--json`) | `GET /runs` |
+| `results RUN_ID` | Summary and failures of a run (`--all`, `--json`); exits 0 and names the verdict, or exits with it under `--exit-code` | `GET /runs/:id`, `/runs/:id/results` |
+| `cancel RUN_ID` | Cancel a queued or running run (already finished is not an error) | `POST /runs/:id/cancel` |
+| `scan` | Rescan `data/projects` for files written after boot | `POST /scan?timeout=N` |
+| `push SRC` | Write a folder of `.py` files as `test-python` resources into a mounted project, then scan | filesystem, `POST /scan` |
+| `agents list` | Table of the configured browser agents (`--json`); a `gateway url` column appears when a record carries `gatewayBaseUrl`; secrets are never returned | `GET /agents` |
+| `agents add NAME --url URL` | Create (or `--replace`) a `browser-agents` record; the secret is encrypted by the gateway first; `--gateway-base-url`, `--default`, `--disabled`, `--description`, `--ping` | `POST /data/api/v1/encryption/encrypt`, `/data/api/v1/resources/...` |
+| `agents ping NAME` | The gateway probes `<url>/health` with the stored secret; exit 0 reachable, 3 not, 4 unknown | `POST /agents/:name/ping` |
+| `agents remove NAME` | Delete the record by name and signature (`--if-exists` makes a missing name a no-op) | `/data/api/v1/resources/...` |
+
+Every command accepts `--gateway URL` / `--token NAME:SECRET` (or `IGT_GATEWAY` /
+`IGT_API_TOKEN`), `--insecure` for self-signed TLS and `--http-timeout`. `run`,
+`discover` and `push` also read `IGT_PROJECT`.
+
+### `run` options
+
+| Option | Maps to |
+|---|---|
+| `--suite S` | `RunRequest.suite`; the suite's selection and options are the base, flags win field by field |
+| `PATHS...`, `--node-id`, `-k`, `-m` | `select.paths`, `select.nodeIds`, `select.keywords`, `select.markers` |
+| `--coverage/--no-coverage`, `--coverage-include M`, `--fail-under N` | `options.coverage.{enabled,include,thresholdLines}`; `--fail-under` and `--coverage-include` imply coverage |
+| `--timeout-per-test S`, `--timeout-run S`, `--fail-fast` | `options.timeoutPerTestMs`, `options.timeoutRunMs` (also the client wall clock: on expiry the run is cancelled and the CLI exits 2), `options.failFast` |
+| `--policy development\|production` | `options.policy` (a suite that says `production` cannot be loosened by the request) |
+| `--label K=V` (repeatable) | `RunRequest.label`, joined with commas |
+| `--junit`, `--lcov`, `--results`, `--run-json PATH` | files downloaded after the terminal event |
+| `--scan` | `POST /scan` before the run (files dropped into `data/projects` after boot) |
+| `--wait/--no-wait`, `--poll-interval S` | follow the run (default) or print `{"runId": ...}` as the only stdout line (the banner goes to stderr) and exit 0 |
+| `--require-browser` | exit 7 when a `browser`-marked test was skipped or errored for want of an agent, even with `--allow-degraded` |
+| `--allow-degraded` | exit 0 instead of 7 for a degraded run; the summary still says `degraded` |
+| `--collect-only` | `kind: collect`: collect without running; exit 1 on collection errors, else 0 |
+| `--offline` | run from the project folder without a gateway (see [Offline runs](#offline-runs)) |
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | passed |
+| 1 | failures, errors, or any collection error (a syntax error never yields a green run with fewer tests); `aborted` with `collection-error` |
+| 2 | cancelled or interrupted; `aborted` with `run-timeout`, `pytest-exit`, `library-changed`; the client `--timeout-run` expired |
+| 3 | cannot reach the gateway, HTTP 5xx, `wait-ready` timeout, `queue-full`/`indexing` still refused after the retry window, `runner-unavailable`, `redundancy-inactive`; `aborted` with `run-error` or `leaked-threads` |
+| 4 | usage: bad flags, 401/403, every 400/404/413/422 refusal, 409 `policy-refused`, an unknown `/info` schema |
+| 5 | no tests collected |
+| 6 | coverage below `--fail-under`, everything else green |
+| 7 | degraded: `run.json.limitations[]` non-empty (unless `--allow-degraded`), or `--require-browser` and a browser item skipped for the agent |
+
+Precedence when several conditions hold: 3, 4, 2, 1, 6, 7, 5, 0. The 409
+`queue-full` and 503 `indexing` answers to `POST /runs` are retried every 5 s for
+up to a minute before they count as 3.
+
+## Provisioning a token
+
+`provision` is the one implementation of the API-token recipe (a port of
+Flint's verified `provision-api-token.mjs`) as plain file writes:
+
+```bash
+ignition-test provision --config-dir ci-stage/config --token-name ci --format env
+# IGT_API_TOKEN=ci:<secret>
+```
+
+It writes, under `<config-dir>/resources/core/ignition/`:
+
+- `security-levels/config.json`: a custom grantable level (`--security-level`,
+  default `Test Framework`; `A/B` creates a nested level) appended to whatever
+  the file already holds;
+- `security-properties/config.json`: that level added to the gateway
+  Access/Read/Write permissions (`AnyOf`). The module's routes check the platform
+  READ/WRITE permission today, so this grant is what lets the token start runs;
+  `--no-grant-gateway-permissions` skips it for the least-privilege design of the
+  security document;
+- `api-token/<name>/config.json`: a `basic-token` profile holding `Authenticated`
+  plus the level, with `tokenHash = base64url(sha256(base64url_decode(secret)))`.
+  The secret is printed once; the gateway stores only its hash.
+
+Each folder gets a `resource.json` (`scope A`, `files: [config.json]`,
+`attributes.uuid`). `--settings '{"policy": "development"}'` (or `@file.json`)
+additionally writes the module's `test-framework-settings` config resource.
+`--token-file docker/.api-token` reuses the stored secret for the same token
+name, so re-provisioning after a container recreate keeps callers working.
+
+Two ways to get the files into a gateway:
+
+1. **Before first boot**: mount the directory as the container's
+   `data/config` (`examples/ci/docker-compose.yaml` does this; `chmod -R 0777`
+   the staged tree because the stock image runs as a non-root user).
+2. **Into a running container**: copy the container's existing
+   `security-levels` and `security-properties` folders out, run `provision`
+   against them (existing entries are merged, never replaced), copy the three
+   folders back and restart the gateway. `docker/provision-token.sh` does exactly
+   this for the compose stack (dev and the `integration-test.yaml` lane), calling
+   `provision` for the file writes; the CLI never restarts anything.
+
+### Ignition 8.1
+
+8.1 has no platform API tokens, so the module owns its tokens: it stores
+`NAME` with `base64url(sha256(base64url_decode(SECRET)))` (the same hash as above)
+and accepts the same `X-Ignition-API-Token: NAME:SECRET` header. The token is
+seeded from the gateway container's environment at startup, so nothing is
+written to disk:
+
+```bash
+set -a   # the printed NAME=value lines carry no export; compose must see IGT_BOOTSTRAP_*
+eval "$(ignition-test provision --target 8.1 --format env --token-file docker/.api-token)"
+set +a
+# IGT_BOOTSTRAP_TOKEN=ci:<secret>          -> gateway container (hashed and stored at startup)
+# IGT_BOOTSTRAP_TOKEN_SCOPE=admin           -> gateway container (read | run | admin)
+# IGT_API_TOKEN=ci:<secret>                 -> this shell, for the CLI and tests/ci
+docker compose -f docker/docker-compose.yaml -f docker/docker-compose.ci.yaml up -d --wait
+```
+
+Scopes: `read` allows the GET routes; `run` adds `POST /runs`, `/scan` and
+cancel; `admin` adds browser-agent and settings management (what `agents add`
+needs). `--settings JSON|@file` adds `IGT_BOOTSTRAP_SETTINGS`, applied only while
+the gateway has no settings row. On 8.1 the `agents` commands use the module's
+own `POST /agents`, `PUT`/`DELETE /agents/:name` and `PUT /config/settings`
+routes instead of the platform config API; `info` shows which platform answered.
+
+## Registering the browser agent
+
+Browser tests need a `browser-agents` config record that tells the gateway where
+the Playwright agent listens and the shared secret it was started with. The
+gateway web page can create one by hand; in CI use the CLI after `wait-ready`:
+
+```bash
+export AGENT_TOKEN="$(openssl rand -hex 32)"          # the value the agent container gets as IGT_AGENT_SECRET
+docker compose -f examples/ci/docker-compose.yaml --profile browser up -d --wait
+ignition-test wait-ready --module dev.bwdesigngroup.testing.TestFramework --project DemoPlant
+ignition-test agents add default --url http://browser-agent:7311 --secret-env AGENT_TOKEN --gateway-base-url http://gateway:8088 --description "CI agent" --ping
+ignition-test agents list
+```
+
+`add` sends the secret once to the gateway's `POST /data/api/v1/encryption/encrypt`
+and writes only the encrypted `{"type": "Embedded", "data": ...}` form into the
+record, exactly as the module's web page does; the plaintext is never printed.
+The secret comes from one of `--secret VALUE`, `--secret-env VAR`,
+`--secret-file PATH` or `--secret-stdin` (prefer the last three in CI so the
+value stays out of the process list). An existing name is an error unless
+`--replace` is given; `--replace` without a new secret keeps the stored one.
+`--gateway-base-url URL` writes the record's `gatewayBaseUrl`: what the browser
+inside the agent container calls the gateway (`http://gateway:8088`, the compose
+network alias, in the example lane; it must match the agent's `ALLOWED_GATEWAYS`).
+The key travels only when the flag is given, so a gateway build without the field
+keeps accepting the record and the gateway's own base URL applies; `--replace`
+without the flag keeps the stored value. `agents list` adds a `gateway url`
+column when any record carries one.
+`--default` also writes `defaultBrowserAgent=NAME` into the
+`test-framework-settings` resource; without it the gateway picks the only
+configured agent, so a second record without `--default` leaves no default.
+`--disabled` stores the record but keeps it out of runs. `agents ping NAME` (or
+`add --ping`) asks the gateway to `GET <url>/health` with the stored secret and
+exits 0 when the agent answered 2xx, 3 when it did not, 4 when no such agent
+exists. The agent's `/health` is an unauthenticated liveness probe, so a
+reachable answer proves the URL, not the secret; a wrong secret surfaces when a
+browser run opens its session. HTTP 401/403 exit 4 with the usual token hint; a 422 validation answer
+(for example a URL without a scheme) exits 4 with the platform's field messages.
+`agents remove NAME` looks the signature up and deletes the record;
+`--if-exists` makes a missing name a no-op for idempotent teardown.
+
+## Offline runs
+
+```bash
+ignition-test run --offline --project-dir examples/project/DemoPlant --suite smoke
+ignition-test run --offline --projects-dir examples/project --project DemoPlant --target 8.1 --collect-only
+```
+
+`--offline` runs the project's suites in a local runtime instead of on a gateway, with
+the same request flags, reports, output and exit codes. It uses `jython-ia`, IA's
+interpreter, and IA's own `system.dataset`, `system.date`, `system.math` and
+`system.util` JSON and logger functions. Tests marked `requires_gateway`, `requires_db`,
+`requires_tag_provider`, `requires_perspective`, `requires_module` or `browser` skip. Any
+other `system.*` call that needs a gateway fails with `OfflineUnavailable`, unless the test
+patches it or a conftest registers a stand-in with `ignition_test.offline.stub`.
+
+| Option | |
+|---|---|
+| `--project-dir DIR`, or `--projects-dir DIR --project NAME` | the project folder; parents come from the projects folder (`IGT_PROJECTS_DIR`) |
+| `--target 8.1\|8.3` | the Ignition the runtime stands for (default 8.3, `IGT_TARGET`) |
+| `--pylib DIR` | extra `sys.path` folder, like `user-lib/pylib` (repeatable) |
+| `--java PATH` | Java 17+ (default `JAVA_HOME`, then `PATH`) |
+| `--runtime DIR` | a local `./gradlew :offline:installDist` tree instead of the bundled runtime (`IGT_OFFLINE_RUNTIME`) |
+
+The wheel bundles the runner jar and a manifest per target. The first offline run
+downloads the jars that manifest lists (IA's `common` and `jython-ia`, upstream
+`jython-standalone`; about 150 MB) from Maven Central and IA's public Nexus into
+`~/.cache/ignition-test` (`IGT_CACHE_DIR`), and every later run checks their sha256.
+A source install has no bundled runtime until `./gradlew :offline:cliRuntime` has
+run. The user guide page is `docs/guide/ci/offline-runs.md`.
+
+## Pushing tests from a folder
+
+```bash
+ignition-test push ./tests --project DemoPlant --projects-dir docker/data/projects
+ignition-test push ./tests --project DemoPlant --projects-dir ci-stage/projects --no-scan   # before boot
+```
+
+`tests/unit/test_a.py` becomes
+`DemoPlant/dev.bwdesigngroup.testing.TestFramework/test-python/unit/test_a/{code.py,resource.json}`,
+`tests/conftest.py` becomes the `conftest` resource, sub-folders are plain
+folders. `--dest generated` nests everything under one folder and `--prune`
+removes resources there that the source no longer has. The written
+`resource.json` carries `enabled`, `lastModification.actor/timestamp` and no
+`lastModificationSignature` (a Designer-side hash the CLI cannot reproduce);
+Designer-authored trees committed with the project do not need `push` at all.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e "cli[test]"
+pytest cli/tests            # 140+ tests against a scripted fake of the REST surface; no gateway needed
+```
+
+The fake gateway lives in `cli/tests/conftest.py` and speaks the wire shapes the
+module serves today (`{error, code}` error bodies, `EventPage` with
+`lastSeq`/`terminal`, the platform's config resource CRUD, encrypt endpoint and
+`{messages, fieldMessages}` 422 bodies for the `agents` commands). When the
+module's REST contract changes, change the fake and the CLI in the same pull
+request.

ignition_test-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ignition-test"
+description = "CI client for the Ignition Test Framework module: provision a token, wait for the gateway, run suites over REST, download JUnit/lcov, exit like pytest."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dynamic = ["version"]
+authors = [{ name = "BW Design Group" }]
+keywords = ["ignition", "testing", "ci", "pytest", "scada"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Testing",
+]
+dependencies = [
+  "requests>=2.28",
+  "click>=8.1",
+]
+
+[project.optional-dependencies]
+# WebSocket streaming is an optional fast path; polling GET /runs/:id/events is the contract.
+ws = ["websocket-client>=1.6"]
+test = ["pytest>=7"]
+
+[project.scripts]
+ignition-test = "ignition_test_cli.main:cli"
+
+[project.urls]
+Homepage = "https://github.com/bw-design-group/ignition.modules.test-framework"
+Documentation = "https://github.com/bw-design-group/ignition.modules.test-framework/tree/main/cli"
+
+[tool.setuptools.dynamic]
+version = { attr = "ignition_test_cli.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# The offline runner (run --offline): ./gradlew :offline:cliRuntime copies the jar and the
+# per-target runtime manifests here before the wheel is built.
+[tool.setuptools.package-data]
+ignition_test_cli = ["offline/*.jar", "offline/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"