Metadata-Version: 2.4
Name: robotframework-velo-cli
Version: 0.1.11
Summary: Run Robot Framework test suites on the Velo cloud platform
Author-email: Velo <support@velo.com>
License: Copyright (c) 2026 Velo. All rights reserved.
        
        PROPRIETARY SOFTWARE LICENSE
        
        This software and its source code, documentation, and associated files
        (collectively, the "Software") are the exclusive property of Velo and are
        protected by copyright law and international treaties.
        
        GRANT OF LICENSE
        
        Velo grants you a limited, non-exclusive, non-transferable, non-sub licensable
        license to use the Software solely for your internal business purposes,
        strictly in accordance with any agreement entered into with Velo.
        
        RESTRICTIONS
        
        You may not, and you may not permit any third party to:
        
          1. Copy, modify, adapt, translate, or create derivative works of the Software;
          2. Reverse engineer, disassemble, decompile, or otherwise attempt to derive
             the source code of the Software;
          3. Sell, sublicense, rent, lease, transfer, or otherwise make the Software
             available to any third party;
          4. Remove or alter any proprietary notices, labels, or marks on the Software;
          5. Use the Software for any purpose other than as expressly permitted
             under this license.
        
        NO WARRANTY
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS
        FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL VELO BE
        LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OF
        THE SOFTWARE.
        
        TERMINATION
        
        This license is effective until terminated. It will terminate automatically
        if you fail to comply with any of its terms. Upon termination, you must
        immediately cease all use of the Software and destroy any copies in your
        possession.
        
        GOVERNING LAW
        
        This license shall be governed by and construed in accordance with applicable
        law. Any disputes arising under this license shall be subject to the exclusive
        jurisdiction of the competent courts.
        
        For licensing inquiries, contact: legal@velo.com
        
Project-URL: Homepage, https://velo.com
Project-URL: Bug Tracker, https://github.com/velo/robotframework-velo-cli/issues
Keywords: robotframework,robot,testing,automation,velo,sap
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Robot Framework
Classifier: Framework :: Robot Framework :: Tool
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: robotframework>=6.0
Requires-Dist: requests>=2.31
Requires-Dist: pathspec>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# robotframework-velo-cli

Run Robot Framework test suites on the Velo cloud platform — no SAP GUI setup required on your machine.

---

## Installation

```bash
pip install robotframework-velo-cli
```

> **Note:** This package intentionally installs a `robot` command that wraps and replaces the standard Robot Framework entry point. `robotframework` is a declared dependency and will be installed automatically. Because `robotframework-velo-cli` is installed after `robotframework`, its `robot` script takes precedence. When `VELO_REMOTE` is not set the wrapper passes all arguments through to Robot Framework unchanged — your existing workflow is unaffected.

---

## Quick start

```bash
# 1. Set your workspace credentials
export VELO_API_KEY=<your-api-key>
export VELO_API_BASE=http://<velo-api-host>:8000   # default: http://localhost:8000

# 2. Run your tests remotely — same command you always use
VELO_REMOTE=1 robot ./tests

# 3. With tag filtering — all standard RF flags pass through unchanged
VELO_REMOTE=1 robot --include smoke --exclude wip ./tests
```

---

## Execution modes

| Variable | Value | Behaviour |
|---|---|---|
| `VELO_REMOTE` | `0` (default) | Package is inert — `robot` runs locally as normal |
| `VELO_REMOTE` | `1` | Suite is packaged, uploaded, and executed on the Velo platform |
| `VELO_DEBUG` | `1` | Local debug: native SAP GUI for Windows, or Docker Java elsewhere |
| `VELO_SAP_CLIENT` | `auto` | SAP backend: `auto`, `java`, or `windows` (see debug mode below) |

---

## Environment variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `VELO_API_KEY` | Yes (remote) | — | Workspace API key |
| `VELO_API_BASE` | No | `http://localhost:8000` | Velo API base URL |
| `VELO_REMOTE` | No | `0` | Set to `1` to enable remote execution |
| `VELO_DEBUG` | No | `0` | Set to `1` for local debug (Windows native or Docker Java) |
| `VELO_SAP_CLIENT` | No | `auto` | SAP client: `auto`, `java`, or `windows` |

---

## Remote execution flow

When `VELO_REMOTE=1`, the following happens automatically:

```
1. Scan working directory and apply .veloignore rules
2. Package directory into a .zip archive
3. Upload archive to the Velo API
4. Trigger a remote run (optionally with --include / --exclude tags)
5. Stream Robot Framework log output to your terminal in real time
6. On completion: download log.html + report.html to ./results/
7. Exit with the standard RF exit code
```

The terminal experience is identical to a local RF run — log lines appear as tests execute, not buffered.

---

## What gets uploaded

The entire current working directory is packaged into a `.zip` archive when you run `robot`. The archive is created from the directory you run the command in, preserving the full folder structure.

**Typical archive contents:**

```
tests/
    smoke/
        login.robot
    regression/
        sales_order.robot
resources/
    keywords.robot
variables/
    common.py
```

Only files are included — empty directories are omitted. The archive is uploaded to the API, extracted into the execution container, and `robot` is run against the entire directory.

---

## .veloignore

A `.veloignore` file in the project root controls which files are excluded from the uploaded archive. It uses the same syntax as `.gitignore` (glob patterns, `#` comments, negation with `!`).

Place it at the root of your test project:

```
your-project/
├── .veloignore       ← here
├── tests/
├── resources/
└── ...
```

### Default exclusions

When **no `.veloignore` file is present**, the following are excluded automatically:

```
.git
__pycache__
*.pyc
*.pyo
venv
.venv
node_modules
.env
.env.*
results
*.log
```

### Important: defaults are replaced, not merged

If a `.veloignore` file exists, **it completely replaces the default list** — the defaults above are no longer applied. Include any defaults you still want in your `.veloignore`.

### Example .veloignore

```gitignore
# Re-include sensible defaults
.git
__pycache__
*.pyc
venv
.venv
.env
.env.*
results
*.log

# Project-specific exclusions
data/sensitive/
config/secrets.yaml
*.csv
docs/
```

### Verifying exclusions

After a run, inspect the uploaded archive on the API server:

```bash
unzip -l <storage_root>/suites/<suite_id>.zip
```

---

## Artifacts

When the run completes, the following are downloaded to your local `--outputdir` (default: `./results/`):

| File | Description |
|---|---|
| `log.html` | Full Robot Framework execution log with keyword-level detail |
| `report.html` | Test suite summary report |

The video recording (`recording.mp4`) is stored on the server and accessible via the API at `GET /api/runs/{run_id}/artifacts/video`.

---

## Exit codes

The package preserves standard RF exit codes so existing CI scripts and Makefiles work without modification:

| Code | Meaning |
|---|---|
| `0` | All tests passed |
| `1` | One or more tests failed |
| `2` | Invalid RF options or arguments |
| `3` | Test execution stopped by user |
| `252` | Help or version info printed |
| `253` | Platform error (upload failed, API unreachable, run did not start) |

---

## RF flag pass-through

All standard `robot` flags are forwarded to the remote execution environment:

| Flag | Behaviour |
|---|---|
| `--include TAG` / `--exclude TAG` | Passed to remote RF runner |
| `--variable KEY:VALUE` | Passed to remote RF runner |
| `--suite SUITE` | Passed to remote RF runner |
| `--outputdir PATH` | Controls local download destination for results |
| `--dryrun` | Executes locally — remote is not triggered |

---

## Development install (editable)

```bash
git clone <repo>
cd velo
pip install -e packages/robotframework-velo-cli
```
