Implementation:MarketSquare Robotframework browser Bootstrap Script

Document Type

API Doc -- Documents the bootstrap.py script, an imperative top-level script that creates a Python virtual environment and installs all development and project dependencies for the robotframework-browser project.

Script Summary

The bootstrap.py script is the single entry point for setting up a development environment. It creates a .venv/ directory in the project root, installs the uv package manager, then uses uv to install both development requirements and project dependencies. After completion, it prints the OS-appropriate activation command.

Source Reference

File	Lines	Description
bootstrap.py	L1-56	Complete bootstrap script

Usage

python bootstrap.py

This should be run from the project root directory. It requires only a system Python installation (3.10+) with the venv module available.

Source Code

"""Creates a virtual environment for developing the library.

Also installs the needed dependencies.
"""

import platform
import subprocess
from pathlib import Path
from venv import EnvBuilder

ROOT_DIR = Path(__file__).parent
VENV_DIR = ROOT_DIR / ".venv"
if not platform.platform().startswith("Windows"):
    VENV_PYTHON = VENV_DIR / "bin" / "python"
else:
    VENV_PYTHON = VENV_DIR / "Scripts" / "python.exe"
SRC_DIR = ROOT_DIR / "Browser"

if not VENV_DIR.exists():
    print(f"Creating virtualenv in {VENV_DIR}")
    EnvBuilder(with_pip=True).create(VENV_DIR)

subprocess.run([VENV_PYTHON, "-m", "pip", "install", "-U", "uv"], check=True)
subprocess.run(
    [
        VENV_PYTHON,
        "-m",
        "uv",
        "pip",
        "install",
        "-r",
        str(SRC_DIR / "dev-requirements.txt"),
    ],
    check=True,
)
subprocess.run(
    [
        VENV_PYTHON,
        "-m",
        "uv",
        "pip",
        "install",
        "-r",
        str(ROOT_DIR / "pyproject.toml"),
    ],
    check=True,
)

activate_script = (
    "source .venv/bin/activate"
    if not platform.platform().startswith("Windows")
    else ".venv\\Scripts\\activate.bat"
)
print(f"Virtualenv `{VENV_DIR}` is ready and up-to-date.")
print(f"Run `{activate_script}` to activate the virtualenv.")

Execution Steps

Step 1: Path Configuration

ROOT_DIR = Path(__file__).parent
VENV_DIR = ROOT_DIR / ".venv"
if not platform.platform().startswith("Windows"):
    VENV_PYTHON = VENV_DIR / "bin" / "python"
else:
    VENV_PYTHON = VENV_DIR / "Scripts" / "python.exe"
SRC_DIR = ROOT_DIR / "Browser"

The script determines:

• ROOT_DIR -- The directory containing the script (project root)
• VENV_DIR -- The virtual environment directory (.venv/)
• VENV_PYTHON -- The Python executable inside the virtual environment (OS-dependent path)
• SRC_DIR -- The Browser/ source directory (contains dev-requirements.txt)

Step 2: Virtual Environment Creation

if not VENV_DIR.exists():
    print(f"Creating virtualenv in {VENV_DIR}")
    EnvBuilder(with_pip=True).create(VENV_DIR)

• Uses Python's built-in venv.EnvBuilder with with_pip=True to ensure pip is available
• Skips creation if .venv/ already exists (idempotent behavior)
• Creates the standard virtual environment structure with bin/ (Unix) or Scripts/ (Windows) directories

Step 3: Install uv

subprocess.run([VENV_PYTHON, "-m", "pip", "install", "-U", "uv"], check=True)

Installs or upgrades the uv package installer using pip. The -U flag ensures the latest version is installed. check=True causes the script to abort if pip fails.

Step 4: Install Development Dependencies

subprocess.run(
    [VENV_PYTHON, "-m", "uv", "pip", "install", "-r",
     str(SRC_DIR / "dev-requirements.txt")],
    check=True,
)

Uses uv pip install to install all packages listed in Browser/dev-requirements.txt. This includes:

• Testing tools: pytest, robotstatuschecker, pabot, approvaltests
• Linting: ruff, mypy
• Build tools: invoke, build, twine, stubgen
• Documentation: rellu, beautifulsoup4
• gRPC tools: grpcio-tools, mypy-protobuf

Step 5: Install Project Dependencies

subprocess.run(
    [VENV_PYTHON, "-m", "uv", "pip", "install", "-r",
     str(ROOT_DIR / "pyproject.toml")],
    check=True,
)

Installs the project's own runtime dependencies as specified in pyproject.toml. This includes:

• robotframework
• grpcio
• protobuf
• Other runtime dependencies

Step 6: Print Activation Instructions

activate_script = (
    "source .venv/bin/activate"
    if not platform.platform().startswith("Windows")
    else ".venv\\Scripts\\activate.bat"
)
print(f"Virtualenv `{VENV_DIR}` is ready and up-to-date.")
print(f"Run `{activate_script}` to activate the virtualenv.")

Prints the OS-appropriate activation command so the developer knows how to activate the newly created environment.

Output

On a fresh setup, the script produces output similar to:

Creating virtualenv in /path/to/project/.venv
... (pip and uv installation output) ...
... (dev-requirements.txt installation output) ...
... (pyproject.toml installation output) ...
Virtualenv `/path/to/project/.venv` is ready and up-to-date.
Run `source .venv/bin/activate` to activate the virtualenv.

Idempotency

The script is safe to run multiple times:

• If .venv/ exists, the EnvBuilder step is skipped
• uv is upgraded (-U) if already installed
• Dependencies are reinstalled/upgraded as needed

What Bootstrap Does NOT Do

The bootstrap script handles only Python dependencies. It does not:

• Install Node.js dependencies (use inv deps for that)
• Compile protobuf files (use inv protobuf)
• Build the Node.js wrapper (use inv node-build)
• Install Playwright browsers (use rfbrowser install)

For a complete development setup after bootstrap, run inv build which handles all remaining steps.

Related

• MarketSquare_Robotframework_browser_Development_Environment_Setup -- Principle document for environment setup
• MarketSquare_Robotframework_browser_Inv_Build -- The build pipeline that follows environment setup
• MarketSquare_Robotframework_browser_Inv_Utest_Atest -- Running tests after environment is set up

Requires Environment

• Environment:MarketSquare_Robotframework_browser_Python_Runtime