conftest.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/tests_core/conftest.py
 
"""
Purpose
-------
Provide shared fixtures for ``oct.core`` tests, in particular the git
integration tests in ``test_git.py`` (Phase 4A / G-A6).
 
Responsibilities
----------------
- ``git_repo``: initialise a real git repository in a pytest tmp_path
  and return its resolved path. Skips the test if the ``git`` binary is
  not available on the host.
- ``can_symlink``: cached session-scoped probe that determines whether
  the platform allows creating symlinks in a temp directory (Linux/
  macOS always, Windows only with Developer Mode or admin).
 
Diagnostics
-----------
Domain: CORE-TESTS
Levels:
    L2 — fixture lifecycle
    L3 — fixture setup details
    L4 — deep tracing
 
Contracts
---------
- ``git_repo`` always returns a directory that is a real git working
  tree with ``user.name`` / ``user.email`` pre-configured so that
  commit operations in tests do not fail on unconfigured identity.
- ``can_symlink`` must never raise; it returns ``True`` or ``False``.
"""
 
import os
import shutil
import subprocess
from pathlib import Path
 
import pytest
 
 
@pytest.fixture(scope="session")
def can_symlink(tmp_path_factory) -> bool:
    """Session-cached probe: True if symlink creation works on this host."""
    probe_dir = tmp_path_factory.mktemp("symlink_probe")
    target = probe_dir / "target.txt"
    link = probe_dir / "link.txt"
    target.write_text("x", encoding="utf-8")
    try:
        os.symlink(target, link)
    except (OSError, NotImplementedError):
        return False
    return link.exists()
 
 
def _git_available() -> bool:
    return shutil.which("git") is not None
 
 
@pytest.fixture
def git_repo(tmp_path: Path) -> Path:
    """Initialise a real git repo in tmp_path; skip if git is missing."""
    if not _git_available():
        pytest.skip("git binary not available on PATH")
    repo = tmp_path / "repo"
    repo.mkdir()
    subprocess.run(
        ["git", "init", "--quiet", "-b", "main"],
        cwd=repo, check=True, capture_output=True, text=True,
    )
    subprocess.run(
        ["git", "config", "user.email", "test@example.com"],
        cwd=repo, check=True, capture_output=True, text=True,
    )
    subprocess.run(
        ["git", "config", "user.name", "Test"],
        cwd=repo, check=True, capture_output=True, text=True,
    )
    subprocess.run(
        ["git", "config", "commit.gpgsign", "false"],
        cwd=repo, check=True, capture_output=True, text=True,
    )
    return repo.resolve()
 
 
def commit_file(repo: Path, name: str, content: str, message: str) -> None:
    """Helper: write a file, stage it, commit it. Used by several tests."""
    (repo / name).write_text(content, encoding="utf-8")
    subprocess.run(
        ["git", "add", name],
        cwd=repo, check=True, capture_output=True, text=True,
    )
    subprocess.run(
        ["git", "commit", "-m", message, "--quiet"],
        cwd=repo, check=True, capture_output=True, text=True,
    )