View source for Principle:MarketSquare Robotframework browser Development Environment Setup

{{PageInfo|type=Principle|title=MarketSquare_Robotframework_browser_Development_Environment_Setup}}
== Overview ==

The '''robotframework-browser''' project requires both '''Python''' and '''Node.js''' toolchains to develop, build, and test. Setting up a reproducible development environment is the first step for any contributor. The project provides a bootstrap script that automates virtual environment creation and dependency installation, ensuring every developer works with a consistent set of tools and versions.

== Core Concept ==

A '''reproducible development environment''' means that every developer, regardless of their system-level Python or Node.js installation, works within an isolated and consistent set of dependencies. The key mechanisms are:

* '''Python virtual environment''' (<code>venv</code>) -- Isolates Python packages from the system installation, preventing version conflicts
* '''uv''' -- A fast Python package installer (written in Rust) that replaces <code>pip install</code> for speed, used to install both development and project dependencies
* '''npm''' -- The Node.js package manager, used separately (via <code>inv deps</code>) for Node.js dependencies

== Bootstrap Process ==

The bootstrap script performs these steps in sequence:

# '''Check for existing virtual environment''' -- If <code>.venv/</code> already exists, skip creation
# '''Create virtual environment''' -- Uses Python's built-in <code>venv.EnvBuilder</code> with pip enabled
# '''Install uv''' -- Upgrades pip and installs the <code>uv</code> package installer into the virtual environment
# '''Install development dependencies''' -- Uses <code>uv pip install</code> with <code>Browser/dev-requirements.txt</code>
# '''Install project dependencies''' -- Uses <code>uv pip install</code> with <code>pyproject.toml</code>
# '''Print activation instructions''' -- Displays the OS-appropriate command to activate the virtual environment

== Dependency Categories ==

The project has two distinct sets of Python dependencies:

{| class="wikitable"
! Category !! Source File !! Contents
|-
| Development dependencies || <code>Browser/dev-requirements.txt</code> || Testing tools (pytest, robotstatuschecker, pabot), linting (ruff, mypy), build tools (invoke, build, twine), and other development utilities
|-
| Project dependencies || <code>pyproject.toml</code> || Runtime dependencies of the Browser library itself (robotframework, grpcio, etc.)
|}

Node.js dependencies are defined in <code>package.json</code> and <code>package-lock.json</code> and are installed separately via the <code>inv deps</code> task.

== Platform Awareness ==

The bootstrap script is platform-aware:

* On '''Unix/macOS''': The virtual environment Python is at <code>.venv/bin/python</code> and activation is <code>source .venv/bin/activate</code>
* On '''Windows''': The virtual environment Python is at <code>.venv/Scripts/python.exe</code> and activation is <code>.venv\Scripts\activate.bat</code>

== Why uv Instead of pip ==

The project uses '''uv''' for dependency installation because:

* It is significantly faster than pip for resolving and installing packages
* It supports the same requirements file formats and pyproject.toml
* It provides the <code>--system</code> flag for CI environments where virtual environments are not used
* It is installed as a pip package itself, so it can be bootstrapped from any Python environment

== Domains ==

* '''Development_Tooling''' -- The bootstrap script is a developer productivity tool
* '''Environment_Management''' -- Virtual environments provide dependency isolation

== Implemented By ==

* [[implemented_by::Implementation:MarketSquare_Robotframework_browser_Bootstrap_Script]]

== Related Topics ==

* [[MarketSquare_Robotframework_browser_Bootstrap_Script]] -- Implementation details of the bootstrap script
* [[MarketSquare_Robotframework_browser_Project_Build_Pipeline]] -- The next step after environment setup
* [[MarketSquare_Robotframework_browser_Inv_Build]] -- The build tasks that depend on the development environment

[[Category:Principles]]