Python Environment, Installation, CLI, Editors, and First Suite: Guided Hands-On Workflow

1. Scenario: build a tiny project whose runtime can be proven

You will create a project containing one exact dependency declaration, one small BuiltIn-only suite, and explicit result directories. The objective is not to learn many Robot keywords. It is to prove that a known interpreter installs a known Robot Framework version, executes a known suite, and places evidence in a known path.

flowchart TD
A[Empty project directory] --> B[Create .venv]
B --> C[Record interpreter identity]
C --> D[Install robotframework==7.4.2]
D --> E[Verify pip and Robot identity]
E --> F[Create tests/environment.robot]
F --> G[Run via environment Python]
G --> H[results/run-01]
H --> I[Inspect output.xml]
H --> J[Inspect log.html]
H --> K[Inspect report.html]

2. Target project layout

rf-env-lab/
├── .gitignore
├── requirements.txt
├── tests/
│   └── environment.robot
└── results/
    └── run-01/
        ├── output.xml
        ├── log.html
        └── report.html

The .venv directory is intentionally omitted from the committed layout. It is local runtime state. requirements.txt is the reproducible dependency input for this baseline lab.

# requirements.txt
robotframework==7.4.2

# .gitignore
.venv/
results/
__pycache__/

3. Create the environment with an explicit interpreter

Choose one platform path. The examples request Python 3.12 to make the interpreter choice visible. If your supported Python has a different command, substitute it and record the actual version.

Windows PowerShell

py -3.12 --version
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -c "import sys; print(sys.executable); print(sys.version)"

macOS/Linux shell

python3.12 --version
python3.12 -m venv .venv
./.venv/bin/python -c 'import sys; print(sys.executable); print(sys.version)'

The last command is the first verification checkpoint. It proves which interpreter lives behind the environment path. Do not proceed merely because a folder named .venv exists.

4. Install the exact dependency into that environment

Windows PowerShell

.\.venv\Scripts\python.exe -m pip --version
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip show robotframework
.\.venv\Scripts\python.exe -m robot --version

macOS/Linux shell

./.venv/bin/python -m pip --version
./.venv/bin/python -m pip install -r requirements.txt
./.venv/bin/python -m pip show robotframework
./.venv/bin/python -m robot --version

Using the environment's Python path avoids a hidden PATH dependency. python -m pip installs into the interpreter that launched pip; python -m robot then loads Robot Framework from that same environment.

5. Create the first suite

The suite uses only BuiltIn, which Robot Framework makes available automatically. The test intentionally has no external side effects.

*** Settings ***
Documentation    Proves the pinned local Robot Framework environment.

*** Test Cases ***
Pinned Environment Can Execute
    ${status}=    Set Variable    ready
    Log    Environment status: ${status}
    Should Be Equal    ${status}    ready

Read the source before running it. Robot will parse one suite from the file, discover one test, call three BuiltIn keywords, and produce a PASS result if the literal values match. No browser session, HTTP request, database row, or process is created.

6. Predict the state changes before execution

7. Run with an explicit result directory

Windows PowerShell

.\.venv\Scripts\python.exe -m robot --outputdir results/run-01 tests

macOS/Linux shell

./.venv/bin/python -m robot --outputdir results/run-01 tests

A successful console run should identify the suite and test, show a PASS summary, and name the generated output, log, and report files. Exact timing and absolute paths vary by machine; the semantic evidence is the one-test PASS result and the three artifact types.

8. Inspect the evidence rather than stopping at a green console

First inspect the directory tree. Then open log.html locally and expand the test to see the keyword trace. report.html summarizes suite/test status. output.xml is the structured result source that downstream tools such as Rebot can process.

results/run-01/
├── output.xml
├── log.html
└── report.html

Inside the log, expect to see the test name Pinned Environment Can Execute and the calls Set Variable, Log, and Should Be Equal. If the console is green but the expected test is missing, that is a selection/path problem, not a success.

9. Compare module execution with the convenience launcher

Activation is now safe to demonstrate because you already know the environment works without it.

Windows PowerShell

.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
robot --version
robot --outputdir results/run-launcher tests
deactivate

macOS/Linux shell

source .venv/bin/activate
python -c 'import sys; print(sys.executable)'
robot --version
robot --outputdir results/run-launcher tests
deactivate

The launcher run should have the same semantic result as the explicit-module run. The point is not that one syntax is universally superior; it is that the environment identity should be demonstrably the same.

10. Optional editor setup without making it the runtime authority

If you use VS Code and RobotCode, install the current extension from its official distribution and select the project's environment interpreter. Current RobotCode requires Python 3.10+ and Robot Framework 5.0+, so a Python 3.12 environment satisfies the current runtime floor. Keep the CLI run above as the reproducibility baseline.

• Open the project folder, not an unrelated parent workspace.
• Select the .venv Python environment using the editor's supported interpreter-selection command.
• Confirm RobotCode discovers tests/environment.robot.
• Run from the editor only after the CLI run is green; compare the selected interpreter and result configuration.
• Do not commit a personal absolute interpreter path.

11. Challenge: diagnose a deliberately ambiguous launcher

Open a fresh shell in the project without activating .venv. Before running anything, predict whether bare robot --version will work. Then inspect the command resolution and compare it to the explicit environment interpreter.

PowerShell

Get-Command robot -ErrorAction SilentlyContinue
.\.venv\Scripts\python.exe -m robot --version

POSIX

command -v robot || true
./.venv/bin/python -m robot --version

If the bare launcher is missing, that is expected in an unactivated clean shell. If it exists, do not assume it belongs to this project. The explicit environment command is the trusted baseline.

12. Verification and cleanup checklist

• Record the exact Python version and sys.executable.
• Record python -m pip --version from the environment.
• Confirm python -m robot --version reports 7.4.2.
• Confirm exactly one expected test executed and passed.
• Confirm results/run-01/output.xml, log.html, and report.html exist.
• Keep requirements.txt and the suite source; delete only the disposable .venv and result directories when you no longer need the lab evidence.

13. Knowledge check

14. Summary and next step

You built a pinned environment, proved interpreter/package provenance, executed one BuiltIn-only suite, and inspected explicit result artifacts. Lesson 3 compares alternative environment and tooling strategies so you can choose deliberately rather than copying one workstation recipe.

Further reading and current primary references

Version-sensitive statements in this lesson were checked on 2026-08-30. The mandatory path pins Robot Framework 7.4.2, the current stable release at the time of authoring. Robot Framework 7.5b1 is a pre-release and is not required. Robot Framework itself requires Python 3.8+; the current RobotCode toolchain has a stricter Python 3.10+ runtime requirement, so editor compatibility must be checked separately from framework compatibility.

• Robot Framework on PyPI — installation, Python requirement, release history
• Robot Framework 7.4.2 User Guide
• Robot Framework 7.4.2 release notes
• Python documentation — venv
• pip User Guide
• uv documentation — virtual environments
• RobotCode — current getting-started and environment guidance
• RobotCode project — current runtime requirements and configuration model
• External Testdoc — replacement for the deprecated built-in Testdoc