Python Environment

The project uses system Python for initial setup and the project-local .venv for normal test and report execution.

Python Usage

Stage	Python	Purpose
OS selection	System Python	Selects the host OS before `.venv` is required
Virtual environment creation	System Python	Creates `.venv` and installs project dependencies
Pytest and Unittest	Project Python	Runs tests in an isolated environment
Environment and report tools	Project Python	Runs `test_envs.tools.*` modules
VS Code Testing	Project Python	Discovers and executes tests through pytest

OS	Project Python
Windows	`.venv/Scripts/python.exe`
Linux	`.venv/bin/python`
macOS	`.venv/bin/python`

VS Code Usage

VS Code entry	Interpreter	Operation
`SETUP 1: Select Operating System`	System Python	Selects the OS through the matching Task
`SETUP 2: Install Python Virtual Environment`	System Python	Creates `.venv` through the matching Task
`SETUP 3: Install Ollama and Local LLM`	Project Python	Installs the Local LLM environment after `.venv` exists
VS Code Testing	Project Python	Discovers pytest and unittest tests through pytest
Report Tasks	Project Python	Generates Markdown, MkDocs, HTML, and DOCX reports

VS Code uses python.defaultInterpreterPath from .vscode/settings.json.

OS	VS Code interpreter setting
Windows	`${workspaceFolder}/.venv/Scripts/python.exe`
Linux	`${workspaceFolder}/.venv/bin/python`
macOS	`${workspaceFolder}/.venv/bin/python`

Automatic terminal activation is disabled with python.terminal.activateEnvironment: false. Use the explicit project Python path or activate .venv manually when needed.

See VS Code Environment for Settings, Run and Debug, Run Tasks, and Testing configuration.

Configuration and Status

config.json

test_envs/configs/config.json stores user-selected project configuration.

Key	Role
`version`	Configuration schema version
`os`	Platform used by environment setup
`time`	Report timezone and UTC offset
`ollama`	Local LLM endpoint, model, prompt, timeout, and retry settings

check.json

test_envs/configs/check.json records detected runtime status.

Section	Recorded status
`generated_at`	Time of the latest environment check
`os`	Configured OS, detected OS, and host platform name
`python`	Installation status, executable path, and version
`ollama`	Executable, endpoint, selected model, and installed models

check.json is generated data. Change config.json and rerun the check command instead of manually editing check.json.

Usage Rules

Rule	Reason
Run commands from the repository root	`test_envs` imports and repository-relative paths depend on it
Use system Python for Setup 1 and Setup 2	The project environment may not exist yet
Use `.venv` Python after setup	Keeps project dependencies isolated from global packages
Keep `.venv` out of Git	It is reproducible from `requirements.txt`
Do not manually edit `check.json`	It is regenerated from detected runtime state

Troubleshooting

Symptom	Check
`No module named test_envs`	Run the command from the repository root
Configured platform does not match host	Set `os` to `auto` or the current host OS
`.venv` Python is missing	Run Setup 2 with system Python
pip installation fails	Verify network access and `requirements.txt`
`Invalid VS Code settings` during OS selection	The configuration tool currently reads `.vscode/settings.json` with a strict JSON parser; JSONC comments are not accepted
Test discovery imports fail	Verify the project interpreter and workspace root

Environment Installation

Requirements

Requirement	Purpose
System Python	Provides `venv` and `ensurepip`
Repository root	Contains `requirements.txt` and `test_envs/`
Network access	Downloads missing Python packages
Windows PowerShell	Runs the Windows examples below

Python setup does not install Ollama or a Local LLM. See Local LLM Environment for that installation.

Windows PowerShell

Run each command from the repository root.

Select the operating system:

python -m test_envs.tools.configuration select-os

Create or update .venv:

python -m test_envs.test_pipeline.environment_setup python --platform config

Verify project Python:

.\.venv\Scripts\python.exe --version

Refresh environment status:

.\.venv\Scripts\python.exe -m test_envs.tools.configuration check

Verify test discovery:

.\.venv\Scripts\python.exe -m pytest -p no:cacheprovider --collect-only

For non-interactive Windows OS selection:

python -m test_envs.tools.configuration set-os --os windows

Linux and macOS

python3 -m test_envs.tools.configuration select-os

python3 -m test_envs.test_pipeline.environment_setup python --platform config

./.venv/bin/python -m test_envs.tools.configuration check

Installation Flow

test_envs.test_pipeline.environment_setup python performs these operations:

Resolve configured platform
        ↓
Verify configured OS matches the host OS
        ↓
Create .venv when missing
        ↓
Run ensurepip --upgrade
        ↓
Upgrade pip
        ↓
Install requirements.txt
        ↓
Refresh test_envs/configs/check.json

An existing .venv is reused. The command still installs requirements.txt again, so it can be rerun after dependency changes.

Installed Packages

Requirement	Purpose
`pytest`	Runs CT and unit tests
`pytest-cov`	Produces Python coverage data
`mkdocs`	Builds and serves documentation
`mkdocs-material`	Provides the documentation theme
`mkdocs-mermaid2-plugin`	Renders Mermaid diagrams
`pyserial`	Supports UART interfaces
`pyusb`	Supports USB interfaces

The authoritative package versions are defined in requirements.txt.

Full test_envs Structure

test_envs/
├── configs/
│   ├── config.json                 # Selected OS, timezone, and Ollama settings
│   └── check.json                  # Detected environment status
├── tests/
│   ├── fixtures/
│   │   └── junit.xml               # Shared result fixture
│   ├── pytest/
│   │   ├── conftest.py             # TEST ID and mock/hil normalization
│   │   ├── fixtures/               # Equipment/interface combinations
│   │   ├── test_cases/             # CT-UART, CT-USB, and CT-NETWORK
│   │   ├── test_equipments/
│   │   │   ├── fpga/{mock,hil}/
│   │   │   ├── saleae/{mock,hil}/
│   │   │   └── digilent/{mock,hil}/
│   │   └── test_interfaces/
│   │       ├── usb/{mock,hil}/
│   │       ├── uart/{mock,hil}/
│   │       ├── jtag/{mock,hil}/
│   │       └── network/{mock,hil}/
│   └── unittest/
│       ├── conftest.py             # Unittest result normalization
│       └── ct_framework/python/    # Current Python framework tests
├── tool_github/
│   ├── github_reporter/             # GitHub Issue result reporting
│   └── issue_parser.py              # GitHub Issue request parsing
├── test_pipeline/
│   ├── environment_setup.py         # Python and Ollama setup
│   └── pipeline.py                  # Test result analysis and report pipeline
└── tools/
    ├── configuration/               # config, check, set-os, and select-os
    ├── extension_runner.py          # Future extension execution
    ├── extensions/                  # Extension modules
    ├── local_llm/                   # Local LLM client and status
    ├── test_result/                 # Pending-result processing
    ├── mkdocs_reporter/             # MkDocs Markdown publishing
    ├── pandoc_reporter/             # HTML, DOCX, and PDF conversion
    ├── result_normalizer/           # Common result model
    └── log_parser/

test_reports/
├── results/{pytest/test_cases,unittest}/ # Result JSON and execution logs
├── markdown/{pytest/test_cases,unittest}/ # Generated Markdown reports
├── pandocs/{pytest/test_cases,unittest}/  # Generated HTML, DOCX, or PDF
└── local_llm/                            # Local LLM analysis artifacts

The {mock,hil} notation means that each listed equipment or interface provides separate mock/ and hil/ implementations. Pytest CT execution ultimately resolves to one of these two modes.