xray-cli 0.1.0__tar.gz

xray_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xray_cli-0.1.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.1
+Name: xray-cli
+Version: 0.1.0
+Summary: Command-line interface for Xray Cloud test management
+License: MIT
+Project-URL: Homepage, https://github.com/arieluchka/xray-cli
+Project-URL: Repository, https://github.com/arieluchka/xray-cli
+Project-URL: Issues, https://github.com/arieluchka/xray-cli/issues
+Keywords: xray,jira,testing,test-management,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+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.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# xray-cli
+
+Command-line interface for [Xray Cloud](https://www.getxray.app/) test management.
+
+A zero-dependency Python CLI that talks to the Xray Cloud API (GraphQL + REST) to manage test executions, tests, runs, results, preconditions, test sets, test plans, and folders — all from your terminal.
+
+## Installation
+
+Requires Python 3.8+.
+
+```bash
+pip install .
+```
+
+This installs the `xray` command.
+
+## Quick Start
+
+1. **Set your Xray API credentials** (get them from Xray Cloud → API Keys):
+
+```bash
+export XRAY_CLIENT_ID="your-client-id"
+export XRAY_CLIENT_SECRET="your-client-secret"
+```
+
+Or create a config file (see [Configuration](#configuration) below).
+
+2. **Run a command:**
+
+```bash
+xray execution list --limit 5
+xray test get XSP-123
+xray run list --execution XSP-456 --failed-only
+```
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--version` | | Print version and exit |
+| `--config PATH` | | Path to config file (default: auto-discover `.xray-cli.ini`) |
+| `--json` | | Output in JSON format instead of human-readable text |
+| `--verbose` | `-v` | Enable verbose/debug output |
+| `--quiet` | `-q` | Suppress all non-error output |
+| `--timeout SECONDS` | | Request timeout in seconds (default: from config or 30) |
+
+> **Note:** Global flags can be placed anywhere in the command, e.g. `xray --json execution list` or `xray execution list --json`.
+
+## Commands
+
+### `xray execution` — Test Execution Operations
+
+**List executions:**
+
+```bash
+xray execution list [--jql JQL] [--limit N] [--start N]
+```
+
+**Create an execution:**
+
+```bash
+xray execution create --project XSP --summary "Regression run" [--test XSP-100 --test XSP-101]
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `--project` | Yes | Jira project key |
+| `--summary` | Yes | Summary for the new execution |
+| `--test` | No | Test issue key to include (repeatable) |
+
+### `xray test` — Test Operations
+
+**Get a single test:**
+
+```bash
+xray test get XSP-123
+```
+
+**List tests:**
+
+```bash
+xray test list [--jql JQL] [--limit N] [--start N]
+```
+
+### `xray run` — Test Run Operations
+
+**List runs:**
+
+```bash
+xray run list [--test XSP-123] [--execution XSP-456] [--status PASS] [--failed-only] [--limit N] [--start N]
+```
+
+| Argument | Description |
+|----------|-------------|
+| `--test` | Filter by test issue key (repeatable) |
+| `--execution` | Filter by execution issue key (repeatable) |
+| `--status` | Filter by run status name |
+| `--failed-only` | Show only failed/aborted runs |
+
+**Update run status:**
+
+```bash
+xray run update-status <run_id> <status>
+```
+
+Status values: `PASS`, `FAIL`, `TODO`, `EXECUTING`, `ABORTED`, etc.
+
+**Add evidence to a run:**
+
+```bash
+xray run add-evidence <run_id> path/to/screenshot.png
+```
+
+### `xray results` — Import Test Results
+
+**Import Xray JSON results:**
+
+```bash
+xray results import xray-json results.json [--project XSP] [--execution XSP-456]
+```
+
+**Import JUnit XML results:**
+
+```bash
+xray results import junit results.xml [--project XSP] [--execution XSP-456]
+```
+
+### `xray precondition` — Precondition Operations
+
+```bash
+xray precondition list [--jql JQL] [--limit N] [--start N]
+```
+
+### `xray test-set` — Test Set Operations
+
+```bash
+xray test-set list [--jql JQL] [--limit N] [--start N]
+```
+
+### `xray test-plan` — Test Plan Operations
+
+```bash
+xray test-plan list [--jql JQL] [--limit N] [--start N]
+```
+
+### `xray folder` — Folder Operations
+
+```bash
+xray folder list --project XSP [--path /MyFolder] [--limit N] [--start N]
+```
+
+## Configuration
+
+### Config File
+
+Create `.xray-cli.ini` in your project directory or home directory:
+
+```ini
+[xray]
+client_id = YOUR_CLIENT_ID
+client_secret = YOUR_CLIENT_SECRET
+
+[defaults]
+project_key = XSP
+output = text
+timeout_seconds = 30
+page_limit = 50
+```
+
+See `xray-cli.ini.example` for a full annotated template.
+
+You can also specify a config file explicitly:
+
+```bash
+xray --config /path/to/config.ini execution list
+```
+
+### Environment Variables
+
+All settings can be set via environment variables:
+
+| Variable | Config Key |
+|----------|------------|
+| `XRAY_CLIENT_ID` | `client_id` |
+| `XRAY_CLIENT_SECRET` | `client_secret` |
+| `XRAY_AUTH_URL` | `auth_url` |
+| `XRAY_GRAPHQL_URL` | `graphql_url` |
+| `XRAY_IMPORT_BASE_URL` | `import_base_url` |
+| `XRAY_PROJECT_KEY` | `project_key` |
+| `XRAY_OUTPUT` | `output` |
+| `XRAY_TIMEOUT` | `timeout_seconds` |
+| `XRAY_PAGE_LIMIT` | `page_limit` |
+
+### Precedence
+
+Settings are resolved in this order (highest wins):
+
+1. CLI flags (`--json`, `--timeout`)
+2. Environment variables (`XRAY_*`)
+3. Config file (`.xray-cli.ini`)
+4. Built-in defaults
+
+## Output Formats
+
+By default, output is human-readable text. Use `--json` for machine-readable JSON:
+
+```bash
+# Human-readable
+xray test list --limit 3
+
+# JSON output (pipe to jq, etc.)
+xray --json test list --limit 3 | jq '.results[].issue_key'
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 2 | Usage / validation error |
+| 3 | Configuration error |
+| 4 | Authentication error |
+| 5 | Network / transport error |
+| 6 | API / resolution error |
+| 7 | Import error |
+
+## Running Tests
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests
+```
+
+## License
+
+MIT

xray_cli-0.1.0/README.md

@@ -0,0 +1,235 @@
+# xray-cli
+
+Command-line interface for [Xray Cloud](https://www.getxray.app/) test management.
+
+A zero-dependency Python CLI that talks to the Xray Cloud API (GraphQL + REST) to manage test executions, tests, runs, results, preconditions, test sets, test plans, and folders — all from your terminal.
+
+## Installation
+
+Requires Python 3.8+.
+
+```bash
+pip install .
+```
+
+This installs the `xray` command.
+
+## Quick Start
+
+1. **Set your Xray API credentials** (get them from Xray Cloud → API Keys):
+
+```bash
+export XRAY_CLIENT_ID="your-client-id"
+export XRAY_CLIENT_SECRET="your-client-secret"
+```
+
+Or create a config file (see [Configuration](#configuration) below).
+
+2. **Run a command:**
+
+```bash
+xray execution list --limit 5
+xray test get XSP-123
+xray run list --execution XSP-456 --failed-only
+```
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--version` | | Print version and exit |
+| `--config PATH` | | Path to config file (default: auto-discover `.xray-cli.ini`) |
+| `--json` | | Output in JSON format instead of human-readable text |
+| `--verbose` | `-v` | Enable verbose/debug output |
+| `--quiet` | `-q` | Suppress all non-error output |
+| `--timeout SECONDS` | | Request timeout in seconds (default: from config or 30) |
+
+> **Note:** Global flags can be placed anywhere in the command, e.g. `xray --json execution list` or `xray execution list --json`.
+
+## Commands
+
+### `xray execution` — Test Execution Operations
+
+**List executions:**
+
+```bash
+xray execution list [--jql JQL] [--limit N] [--start N]
+```
+
+**Create an execution:**
+
+```bash
+xray execution create --project XSP --summary "Regression run" [--test XSP-100 --test XSP-101]
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `--project` | Yes | Jira project key |
+| `--summary` | Yes | Summary for the new execution |
+| `--test` | No | Test issue key to include (repeatable) |
+
+### `xray test` — Test Operations
+
+**Get a single test:**
+
+```bash
+xray test get XSP-123
+```
+
+**List tests:**
+
+```bash
+xray test list [--jql JQL] [--limit N] [--start N]
+```
+
+### `xray run` — Test Run Operations
+
+**List runs:**
+
+```bash
+xray run list [--test XSP-123] [--execution XSP-456] [--status PASS] [--failed-only] [--limit N] [--start N]
+```
+
+| Argument | Description |
+|----------|-------------|
+| `--test` | Filter by test issue key (repeatable) |
+| `--execution` | Filter by execution issue key (repeatable) |
+| `--status` | Filter by run status name |
+| `--failed-only` | Show only failed/aborted runs |
+
+**Update run status:**
+
+```bash
+xray run update-status <run_id> <status>
+```
+
+Status values: `PASS`, `FAIL`, `TODO`, `EXECUTING`, `ABORTED`, etc.
+
+**Add evidence to a run:**
+
+```bash
+xray run add-evidence <run_id> path/to/screenshot.png
+```
+
+### `xray results` — Import Test Results
+
+**Import Xray JSON results:**
+
+```bash
+xray results import xray-json results.json [--project XSP] [--execution XSP-456]
+```
+
+**Import JUnit XML results:**
+
+```bash
+xray results import junit results.xml [--project XSP] [--execution XSP-456]
+```
+
+### `xray precondition` — Precondition Operations
+
+```bash
+xray precondition list [--jql JQL] [--limit N] [--start N]
+```
+
+### `xray test-set` — Test Set Operations
+
+```bash
+xray test-set list [--jql JQL] [--limit N] [--start N]
+```
+
+### `xray test-plan` — Test Plan Operations
+
+```bash
+xray test-plan list [--jql JQL] [--limit N] [--start N]
+```
+
+### `xray folder` — Folder Operations
+
+```bash
+xray folder list --project XSP [--path /MyFolder] [--limit N] [--start N]
+```
+
+## Configuration
+
+### Config File
+
+Create `.xray-cli.ini` in your project directory or home directory:
+
+```ini
+[xray]
+client_id = YOUR_CLIENT_ID
+client_secret = YOUR_CLIENT_SECRET
+
+[defaults]
+project_key = XSP
+output = text
+timeout_seconds = 30
+page_limit = 50
+```
+
+See `xray-cli.ini.example` for a full annotated template.
+
+You can also specify a config file explicitly:
+
+```bash
+xray --config /path/to/config.ini execution list
+```
+
+### Environment Variables
+
+All settings can be set via environment variables:
+
+| Variable | Config Key |
+|----------|------------|
+| `XRAY_CLIENT_ID` | `client_id` |
+| `XRAY_CLIENT_SECRET` | `client_secret` |
+| `XRAY_AUTH_URL` | `auth_url` |
+| `XRAY_GRAPHQL_URL` | `graphql_url` |
+| `XRAY_IMPORT_BASE_URL` | `import_base_url` |
+| `XRAY_PROJECT_KEY` | `project_key` |
+| `XRAY_OUTPUT` | `output` |
+| `XRAY_TIMEOUT` | `timeout_seconds` |
+| `XRAY_PAGE_LIMIT` | `page_limit` |
+
+### Precedence
+
+Settings are resolved in this order (highest wins):
+
+1. CLI flags (`--json`, `--timeout`)
+2. Environment variables (`XRAY_*`)
+3. Config file (`.xray-cli.ini`)
+4. Built-in defaults
+
+## Output Formats
+
+By default, output is human-readable text. Use `--json` for machine-readable JSON:
+
+```bash
+# Human-readable
+xray test list --limit 3
+
+# JSON output (pipe to jq, etc.)
+xray --json test list --limit 3 | jq '.results[].issue_key'
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 2 | Usage / validation error |
+| 3 | Configuration error |
+| 4 | Authentication error |
+| 5 | Network / transport error |
+| 6 | API / resolution error |
+| 7 | Import error |
+
+## Running Tests
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests
+```
+
+## License
+
+MIT

xray_cli-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=45,<75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xray-cli"
+version = "0.1.0"
+description = "Command-line interface for Xray Cloud test management"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+readme = "README.md"
+keywords = ["xray", "jira", "testing", "test-management", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+]
+
+[project.urls]
+Homepage = "https://github.com/arieluchka/xray-cli"
+Repository = "https://github.com/arieluchka/xray-cli"
+Issues = "https://github.com/arieluchka/xray-cli/issues"
+
+[project.scripts]
+xray = "xray_cli.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

xray_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xray_cli-0.1.0/src/xray_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Xray Cloud CLI - command-line interface for Xray test management."""
+
+__version__ = "0.1.0"

xray_cli-0.1.0/src/xray_cli/auth.py

@@ -0,0 +1,88 @@
+"""Token service for Xray Cloud API authentication."""
+
+import json
+import urllib.request
+import urllib.error
+
+from xray_cli.errors import AuthError, TransportError
+from xray_cli import log
+
+
+class TokenService:
+    """Acquires and caches Xray API tokens using Client ID and Secret."""
+
+    def __init__(self, auth_url, client_id, client_secret, timeout=30):
+        self._auth_url = auth_url
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._timeout = timeout
+        self._token = None
+
+    def get_token(self):
+        """Return a cached token, or acquire a new one."""
+        if self._token is not None:
+            return self._token
+        self._token = self._authenticate()
+        return self._token
+
+    def invalidate_token(self):
+        """Clear the cached token so the next call re-authenticates."""
+        self._token = None
+
+    def _authenticate(self):
+        """Exchange Client ID/Secret for an auth token."""
+        payload = json.dumps({
+            "client_id": self._client_id,
+            "client_secret": self._client_secret,
+        }).encode("utf-8")
+
+        req = urllib.request.Request(
+            self._auth_url,
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+
+        log.debug("Authenticating against %s", self._auth_url)
+
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                body = resp.read().decode("utf-8")
+                # The Xray auth endpoint returns the token as a bare JSON string
+                token = json.loads(body)
+                if isinstance(token, str):
+                    log.debug("Token acquired successfully")
+                    return token
+                # Some responses may wrap it differently
+                if isinstance(token, dict) and "token" in token:
+                    log.debug("Token acquired successfully")
+                    return token["token"]
+                raise AuthError(
+                    "Unexpected auth response format",
+                    detail=f"Response body: {body[:200]}",
+                )
+        except urllib.error.HTTPError as exc:
+            status = exc.code
+            try:
+                detail = exc.read().decode("utf-8", errors="replace")[:500]
+            except Exception:
+                detail = None
+            if status in (401, 403):
+                raise AuthError(
+                    "Authentication failed: invalid Client ID or Client Secret",
+                    detail=detail,
+                )
+            raise AuthError(
+                f"Authentication failed with HTTP {status}",
+                detail=detail,
+            )
+        except urllib.error.URLError as exc:
+            raise TransportError(
+                f"Cannot reach auth endpoint: {exc.reason}",
+                detail=str(exc),
+            )
+        except (OSError, ValueError) as exc:
+            raise TransportError(
+                f"Auth request failed: {exc}",
+                detail=str(exc),
+            )