robotframework-velo-cli 0.1.7

Run Robot Framework test suites on the Velo cloud platform

robotframework-velo-cli

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

---

Installation

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

# 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

# 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:

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)

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