Metadata-Version: 2.1
Name: xray-cli
Version: 0.1.2
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
