Checkpoint Lab — Python Environment, Installation, CLI, Editors, and First Suite

1. Checkpoint charter

Your goal is to prove that a Robot Framework project can be reconstructed from declared inputs rather than remembered shell state. You will build a pinned environment, run the same suite twice from clean shells, record interpreter/framework provenance, create one controlled mismatch in a second environment, diagnose it, restore a clean execution, and retain evidence.

2. Target evidence packet

rf-env-checkpoint/
├── requirements.txt
├── tests/
│   └── environment.robot
├── evidence/
│   ├── run-01-provenance.txt
│   ├── run-02-provenance.txt
│   ├── mismatch.txt
│   └── recovery-provenance.txt
├── results/
│   ├── run-01/
│   │   ├── output.xml
│   │   ├── log.html
│   │   └── report.html
│   ├── run-02/
│   │   ├── output.xml
│   │   ├── log.html
│   │   └── report.html
│   └── recovered/
│       ├── output.xml
│       ├── log.html
│       └── report.html
└── .venv/                 # disposable, not evidence to commit

The evidence packet records facts; the virtual environment is rebuildable runtime state. Do not claim run-01 and run-02 XML files must be byte-identical—timestamps and execution IDs can differ. The invariant is the same selected suite/test and same semantic PASS result under the same declared versions.

3. Preflight and predictions

Before creating anything, write down two predictions:

1. After the correct environment install, python -m robot --version will report 7.4.2 and the environment interpreter path will point inside .venv.
2. After the first suite run, the source file and environment packages will remain unchanged, while a new run-specific result directory will contain output.xml, log.html, and report.html.

Also record the base Python version you intend to use. Examples below use Python 3.12.x. If you use a different supported 3.8+ interpreter, record it explicitly.

4. Create the declared project inputs

# requirements.txt
robotframework==7.4.2

*** Settings ***
Documentation    Checkpoint suite for environment reproducibility.

*** Test Cases ***
Environment Contract Is Reproducible
    ${framework}=    Set Variable    Robot Framework
    ${expected}=     Set Variable    Robot Framework
    Should Be Equal    ${framework}    ${expected}
    Log    Checkpoint execution is using synthetic data only.

Do not add browser or network libraries. The checkpoint is about environment provenance, not external integration.

5. Build the correct environment

Windows PowerShell

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m robot --version

macOS/Linux shell

python3.12 -m venv .venv
./.venv/bin/python -m pip install -r requirements.txt
./.venv/bin/python -m robot --version

Verification: the Robot version is 7.4.2 and the selected Python is the environment interpreter. If installation fails because of package-index connectivity, preserve the error and resolve network/proxy policy before changing project source.

6. Clean-shell run 1

Open a new shell in the project directory. Do not activate .venv. Use its Python path explicitly so the run does not depend on inherited shell state.

Windows PowerShell

New-Item -ItemType Directory -Force evidence | Out-Null
.\.venv\Scripts\python.exe -c "import sys; print(sys.executable); print(sys.version)" | Set-Content evidence\run-01-provenance.txt
.\.venv\Scripts\python.exe -m pip --version | Add-Content evidence\run-01-provenance.txt
.\.venv\Scripts\python.exe -m robot --version | Add-Content evidence\run-01-provenance.txt
.\.venv\Scripts\python.exe -m robot --outputdir results/run-01 tests

macOS/Linux shell

mkdir -p evidence
./.venv/bin/python -c 'import sys; print(sys.executable); print(sys.version)' > evidence/run-01-provenance.txt
./.venv/bin/python -m pip --version >> evidence/run-01-provenance.txt
./.venv/bin/python -m robot --version >> evidence/run-01-provenance.txt
./.venv/bin/python -m robot --outputdir results/run-01 tests

Verify one suite and one test executed and passed. Open results/run-01/log.html and confirm the expected test and BuiltIn keyword trace.

7. Clean-shell run 2

Close the shell completely. Open another fresh shell in the project directory and repeat the same explicit environment pattern into a different result folder.

Windows PowerShell

.\.venv\Scripts\python.exe -c "import sys; print(sys.executable); print(sys.version)" | Set-Content evidence\run-02-provenance.txt
.\.venv\Scripts\python.exe -m pip --version | Add-Content evidence\run-02-provenance.txt
.\.venv\Scripts\python.exe -m robot --version | Add-Content evidence\run-02-provenance.txt
.\.venv\Scripts\python.exe -m robot --outputdir results/run-02 tests

