docs(testbench-cli-reporter): TestBench CLI Reporter v3.0.0

docusaurus/testbench-cli-reporter_versioned_docs/version-3.0.0/cli/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "CLI reference",
+  "position": 4
+}

docusaurus/testbench-cli-reporter_versioned_docs/version-3.0.0/cli/authentication.md

@@ -0,0 +1,34 @@
+---
+sidebar_position: 1
+title: Authentication & connection
+---
+
+## Connection options
+
+All subcommands accept the same connection options:
+
+- `--server` TestBench server as `hostname`, `hostname:port`, or `https://host:port/api/`
+- `--login` / `--password` credentials
+- `--session` existing session token (or for JSON export or import, a JWT token)
+- `--verify` verify TLS certificates
+
+If you provide `hostname` without a port, the CLI assumes port `443` and always uses `https://.../api/`.
+
+## When to use `--session`
+
+`--session` is only used for TestBench 4.x, where the API issues a session token.
+
+If you provide `--login` and `--password`, the CLI will:
+
+- detect the TestBench server version
+- authenticate using the appropriate mechanism for that version
+
+## Config file authentication fields
+
+In automatic mode configs, each entry in `configuration[]` can contain:
+
+- `sessionToken`: a session token or JWT token (TestBench 4.x)
+- `basicAuth`: base64 of `login:password`
+- `loginname` / `password`: optional plaintext credentials
+
+The CLI can also override these fields at runtime via `--login/--password` or `--session`.

docusaurus/testbench-cli-reporter_versioned_docs/version-3.0.0/cli/commands.md

