This guide describes the current local setup flow for the repository, including the configuration and workflow choices most contributors need in practice.

Robottelo is a pytest-based functional test suite for Red Hat Satellite and Foreman. In practice, a working local setup usually needs more than a Python environment:

• Python and the repo dependencies
• broker configuration for provisioning or remote execution
• Robottelo configuration in conf/ and settings.local.yaml
• access to a Satellite/Foreman environment or inventory your team already uses

If you only want to work on framework code or docs, you can get away with a lighter setup. If you want to run functional tests, assume you will need broker and environment-specific configuration.

• Linux environment
• Python 3.12
• Git
• system packages needed to build Python dependencies

On Fedora/RHEL, the minimal system packages are:

sudo dnf install -y gcc python3-devel libxml2-devel

For most contributors, the cleanest starting point is:

git clone https://github.com/SatelliteQE/robottelo.git
cd robottelo

If you work from a fork, add your fork as origin and keep the main project as upstream.

Example:

git remote rename origin upstream
git remote add origin [email protected]:<your-github-username>/robottelo.git

This makes it easier to keep your branch synced with the main repository while pushing your work to your fork.

Using a virtual environment is strongly recommended. It keeps Robottelo’s dependencies isolated from your system Python and from other projects.

Use your preferred tool. venv, virtualenvwrapper, and uv all work.

python3.12 -m venv .venv
source .venv/bin/activate

mkvirtualenv robottelo
workon robottelo

Common virtualenvwrapper commands:

• mkvirtualenv <name> creates a venv
• workon <name> activates it
• rmvirtualenv <name> removes it
• lsvirtualenv lists existing environments

If you already use uv, it works well here too. The main benefit is faster dependency installation.

The repository keeps runtime dependencies in requirements.txt and developer tooling in requirements-optional.txt.

With uv:

uv pip install -r requirements.txt -r requirements-optional.txt

With pip:

pip install -r requirements.txt -r requirements-optional.txt

• requirements.txt gives you the runtime and test dependencies
• requirements-optional.txt gives you contributor tooling such as ruff, pre-commit, pytest-cov, sphinx, and manage

If you only need the leanest possible environment, you can skip the optional file at first, but most contributors end up needing it.

Robottelo relies on broker for provisioning test infrastructure and for working with remote hosts.

Depending on your installed broker version, one of these commands is typically used to initialize its config:

broker config init

or, on older workflows:

broker --version

The important outcome is that broker creates its settings and inventory files so you can edit them.

Typical values you may need to review in the generated broker config include:

host_username: <remote-user-you-want-to-use-for-remote-exec>
host_password: "<password>"
# Keep only if you use key-based authentication
host_ssh_key_filename: "</path/to/the/ssh-key>"

If your group maintains a known-good broker config or inventory outside this checkout, do not feel forced to rebuild everything locally from scratch. Using existing shared config is often the fastest path to a working setup.

Robottelo loads base configuration from the conf/ directory and allows local overrides through settings.local.yaml.

Create the config files from the templates:

for conffile in conf/*.yaml.template; do
  cp -- "$conffile" "${conffile%.yaml.template}.yaml"
done
cp settings.sample.yaml settings.local.yaml

At minimum, point Robottelo at an existing Satellite or Foreman instance:

dynaconf_merge: true
server:
  hostname: sat.example.com
  ssh_username: root
  ssh_password: your_password

You will see both styles in older examples and existing setups.

• use hostname when you are targeting one default system
• use hostnames when you maintain a pool of systems for xdist or balancing

Example:

dynaconf_merge: true
server:
  hostnames: ['sat615-1.example.com', 'sat615-2.example.com']
  ssh_username: root
  ssh_password: your_password

The sample settings file explicitly notes that environment variables are often preferred for overrides. If your environment already manages secrets and host selection externally, you may not need much in settings.local.yaml.

If your team already has a mature Robottelo config tree, it may be better to:

• copy that config into conf/
• symlink known-good config into place
• keep only personal overrides in settings.local.yaml

That usually scales better than manually recreating a large config surface.

Before trying a heavy functional run, validate the local environment in smaller steps.

ruff check .
ruff format .
make test-robottelo
make test-docstrings

make docs

make test-foreman-api
make test-foreman-cli
make test-foreman-ui
make test-foreman-sys
make test-foreman-upgrade

The Makefile is the best source for the current supported commands and common targets.

UI tests in tests/foreman/ui/ rely on Airgun/Selenium-style browser automation. In practice, these tests tend to be more environment-sensitive than API or CLI tests.

Good defaults:

• start with API or framework tests if you are validating a fresh setup
• run UI tests only after the base environment, broker config, and Satellite access are already working
• expect browser or display-related issues to be separate from Python dependency issues

If you are working on UI-specific code paths regularly, keep a stable local UI environment instead of treating every run as an ad hoc experiment.

requirements-optional.txt includes:

• pre-commit for local hooks
• pytest-cov for framework coverage
• sphinx for docs generation
• manage for the interactive helper shell

Install pre-commit hooks if you use them:

pre-commit install

If you regularly test multiple Satellite versions, using separate git worktrees is usually easier than constantly switching local settings in one checkout.

• each Satellite branch gets its own working tree
• each worktree can keep its own settings.local.yaml
• each worktree can use a dedicated virtual environment
• switching branches does not keep stomping on local config

Example:

git worktree add ../robottelo-6.15 6.15.z
git worktree add ../robottelo-6.16 6.16.z

Then, per worktree:

cd ../robottelo-6.15
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r requirements-optional.txt
cp settings.sample.yaml settings.local.yaml

No. For framework work, docs, and many cleanup tasks, you can get useful work done with the local Python environment plus make test-robottelo. For broader functional testing, you will usually need real infrastructure access.

Prefer settings.local.yaml for personal overrides. Edit conf/ when you are intentionally maintaining shared defaults or copying in a known-good config set.

• framework work: install dependencies and run make test-robottelo
• API/CLI work: add working server and SSH config
• UI work: do the above first, then validate your browser/display setup

Use the command supported by your installed broker version. The key requirement is simply that broker creates and exposes its config files so you can populate them.