macOS/Linux shell

./.venv/bin/python -c 'import sys; print(sys.executable); print(sys.version)' > evidence/run-02-provenance.txt
./.venv/bin/python -m pip --version >> evidence/run-02-provenance.txt
./.venv/bin/python -m robot --version >> evidence/run-02-provenance.txt
./.venv/bin/python -m robot --outputdir results/run-02 tests

Compare the two provenance files: interpreter path, Python version, pip ownership, and Robot version should be consistent. Compare the run results semantically: same suite/test selection and PASS status. Timing values may differ.

8. Inject one reversible interpreter/dependency mismatch

Create .venv-broken but deliberately do not install Robot Framework into it. This simulates a common “right project, wrong interpreter” incident without damaging the working environment.

Windows PowerShell

py -3.12 -m venv .venv-broken
.\.venv-broken\Scripts\python.exe -c "import sys; print(sys.executable)" | Set-Content evidence\mismatch.txt
.\.venv-broken\Scripts\python.exe -m robot --version *>> evidence\mismatch.txt
$LASTEXITCODE
Get-Content evidence\mismatch.txt

macOS/Linux shell

python3.12 -m venv .venv-broken
./.venv-broken/bin/python -c 'import sys; print(sys.executable)' > evidence/mismatch.txt
./.venv-broken/bin/python -m robot --version >> evidence/mismatch.txt 2>&1 || true
cat evidence/mismatch.txt

Diagnosis: the interpreter exists, but its environment lacks the robot module. The failure happens before suite parsing. Do not edit tests/environment.robot.

9. Recover with the least destructive correction

Return to the known-good environment and run the smallest controlled slice into a fresh result directory.

Windows PowerShell

.\.venv\Scripts\python.exe -c "import sys; print(sys.executable); print(sys.version)" | Set-Content evidence\recovery-provenance.txt
.\.venv\Scripts\python.exe -m robot --version | Add-Content evidence\recovery-provenance.txt
.\.venv\Scripts\python.exe -m robot --outputdir results/recovered tests/environment.robot

macOS/Linux shell

./.venv/bin/python -c 'import sys; print(sys.executable); print(sys.version)' > evidence/recovery-provenance.txt
./.venv/bin/python -m robot --version >> evidence/recovery-provenance.txt
./.venv/bin/python -m robot --outputdir results/recovered tests/environment.robot

The recovered run should PASS without modifying suite source or installing anything globally. That confirms the failure belonged to the broken interpreter context.

10. Architecture/evidence diagram

flowchart LR
REQ[requirements.txt\nRF 7.4.2 pin] --> GOOD[.venv\ncorrect interpreter context]
GOOD --> ROBOT[python -m robot]
SUITE[tests/environment.robot] --> ROBOT
ROBOT --> R1[results/run-01]
ROBOT --> R2[results/run-02]
ROBOT --> RR[results/recovered]
BAD[.venv-broken\nno Robot package] --> FAIL[evidence/mismatch.txt]
GOOD --> PROV[evidence/provenance files]

Explain each arrow in your own words. In particular, .venv-broken does not make the suite invalid; it is a separate runtime state store whose missing dependency prevents Robot from starting.

11. Final verification checklist

• requirements.txt pins exactly robotframework==7.4.2.
• The correct environment's Python path is recorded and points inside .venv.
• Both clean-shell runs report the same Python/Robot version combination.
• Run 1 and run 2 each execute the expected single test and PASS.
• Both run directories contain output.xml, log.html, and report.html.
• evidence/mismatch.txt proves the broken environment lacks Robot Framework.
• The recovered run passes from the correct environment without global installation or suite changes.
• No credentials, production URLs, personal browser profiles, or external systems were used.

12. Cleanup and rollback

Preserve the evidence packet until the checkpoint is reviewed. Then the entire lab directory can be deleted because it contains only disposable local resources. If you want to retain the project as a learning example, keep requirements.txt, tests/, and optionally sanitized evidence; delete .venv, .venv-broken, and generated results when no longer needed.

Do not generalize this cleanup rule to production evidence. Real CI retention should follow policy and preserve first-failure artifacts for the required period.

13. Knowledge check

14. What Chapter 02 adds to a production operating model

You now have a reproducible bootstrap contract: choose a supported Python interpreter, create an isolated environment, install reviewed dependency inputs, execute Robot through an identifiable interpreter/launcher, write results to an explicit location, preserve first-failure evidence, and keep editor tooling subordinate to the same runtime truth.

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