robotframework-velo-cli 0.5.0

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.

Third-party CI/CD tools (Copado, Pace, Docker-based runners)

Some CI/CD platforms (e.g. Copado Robotic Testing) invoke Robot Framework directly via python -m robot rather than through the robot binary. In those environments the robot entry point shim is bypassed entirely, regardless of PATH ordering.

Run the following command after pip install to install a Python startup hook (usercustomize.py) that intercepts python -m robot at the interpreter level:

velo install

The hook is written to the user site-packages directory for the active Python version and is loaded automatically by every new Python subprocess. It is a no-op when VELO_REMOTE is not set.

Typical pre-start hook for Copado / Pace environments:

export PATH=/home/executor/.local/bin:$PATH
export VELO_REMOTE=1
export VELO_API_KEY=<your-api-key>

pip install robotframework-velo-cli
pip install robotframework-velo-sapgui   # if using SAP GUI keywords

velo install

You should see [velo] usercustomize: robot.run_cli patched in the test run output, followed by [velo] uploading suite..., confirming the interception is active.

---

Quick start

# 1. Save credentials once (stored in ~/.config/velo/config.yaml, mode 0600)
velo login --api-base http://localhost:8000 --engine robot-sap
# prompts for API key if --api-key is omitted

# 2. Run on Velo — no VELO_REMOTE needed
velo robot ./tests

# 3. One-shot overrides + RF tag filters
velo robot --engine robot-sap --api-base http://localhost:8000 \
  --include smoke --exclude wip ./tests

CI / Copado can still use env vars + the robot wrapper:

export VELO_API_KEY=<your-api-key>
export VELO_API_BASE=http://localhost:8000   # or https://velo.aster.pro/cli in prod
VELO_REMOTE=1 robot ./tests

---

velo commands

Command	Purpose
velo robot [opts] <suite>	Always run remotely (batched). Options: --engine, --engine-version, --api-base
velo login	Save API key (+ optional api_base / engine / engine_version)
velo logout	Remove stored API key
velo configure	Update stored api_base / engine / engine_version
velo install	Install usercustomize hook for python -m robot in CI

Settings resolve in order: CLI flags → env vars → ~/.config/velo/config.yaml → defaults.

---

Execution modes

Variable / command	Behaviour
velo robot …	Always remote (does not require VELO_REMOTE)
VELO_REMOTE=1 robot …	Remote via the shadowed robot entry point
robot … (no remote flag)	Local Robot Framework
VELO_DEBUG=1 robot …	Local debug: native SAP GUI for Windows, or Docker Java elsewhere

---

Environment variables

Variable	Required	Default	Description
VELO_API_KEY	Yes (remote)*	—	Workspace API key (*or stored via velo login)
VELO_API_BASE	No	https://velo.aster.pro/cli	API origin. Local: http://localhost:8000. Prod: include the /cli gateway prefix.
VELO_ENGINE	No	robot-sap	Engine ID sent on suite upload
VELO_ENGINE_VERSION	No	engine default	Optional engine version pin
VELO_REMOTE	No	0	Set to 1 for remote when using robot / python -m robot
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 you run velo robot (or VELO_REMOTE=1 robot), the following happens automatically:

1. Scan working directory and apply .veloignore rules
2. Package directory into a .zip archive
3. Upload archive to POST /api/suites (with engine)
4. Trigger POST /api/executions with strategy=batched (one container)
5. Stream logs from the single child run via SSE
6. On completion: download output.xml + log.html + report.html to ./results/
7. Exit with the standard RF exit code

The CLI currently supports single-run sequential execution only (strategy=batched). Multi-run / isolated fan-out is not supported yet.

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 is stored on the server and available via the run's artifact_urls (kind video) at GET {VELO_API_BASE}/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

Flag	Behaviour
--include TAG / --exclude TAG	Sent as engine params.include / params.exclude (ROBOT_INCLUDE / ROBOT_EXCLUDE)
--variable KEY:VALUE	Forwarded as structured variables on the execution
--variablefile PATH	Scalar YAML entries forwarded as variables
--outputdir PATH	Local download destination for result artifacts

---

Development install (editable)

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