@@ -0,0 +1,183 @@
+---
+sidebar_position: 2
+title: Commands
+---
+
+This section documents the explicit, non-interactive subcommands.
+
+All commands require a connection via `--server` and either `--session` or `--login`/`--password`.
+
+
+## Project Path or Keys
+
+Many commands that operate on a project, test object version, or test cycle accept either:
+- The name of the project, version, or cycle<br />
+  (e.g. `--project "My Project" --version "Release 1.0" --cycle "Cycle A"`)
+- The key of the project, version, or cycle<br />
+  (e.g. `--project-key 102 --tov-key 1223 --cycle-key 5121`)
+
+If the keys are provided, they take precedence over the names.
+If no keys are provided, the CLI Reporter tries to resolve the names to keys by querying the TestBench server.
+
+
+## Common connection options
+
+Every subcommand accepts these options:
+
+| Option | Short | Description |
+|---|---|---|
+| `--server` | `-s` | TestBench server address (`hostname[:port]` or full URL) |
+| `--login` | | Login name for authentication |
+| `--password` | | Password for authentication |
+| `--session` | | Existing session token (alternative to login/password) |
+| `--verify` | | Enable TLS certificate verification (flag, off by default) |
+
+These options can also be set on the main `testbench-cli-reporter` command and inherited by subcommands.
+
+---
+
+## `export-xml`
+
+Export an XML full report (zip).
+
+```bash
+testbench-cli-reporter export-xml -s HOST[:PORT] --login USER --password PASS \
+  --tov-key TOV --cycle-key CYCLE --uid itb-TT-1234 -o report.zip
+```
+
+| Option | Short | Required | Default | Description |
+|---|---|---|---|---|
+| `--project` | `-p` | | | Project name |
+| `--version` | `-v` | | | Test object version name |
+| `--cycle` | `-y` | | | Test cycle name |
+| `--project-key` | | | | Project key (currently not relevant for XML export) |
+| `--tov-key` | | | | Test object version key |
+| `--cycle-key` | | | | Test cycle key |
+| `--uid` | `-u` | | | Report root UID (test theme root). If omitted, exports the full tree |
+| `--filtering` | | | | FilteringOptions payload as base64-encoded JSON (see [FilteringOptions](../configuration/filtering-options.md)) |
+| `--output` | `-o` | | `report.zip` | Output zip file path |
+
+You must provide either `--project`/`--version`[/`--cycle`] (by name) or `--tov-key`/`--cycle-key` (by key).
+
+---
+
+## `import-xml`
+
+Import an XML execution results zip back into TestBench.
+
+Project, version, and cycle are determined from the XML content and don't need to be provided as options.
+
+```bash
+testbench-cli-reporter import-xml -s HOST[:PORT] --login USER --password PASS \
+  --input report.zip
+```
+
+| Option | Short | Required | Default | Description |
+|---|---|---|---|---|
+| `--input` | `-i` | **yes** | | Path to the XML results zip file |
+| `--uid` | `-u` | | `ROOT` | Report root UID |
+| `--filtering` | | | | FilteringOptions payload as base64-encoded JSON |
+
+---
+
+## `export-json`
+
+Export a JSON full report (zip).
+
+```bash
+testbench-cli-reporter export-json -s HOST[:PORT] --login USER --password PASS \
+  --project-key PROJECT --tov-key TOV --cycle-key CYCLE \
+  --uid itb-TT-1234 -o json-report.zip
+```
+
+| Option | Short | Required | Default | Description |
+|---|---|---|---|---|
+| `--project` | `-p` | | | Project name |
+| `--version` | `-v` | | | Test object version name |
+| `--cycle` | `-y` | | | Test cycle name |
+| `--project-key` | | | | Project key |
+| `--tov-key` | | | | Test object version key |
+| `--cycle-key` | | | | Test cycle key |
+| `--uid` | `-u` | | | Tree root UID |
+| `--filtering` | | | | FilteringOptions payload as base64-encoded JSON |
+| `--output` | `-o` | | `json-report.zip` | Output zip file path |
+
+You must either provide the keys for project and tov or cylce, or the names for project and version (and optionally cycle).
+
+---
+
+## `import-json`
+
+Import a JSON execution results zip back into TestBench.
+
+Project, test object version, and test cycle are determined from the JSON report metadata.
+
+```bash
+testbench-cli-reporter import-json -s HOST[:PORT] --login USER --password PASS \
+  --input json-report.zip
+```
+
+| Option | Short | Required | Default | Description |
+|---|---|---|---|---|
+| `--input` | `-i` | **yes** | | Path to the JSON results zip file |
+| `--uid` | `-u` | | | Report root UID |
+| `--filtering` | | | | FilteringOptions payload as base64-encoded JSON |
+
+---
+
+## `export-csv`
+
+Export a CSV report zip.
+
+```bash
+testbench-cli-reporter export-csv -s HOST[:PORT] --login USER --password PASS \
+  --project-key PROJECT --tov-key TOV --cycle-key CYCLE --cycle-key CYCLE2 \
+  --uid itb-TT-1234 -o csv_report.zip
+```
+
+| Option | Short | Required | Default | Description |
+|---|---|---|---|---|
+| `--project-key` | | **yes** | | Project key |
+| `--tov-key` | | **yes** | | Test object version key |
+| `--cycle-key` | | | | Test cycle key (repeatable; omit to export without cycle scope) |
+| `--uid` | `-u` | | | Report root UID |
+| `--output` | `-o` | | `csv_report.zip` | Output zip file path |
+
+---
+
+## `export-logs`
+
+Administrator helper: export TestBench server logs as a zip.
+
+```bash
+testbench-cli-reporter export-logs -s HOST[:PORT] --login USER --password PASS \
+  -o server_logs.zip
+```
+
+| Option | Short | Required | Default | Description |
+|---|---|---|---|---|
+| `--output` | `-o` | | `server_logs.zip` | Output zip file path |
+
+---
+
+## `gen-jwt`
+
+Generate a JWT based on the current session (TestBench 4.x+).
+
+```bash
+testbench-cli-reporter gen-jwt -s HOST[:PORT] --login USER --password PASS \
+  --permission ReadProjectHierarchy --permission ImportExecutionResults \
+  --project-key PROJECT --tov-key TOV --cycle-key CYCLE \
+  --subject my-service --expires 3600
+```
+
+| Option | Short | Required | Default | Description |
+|---|---|---|---|---|
+| `--permission` | | | | Permission to include (repeatable; accepts comma or `\|` separated lists) |
+| `--project-key` | | | | Project key |
+| `--tov-key` | | | | Test object version key |
+| `--cycle-key` | | | | Test cycle key |
+| `--subject` | | | | Subject claim for the token |
+| `--expires` | | | | Token expiry in seconds |
+
+Run `testbench-cli-reporter gen-jwt --help` to see the full list of available permission names.

docusaurus/testbench-cli-reporter_versioned_docs/version-3.0.0/compatibility/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Compatibility",
+  "position": 6
+}

docusaurus/testbench-cli-reporter_versioned_docs/version-3.0.0/compatibility/testbench-versions.md

@@ -0,0 +1,32 @@
+---
+sidebar_position: 1
+title: TestBench 3.x vs 4.x
+---
+
+The CLI is built to work with both current TestBench 3.x installations and the upcoming TestBench 4.x API.
+
+## Version detection
+
+On startup, the client reads the server version from:
+
+- `GET /api/2/serverVersions` (preferred)
+- fallback: `GET /api/1/serverVersions`
+
+The detected version influences authentication and which endpoints are used.
+
+## Authentication
+
+- TestBench 4.x: session-based authentication
+  - the CLI requests a session token and sends it via the `Authorization` header
+  - you can also supply an existing session token or a JWT via `--session`
+  - for TestBench 4.x, the authentication is always done via the `/api/2/auth` endpoint, even if XML exports or other legacy endpoints are used
+- TestBench 3.x: legacy authentication
+  - the CLI uses HTTP basic auth to call legacy endpoints
+
+## Feature availability
+
+Some features depend on server capabilities:
+
+- CSV export requires TestBench >= 3.0.6.2
+- JSON export/import and JWT generation require TestBench 4.x+
+

docusaurus/testbench-cli-reporter_versioned_docs/version-3.0.0/configuration/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Configuration",
+  "position": 5
+}