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_env.json and config_ollama.json
test_envs/configs/config_env.json stores the selected OS and timezone. test_envs/configs/config_ollama.json stores the Ollama endpoint, model, prompt, timeout, and retry 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_envs.json
test_envs/configs/check_envs.json records detected OS and Python runtime status. Ollama status is written separately to test_envs/configs/check_ollama.json.
| 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 |
Both check files are generated data. Change config_env.json or config_ollama.json and rerun the check command instead of manually editing them.
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_envs.json or check_ollama.json |
They are 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_envs.json and test_envs/configs/check_ollama.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_env.json # Selected OS and timezone
│ ├── config_ollama.json # Ollama settings
│ ├── check_envs.json # Detected OS and Python status
│ └── check_ollama.json # Detected Ollama 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.