test_scaffold_venv.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/tests_scaffold/test_scaffold_venv.py
 
"""
Purpose
-------
FS-503 / FS-504 regression coverage — the ``include_venv`` flag on
:func:`oct.scaffold.run_scaffold` must:
 
* create ``.venv/`` via :mod:`venv` when True (the default),
* populate :attr:`ScaffoldResult.venv_path`,
* leave ``venv_path`` as ``None`` when False,
* skip (not overwrite) an existing ``.venv/``,
* downgrade :class:`OSError` from the builder to a warning message,
* make the venv discoverable to :func:`check_venv_health` — i.e. the
  scaffolded project is then "venv-found" even before activation.
 
The tests stub :class:`venv.EnvBuilder` so the suite never shells out to
``ensurepip`` — we are testing the *contract*, not the stdlib.
 
Diagnostics
-----------
Domain: SCAFFOLD-TESTS
Levels:
    L2 — test lifecycle
 
Contracts
---------
- ``include_venv=True`` → ``.venv/`` created; ``venv_path`` set.
- ``include_venv=False`` → no ``.venv/``; ``venv_path is None``.
- Pre-existing ``.venv/`` is recorded in ``skipped`` with a message.
"""
 
from __future__ import annotations
 
from pathlib import Path
 
import pytest
 
from oct.scaffold import ScaffoldResult, run_scaffold
from oct.scaffold import oct_scaffold as _scaffold_mod
 
 
class _FakeEnvBuilder:
    """Drop-in replacement for :class:`venv.EnvBuilder` used in tests.
 
    Creates the target directory (mirroring the stdlib side-effect) without
    installing pip — cheap, deterministic, safe on Windows.
    """
 
    instances: list["_FakeEnvBuilder"] = []
 
    def __init__(self, *, with_pip: bool = True, clear: bool = False,
                 upgrade_deps: bool = False) -> None:
        self.with_pip = with_pip
        self.clear = clear
        self.upgrade_deps = upgrade_deps
        self.created: list[str] = []
        _FakeEnvBuilder.instances.append(self)
 
    def create(self, env_dir: str) -> None:
        Path(env_dir).mkdir(parents=True, exist_ok=True)
        (Path(env_dir) / "pyvenv.cfg").write_text("home = /fake\n", encoding="utf-8")
        self.created.append(env_dir)
 
 
@pytest.fixture(autouse=True)
def _stub_envbuilder(monkeypatch: pytest.MonkeyPatch):
    """Swap in the fake EnvBuilder for every test in this module."""
    _FakeEnvBuilder.instances = []
    monkeypatch.setattr(_scaffold_mod.venv, "EnvBuilder", _FakeEnvBuilder)
    yield
 
 
def test_include_venv_true_creates_venv(tmp_path: Path):
    """FS-503: default include_venv=True materialises .venv/ at the project root."""
    result = run_scaffold("demo", tmp_path, include_venv=True)
    project = tmp_path / "demo"
    venv_dir = project / ".venv"
    assert venv_dir.is_dir()
    assert (venv_dir / "pyvenv.cfg").is_file()
    assert result.venv_path == venv_dir
    assert venv_dir in result.created
    assert len(_FakeEnvBuilder.instances) == 1
 
 
def test_include_venv_false_skips_venv(tmp_path: Path):
    """FS-503: include_venv=False produces no .venv/ and venv_path stays None."""
    result = run_scaffold("demo", tmp_path, include_venv=False)
    project = tmp_path / "demo"
    assert not (project / ".venv").exists()
    assert result.venv_path is None
    assert _FakeEnvBuilder.instances == []
 
 
def test_dry_run_true_never_creates_venv(tmp_path: Path):
    """FS-503: include_venv=True combined with dry_run=True must not touch disk."""
    result = run_scaffold("demo", tmp_path, dry_run=True, include_venv=True)
    project = tmp_path / "demo"
    assert not project.exists()
    assert result.venv_path is None
    assert _FakeEnvBuilder.instances == []
    assert any(".venv" in m and "DRY RUN" in m for m in result.messages)
 
 
def test_preexisting_venv_is_skipped(tmp_path: Path):
    """FS-503: a second run over an existing tree records .venv/ in skipped."""
    first = run_scaffold("demo", tmp_path, include_venv=True)
    assert first.venv_path is not None  # sanity
    second = run_scaffold("demo", tmp_path, include_venv=True)
    project = tmp_path / "demo"
    assert (project / ".venv") in second.skipped
    # The fake builder was only triggered on the first run.
    assert len(_FakeEnvBuilder.instances) == 1
    assert any("already exists" in m for m in second.messages)
 
 
def test_venv_creation_failure_downgrades_to_warning(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch,
):
    """FS-503: OSError from EnvBuilder must not abort scaffolding."""
 
    class _ExplodingBuilder:
        def __init__(self, **_: object) -> None:
            pass
 
        def create(self, env_dir: str) -> None:  # noqa: ARG002
            raise OSError("disk full")
 
    monkeypatch.setattr(_scaffold_mod.venv, "EnvBuilder", _ExplodingBuilder)
    result = run_scaffold("demo", tmp_path, include_venv=True)
    project = tmp_path / "demo"
    # Project is still scaffolded; only venv missing.
    assert (project / ".option_c" / "octrc.json").is_file()
    assert result.venv_path is None
    assert any("venv creation failed" in m for m in result.messages)
 
 
def test_result_is_scaffoldresult(tmp_path: Path):
    """Smoke: include_venv flag preserves the ScaffoldResult contract."""
    result = run_scaffold("demo", tmp_path, include_venv=True)
    assert isinstance(result, ScaffoldResult)
    assert isinstance(result.created, list)
    assert isinstance(result.skipped, list)
    assert isinstance(result.messages, list)