Command-Line Selection, Tag Expressions, Reruns, and Execution Profiles: Core Concepts and Mental Model

1. The problem: the same repository can execute very different test sets

Chapter 14 turned results into durable evidence. Chapter 15 moves one step earlier: which tests were allowed to enter the run? A repository may contain hundreds of tests, but a developer wants one test, a pull request wants smoke tests, a nightly job wants regression without slow cases, and an incident responder wants to reproduce exactly the failed slice. If selection is implicit, a green result may simply mean the wrong tests ran.

Robot Framework therefore has two related but different control planes. The first is the core command line: source paths, --suite, --test, tag filters, variables, search paths, modifiers/listeners, and output options. The second is any external wrapper that composes those options—for example RobotCode profiles. A wrapper can be useful, but the resulting Robot invocation remains the thing that determines execution.

2. Read-only preflight: prove the tool and source before selecting

python --version
python -m robot --version
python -m robot --help
# Inspect source without modifying it.
# PowerShell: Get-ChildItem -Recurse tests -Filter *.robot
# Bash:       find tests -type f -name "*.robot" -print

Record the interpreter/framework version, current working directory, exact source path, and existing result directories. The working directory matters because data-source arguments and relative output paths are interpreted in the process context. A selection command is not reproducible if “run this from somewhere around the repository” is part of the procedure.

3. Mental model: source → configuration → selection → execution → evidence

flowchart TD
A[Project source] --> B[robot CLI parser]
C[CLI flags / argument files] --> B
D[Variables / pythonpath / modifiers] --> B
B --> E[Parsed suite model]
E --> F[Suite + test name selectors]
F --> G[Include / exclude filters]
G --> H[Skip policy]
H --> I[Selected execution model]
I --> J[Keyword execution]
J --> K[output.xml + log/report]
L[External RobotCode profile] -. expands to options .-> C

The source model exists before selection. Name and tag selectors decide which tests enter the execution model. --skip is different: matching tests remain part of the result model but are marked skipped rather than executed. Variables and search paths influence runtime configuration; listeners and pre-run modifiers can alter model behavior and must therefore be recorded as provenance. The outputs prove what Robot recorded—not what somebody intended to select.

4. Name every state owner

5. Name selection: simple names versus long names

--test and --suite accept case-, space-, and underscore-insensitive simple patterns with *, ?, and bracket patterns. A test can be selected by simple name, but when a parent suite is included in the selector the whole suite path from the execution root must match. This is why root selection is part of identity.

# Run a test by simple name anywhere under tests/.
python -m robot --test "Health Is Smoke" tests

# If tests/ is the root suite named Tests and service.robot is Service:
python -m robot --test "Tests.Service.Health Is Smoke" tests

# Match the same child suite anywhere by explicitly allowing any root prefix.
python -m robot --suite "*.Service" tests

Do not confuse selection with executing a child file directly. Selecting Service while executing the root keeps the higher-level suite context. Executing tests/service.robot directly creates a different root and can bypass higher-level initialization.

6. Tag expressions are predicates, not environment configuration

--include selects tests whose tags match; --exclude vetoes tests whose tags match. Repeating --include behaves like an OR across the supplied include patterns; repeating --exclude excludes a test if any exclude pattern matches. Within one tag pattern, Robot supports AND (or &), OR, and NOT. Operators are uppercase and case-sensitive even though tag matching itself is case-insensitive.

python -m robot --include smoke tests
python -m robot --include regression --exclude slow tests
python -m robot --include regressionNOTslow tests
python -m robot --include smokeORrerun-demo tests
python -m robot --include smoke --include regression tests

7. --skip and --exclude intentionally leave different evidence

A release report that says “3 passed, 1 skipped” communicates a different contract from “3 tests selected.” Use the distinction deliberately. Do not convert known failures to skips merely to make a pipeline green.

8. Argument files are Robot Framework core configuration

--argumentfile (or -A) inserts options and data sources into the command line at the position where the argument file is referenced. One option or data source is written per line. Later single-valued options can override earlier values because ordinary command-line precedence still applies. Argument files may be nested. In 7.4, environment expansion is available only when explicitly enabled with # expandvars: true.

# config/smoke.args
--include smoke
--exclude slow
--variable TARGET_ENV:local
--variable EXPECTED_ENV:local
--outputdir results/smoke
tests

python -m robot --argumentfile config/smoke.args
# Later options can override earlier single-valued ones.
python -m robot --argumentfile config/base.args --outputdir results/adhoc tests

Relative data-source/output paths inside an argument file do not magically become relative to the argument file. Treat the project working directory as part of the command contract or use an explicit launcher that normalizes paths.

9. Failed-only rerun is selection by prior identity

--rerunfailed reads an earlier Robot output and selects the failed tests as if they had been selected with --test. The source still has to describe the same logical tests. Renaming/moving suites between the original run and rerun can therefore break identity or create undefined behavior. Preserve the first output, write rerun output separately, then merge as a derived artifact.

python -m robot --outputdir results/initial --output original.xml tests
python -m robot --rerunfailed results/initial/original.xml \
  --outputdir results/rerun --output rerun.xml tests
python -m robot.rebot --merge \
  --outputdir results/final --output merged.xml \
  results/initial/original.xml results/rerun/rerun.xml

The merged result answers “what is the corrected combined state after the rerun?” It does not erase the fact that the first run failed. Production policy should retain both originals and annotate a rerun-only pass rather than silently classifying it as equivalent to a first-pass success.

10. Execution profiles are an external composition layer

Robot Framework core has no robot.toml profile engine. RobotCode supplies one. That distinction matters because installing robotframework alone does not make RobotCode commands or profile precedence available. At the current pinned optional version, RobotCode 2.7.0 loads global/user, pyproject.toml, project robot.toml, and project-local .robot.toml configuration in documented order; profiles can then add/override settings.

# robot.toml -- OPTIONAL RobotCode 2.7.0 layer, not Robot Framework core
paths = ["tests"]
output-dir = "results/robotcode"

[profiles.smoke]
extend-includes = ["smoke"]
variables = { TARGET_ENV = "local", EXPECTED_ENV = "local" }

# Requires: pip install "robotcode[runner]==2.7.0"
robotcode -p smoke run

A team can commit robot.toml while ignoring .robot.toml for developer-local overrides. That convenience must not make the executed configuration invisible; record the selected profile and inspect the resolved profile before relying on it in CI.

11. DevOps connection: selection is part of release evidence

A fast feedback lane is trustworthy only if the command, selectors, variables, source revision, result path, and wrapper/profile layer are reproducible. The practical operating rule is: first prove what will be selected, then execute, then prove what actually appeared in output.xml.

Knowledge check

Summary and bridge

You can now treat selection as a deterministic control plane rather than a collection of ad-hoc flags. Lesson 2 turns that model into a small local project with measurable slice counts, a controlled failure, failed-only rerun, and merge evidence.

References and version anchors

• Robot Framework 7.4.2 User Guide — CLI option syntax, name/tag selection, argument files, reruns, skip/exclude semantics, and result post-processing.
• Robot Framework 7.4.2 on PyPI — stable release and Python compatibility anchor.
• RobotCode configuration documentation and RobotCode 2.7.0 on PyPI — optional external profile layer only.