xray-cli 0.1.0__py3-none-any.whl

xray_cli/__init__.py

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

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),
+            )

xray_cli/cli.py

@@ -0,0 +1,153 @@
+"""CLI entry point and argparse command tree for xray-cli."""
+
+import argparse
+import sys
+
+from xray_cli import __version__
+from xray_cli.config import load_config
+from xray_cli.errors import XrayCliError, EXIT_USAGE_ERROR
+from xray_cli import log
+
+
+def _build_parser():
+    """Build the top-level argument parser with global flags."""
+    parser = argparse.ArgumentParser(
+        prog="xray",
+        description="Command-line interface for Xray Cloud test management.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    parser.add_argument(
+        "--config", metavar="PATH", default=None,
+        help="Path to config file (default: auto-discover .xray-cli.ini)",
+    )
+    parser.add_argument(
+        "--json", action="store_true", default=False, dest="json_output",
+        help="Output in JSON format instead of human-readable text",
+    )
+    parser.add_argument(
+        "--verbose", "-v", action="store_true", default=False,
+        help="Enable verbose/debug output",
+    )
+    parser.add_argument(
+        "--quiet", "-q", action="store_true", default=False,
+        help="Suppress all non-error output",
+    )
+    parser.add_argument(
+        "--timeout", type=int, default=None, metavar="SECONDS",
+        help="Request timeout in seconds (default: from config or 30)",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", title="commands")
+
+    # Register command families
+    from xray_cli.commands import execution, test, run, results
+    from xray_cli.commands import precondition, test_set, test_plan, folder
+    execution.register(subparsers)
+    test.register(subparsers)
+    run.register(subparsers)
+    results.register(subparsers)
+    precondition.register(subparsers)
+    test_set.register(subparsers)
+    test_plan.register(subparsers)
+    folder.register(subparsers)
+
+    return parser
+
+
+def _collect_cli_overrides(args):
+    """Extract CLI-level overrides to pass into config loading."""
+    overrides = {}
+    if args.json_output:
+        overrides["output"] = "json"
+    if args.timeout is not None:
+        overrides["timeout_seconds"] = str(args.timeout)
+    return overrides
+
+
+_GLOBAL_FLAGS = {
+    "--json": 0,       # 0 = flag takes no argument
+    "--verbose": 0,
+    "-v": 0,
+    "--quiet": 0,
+    "-q": 0,
+    "--config": 1,     # 1 = flag takes one argument
+    "--timeout": 1,
+}
+
+
+def _hoist_global_flags(argv):
+    """Move global flags that appear after a subcommand to the front.
+
+    argparse only recognises top-level flags when they precede the
+    subcommand.  This helper lets users write them anywhere, e.g.
+    ``xray test get OTR-1 --json`` instead of ``xray --json test get OTR-1``.
+    """
+    hoisted = []
+    rest = []
+    i = 0
+    while i < len(argv):
+        token = argv[i]
+        if token in _GLOBAL_FLAGS:
+            n_args = _GLOBAL_FLAGS[token]
+            hoisted.append(token)
+            if n_args and i + 1 < len(argv):
+                i += 1
+                hoisted.append(argv[i])
+        else:
+            rest.append(token)
+        i += 1
+    return hoisted + rest
+
+
+def main(argv=None):
+    """Main entry point for xray-cli."""
+    parser = _build_parser()
+    raw = argv if argv is not None else sys.argv[1:]
+    args = parser.parse_args(_hoist_global_flags(raw))
+
+    # Configure logging
+    log.configure_verbosity(verbose=args.verbose, quiet=args.quiet)
+
+    # If no command given, print help
+    if not args.command:
+        parser.print_help(sys.stderr)
+        return EXIT_USAGE_ERROR
+
+    # Load config
+    try:
+        cli_overrides = _collect_cli_overrides(args)
+        config = load_config(
+            explicit_path=args.config,
+            cli_overrides=cli_overrides,
+        )
+        log.debug("Config loaded: %s", config)
+    except XrayCliError as exc:
+        log.error("%s: %s", exc.category, exc)
+        if exc.detail:
+            log.debug("Detail: %s", exc.detail)
+        return exc.exit_code
+
+    # Dispatch to subcommand handler
+    handler = getattr(args, "handler", None)
+    if handler is None:
+        parser.print_help(sys.stderr)
+        return EXIT_USAGE_ERROR
+
+    try:
+        return handler(args, config)
+    except XrayCliError as exc:
+        log.error("%s: %s", exc.category, exc)
+        if exc.detail:
+            log.debug("Detail: %s", exc.detail)
+        return exc.exit_code
+
+
+def cli():
+    """Console script entry point — calls main() and exits."""
+    sys.exit(main() or 0)
+
+
+if __name__ == "__main__":
+    cli()

xray_cli/commands/_shared.py

@@ -0,0 +1,23 @@
+"""Shared helpers for command handlers."""
+
+
+def build_service(config):
+    """Build a fully wired XrayService from config."""
+    from xray_cli.auth import TokenService
+    from xray_cli.graphql_client import GraphQLClient
+    from xray_cli.rest_client import RestClient
+    from xray_cli.service import XrayService
+
+    token_service = TokenService(
+        config.auth_url, config.client_id, config.client_secret,
+        timeout=config.timeout_seconds,
+    )
+    gql_client = GraphQLClient(
+        config.graphql_url, token_service,
+        timeout=config.timeout_seconds,
+    )
+    rest_client = RestClient(
+        config.import_base_url, token_service,
+        timeout=config.timeout_seconds,
+    )
+    return XrayService(gql_client, rest_client=rest_client)

xray_cli/commands/execution.py

@@ -0,0 +1,97 @@
+"""Command handlers for execution operations."""
+
+from xray_cli import formatter
+from xray_cli.errors import ValidationError
+
+
+def register(subparsers):
+    """Register execution subcommands."""
+    exec_parser = subparsers.add_parser("execution", help="Test execution operations")
+    exec_sub = exec_parser.add_subparsers(dest="execution_command", title="execution commands")
+
+    # execution list
+    list_parser = exec_sub.add_parser("list", help="List test executions")
+    list_parser.add_argument(
+        "--jql", default=None,
+        help="JQL filter for executions",
+    )
+    list_parser.add_argument(
+        "--limit", type=int, default=None,
+        help="Maximum results per page (1-100, default: from config)",
+    )
+    list_parser.add_argument(
+        "--start", type=int, default=0,
+        help="Start offset for pagination (default: 0)",
+    )
+    list_parser.set_defaults(handler=handle_execution_list)
+
+    # execution create
+    create_parser = exec_sub.add_parser("create", help="Create a test execution")
+    create_parser.add_argument(
+        "--project", required=True, dest="project_key",
+        help="Jira project key (e.g. XSP)",
+    )
+    create_parser.add_argument(
+        "--summary", required=True,
+        help="Summary for the new test execution",
+    )
+    create_parser.add_argument(
+        "--test", dest="test_keys", action="append", default=None,
+        help="Test issue key to include (repeatable)",
+    )
+    create_parser.set_defaults(handler=handle_execution_create)
+
+    # Set a fallback handler for bare "execution" with no subcommand
+    exec_parser.set_defaults(handler=lambda args, config: _show_help(exec_parser))
+
+
+def _show_help(parser):
+    parser.print_help()
+    return 2
+
+
+def _build_service(config):
+    from xray_cli.auth import TokenService
+    from xray_cli.graphql_client import GraphQLClient
+    from xray_cli.service import XrayService
+
+    token_service = TokenService(
+        config.auth_url, config.client_id, config.client_secret,
+        timeout=config.timeout_seconds,
+    )
+    gql_client = GraphQLClient(
+        config.graphql_url, token_service,
+        timeout=config.timeout_seconds,
+    )
+    return XrayService(gql_client)
+
+
+def handle_execution_list(args, config):
+    """Handle 'execution list' command."""
+    limit = args.limit if args.limit is not None else config.page_limit
+    if limit < 1 or limit > 100:
+        raise ValidationError("--limit must be between 1 and 100")
+
+    service = _build_service(config)
+    result = service.list_executions(
+        jql=args.jql,
+        limit=limit,
+        start=args.start,
+    )
+
+    output_mode = "json" if args.json_output else config.output
+    formatter.render(result, mode=output_mode)
+    return 0
+
+
+def handle_execution_create(args, config):
+    """Handle 'execution create' command."""
+    service = _build_service(config)
+    result = service.create_execution(
+        project_key=args.project_key,
+        summary=args.summary,
+        test_keys=args.test_keys,
+    )
+    output_mode = "json" if args.json_output else config.output
+    formatter.render(result, mode=output_mode)
+    return 0

xray_cli/commands/folder.py

@@ -0,0 +1,39 @@
+"""Command handlers for folder operations."""
+
+from xray_cli import formatter
+from xray_cli.errors import ValidationError
+
+
+def register(subparsers):
+    """Register folder subcommands."""
+    parser = subparsers.add_parser("folder", help="Folder operations")
+    sub = parser.add_subparsers(dest="folder_command", title="folder commands")
+
+    list_parser = sub.add_parser("list", help="List folders")
+    list_parser.add_argument(
+        "--project", required=True, dest="project_key",
+        help="Jira project key (required)",
+    )
+    list_parser.add_argument("--path", default="/", help="Folder path (default: root /)")
+    list_parser.add_argument("--limit", type=int, default=None, help="Page size (1-100)")
+    list_parser.add_argument("--start", type=int, default=0, help="Pagination offset")
+    list_parser.set_defaults(handler=handle_list)
+
+    parser.set_defaults(handler=lambda args, config: (parser.print_help(), 2)[1])
+
+
+def handle_list(args, config):
+    from xray_cli.commands._shared import build_service
+    limit = args.limit if args.limit is not None else config.page_limit
+    if limit < 1 or limit > 100:
+        raise ValidationError("--limit must be between 1 and 100")
+    service = build_service(config)
+    result = service.list_folders(
+        project_key=args.project_key,
+        path=args.path,
+        limit=limit,
+        start=args.start,
+    )
+    output_mode = "json" if args.json_output else config.output
+    formatter.render(result, mode=output_mode)
+    return 0

xray_cli/commands/precondition.py

@@ -0,0 +1,30 @@
+"""Command handlers for precondition operations."""
+
+from xray_cli import formatter
+from xray_cli.errors import ValidationError
+
+
+def register(subparsers):
+    """Register precondition subcommands."""
+    parser = subparsers.add_parser("precondition", help="Precondition operations")
+    sub = parser.add_subparsers(dest="precondition_command", title="precondition commands")
+
+    list_parser = sub.add_parser("list", help="List preconditions")
+    list_parser.add_argument("--jql", default=None, help="JQL filter")
+    list_parser.add_argument("--limit", type=int, default=None, help="Page size (1-100)")
+    list_parser.add_argument("--start", type=int, default=0, help="Pagination offset")
+    list_parser.set_defaults(handler=handle_list)
+
+    parser.set_defaults(handler=lambda args, config: (parser.print_help(), 2)[1])
+
+
+def handle_list(args, config):
+    from xray_cli.commands._shared import build_service
+    limit = args.limit if args.limit is not None else config.page_limit
+    if limit < 1 or limit > 100:
+        raise ValidationError("--limit must be between 1 and 100")
+    service = build_service(config)
+    result = service.list_preconditions(jql=args.jql, limit=limit, start=args.start)
+    output_mode = "json" if args.json_output else config.output
+    formatter.render(result, mode=output_mode)
+    return 0

xray_cli/commands/results.py

@@ -0,0 +1,82 @@
+"""Command handlers for results import operations."""
+
+from xray_cli import formatter
+
+
+def register(subparsers):
+    """Register results subcommands."""
+    results_parser = subparsers.add_parser("results", help="Test results operations")
+    results_sub = results_parser.add_subparsers(dest="results_command", title="results commands")
+
+    # results import
+    import_parser = results_sub.add_parser("import", help="Import test results")
+    import_sub = import_parser.add_subparsers(dest="import_format", title="import formats")
+
+    # results import xray-json
+    xray_json_parser = import_sub.add_parser("xray-json", help="Import Xray JSON results")
+    xray_json_parser.add_argument("file", help="Path to Xray JSON results file")
+    xray_json_parser.add_argument("--project", dest="project_key", default=None, help="Project key")
+    xray_json_parser.add_argument("--execution", dest="execution_key", default=None, help="Existing execution key")
+    xray_json_parser.set_defaults(handler=handle_import_xray_json)
+
+    # results import junit
+    junit_parser = import_sub.add_parser("junit", help="Import JUnit XML results")
+    junit_parser.add_argument("file", help="Path to JUnit XML results file")
+    junit_parser.add_argument("--project", dest="project_key", default=None, help="Project key")
+    junit_parser.add_argument("--execution", dest="execution_key", default=None, help="Existing execution key")
+    junit_parser.set_defaults(handler=handle_import_junit)
+
+    import_parser.set_defaults(handler=lambda args, config: _show_help(import_parser))
+    results_parser.set_defaults(handler=lambda args, config: _show_help(results_parser))
+
+
+def _show_help(parser):
+    parser.print_help()
+    return 2
+
+
+def _build_service(config):
+    from xray_cli.auth import TokenService
+    from xray_cli.graphql_client import GraphQLClient
+    from xray_cli.rest_client import RestClient
+    from xray_cli.service import XrayService
+
+    token_service = TokenService(
+        config.auth_url, config.client_id, config.client_secret,
+        timeout=config.timeout_seconds,
+    )
+    gql_client = GraphQLClient(
+        config.graphql_url, token_service,
+        timeout=config.timeout_seconds,
+    )
+    rest_client = RestClient(
+        config.import_base_url, token_service,
+        timeout=config.timeout_seconds,
+    )
+    return XrayService(gql_client, rest_client=rest_client)
+
+
+def handle_import_xray_json(args, config):
+    """Handle 'results import xray-json <file>' command."""
+    service = _build_service(config)
+    result = service.import_xray_json(
+        args.file,
+        project_key=args.project_key or config.project_key,
+        execution_key=args.execution_key,
+    )
+    output_mode = "json" if args.json_output else config.output
+    formatter.render(result, mode=output_mode)
+    return 0
+
+
+def handle_import_junit(args, config):
+    """Handle 'results import junit <file>' command."""
+    service = _build_service(config)
+    result = service.import_junit_xml(
+        args.file,
+        project_key=args.project_key or config.project_key,
+        execution_key=args.execution_key,
+    )
+    output_mode = "json" if args.json_output else config.output
+    formatter.render(result, mode=output_mode)
+    return 0

xray_cli/commands/run.py

@@ -0,0 +1,111 @@
+"""Command handlers for run operations."""
+
+from xray_cli import formatter
+from xray_cli.errors import ValidationError
+
+
+def register(subparsers):
+    """Register run subcommands."""
+    run_parser = subparsers.add_parser("run", help="Test run operations")
+    run_sub = run_parser.add_subparsers(dest="run_command", title="run commands")
+
+    # run list
+    list_parser = run_sub.add_parser("list", help="List test runs")
+    list_parser.add_argument(
+        "--test", dest="test_keys", action="append", default=None,
+        help="Filter by test issue key (repeatable)",
+    )
+    list_parser.add_argument(
+        "--execution", dest="execution_keys", action="append", default=None,
+        help="Filter by execution issue key (repeatable)",
+    )
+    list_parser.add_argument(
+        "--status", default=None,
+        help="Filter by run status name",
+    )
+    list_parser.add_argument(
+        "--failed-only", action="store_true", default=False,
+        help="Show only failed/aborted runs",
+    )
+    list_parser.add_argument(
+        "--limit", type=int, default=None,
+        help="Maximum results per page (1-100, default: from config)",
+    )
+    list_parser.add_argument(
+        "--start", type=int, default=0,
+        help="Start offset for pagination (default: 0)",
+    )
+    list_parser.set_defaults(handler=handle_run_list)
+
+    # run update-status
+    update_parser = run_sub.add_parser("update-status", help="Update a test run status")
+    update_parser.add_argument("run_id", help="Test run ID")
+    update_parser.add_argument("status", help="New status (e.g. PASS, FAIL, TODO)")
+    update_parser.set_defaults(handler=handle_run_update_status)
+
+    # run add-evidence
+    evidence_parser = run_sub.add_parser("add-evidence", help="Add evidence to a test run")
+    evidence_parser.add_argument("run_id", help="Test run ID")
+    evidence_parser.add_argument("file", help="Path to evidence file")
+    evidence_parser.set_defaults(handler=handle_run_add_evidence)
+
+    run_parser.set_defaults(handler=lambda args, config: _show_help(run_parser))
+
+
+def _show_help(parser):
+    parser.print_help()
+    return 2
+
+
+def _build_service(config):
+    from xray_cli.auth import TokenService
+    from xray_cli.graphql_client import GraphQLClient
+    from xray_cli.service import XrayService
+
+    token_service = TokenService(
+        config.auth_url, config.client_id, config.client_secret,
+        timeout=config.timeout_seconds,
+    )
+    gql_client = GraphQLClient(
+        config.graphql_url, token_service,
+        timeout=config.timeout_seconds,
+    )
+    return XrayService(gql_client)
+
+
+def handle_run_list(args, config):
+    """Handle 'run list' command."""
+    limit = args.limit if args.limit is not None else config.page_limit
+    if limit < 1 or limit > 100:
+        raise ValidationError("--limit must be between 1 and 100")
+
+    service = _build_service(config)
+    result = service.list_runs(
+        test_keys=args.test_keys,
+        execution_keys=args.execution_keys,
+        status=args.status,
+        failed_only=args.failed_only,
+        limit=limit,
+        start=args.start,
+    )
+    output_mode = "json" if args.json_output else config.output
+    formatter.render(result, mode=output_mode)
+    return 0
+
+
+def handle_run_update_status(args, config):
+    """Handle 'run update-status <run-id> <status>' command."""
+    service = _build_service(config)
+    result = service.update_run_status(args.run_id, args.status)
+    output_mode = "json" if args.json_output else config.output
+    formatter.render(result, mode=output_mode)
+    return 0
+
+
+def handle_run_add_evidence(args, config):
+    """Handle 'run add-evidence <run-id> <file>' command."""
+    service = _build_service(config)
+    result = service.add_run_evidence(args.run_id, args.file)
+    output_mode = "json" if args.json_output else config.output
+    formatter.render(result, mode=output_mode)
+    return 0