automaton/tasks/complete/runnable-test-suite/subtasks/vram-detect-cross-platform-tests/SPEC.md

# SPEC — vram-detect-cross-platform-tests

Parent: `runnable-test-suite` (see PARENT_SPEC.md).

**Dependency:** This sub-task runs AFTER `vram-detect-cross-platform` is complete.
Its function signatures and detection logic are the contract you test against.

## Scope

pytest tests proving cross-platform branches of `scripts/vram_detect.py` work
WITHOUT hitting real hardware. Every `subprocess.run` / `Path.exists` / `sysctl`
call is mocked.

## Files this sub-task touches (and ONLY this)

- `tests/test_vram_detect.py` — extend or rewrite. Preserve any existing
  passing test (Linux regression tests especially).

## MUST NOT touch

- `scripts/vram_detect.py` (if it has a bug, escalate back to Orchestrator —
  subtask-2 owns it)
- Any documentation, prompt, install script, or other source file
- Any other test file

## Test patterns (parametrize + monkeypatch)

### 1. `test_detect_ram_linux` (regression — must already be there, keep it)
- Patches `Path("/proc/meminfo")` text with synthetic `MemTotal: 16384000 kB\nMemAvailable: 8192000 kB`.
- Asserts `(16_384_000, 8_192_000)` returned.

### 2. `test_detect_ram_macos`
- `monkeypatch.setattr(platform, "system", lambda: "Darwin")`.
- Patches `subprocess.run` so `sysctl -n hw.memsize` returns `"34359738368"` (32GB).
- Asserts total_kb correct (33_554_432), available == total.

### 3. `test_detect_ram_windows`
- `monkeypatch.setattr(platform, "system", lambda: "Windows")`.
- Patches subprocess to return wmic output `TotalPhysicalMemory=34359738368`.
- Asserts total_kb == 33_554_432.

### 4. `test_detect_gpu_vram_nvidia_linux`
- `monkeypatch.setattr(platform, "system", lambda: "Linux")`.
- Patches `nvidia-smi` output `"24576\n"`.
- Asserts `(25_165_824, 25_165_824, 1)` (24GB × 1024 = KB).

### 5. `test_detect_gpu_vram_apple_silicon`
- `monkeypatch.setattr(platform, "system", lambda: "Darwin")`.
- Patches `system_profiler SPDisplaysDataType` with a real Apple M-series snippet:
  ```
  Graphics/Displays:
      Apple M2:
        Chipset Model: Apple M2
        Type: GPU
        Bus: Built-In
        Total Number of Cores: 10
        Vendor: Apple (0x106b)
        Metal: Supported, version 2
  ```
- Patches `sysctl -n hw.memsize` with `"17179869184"` (16GB).
- Asserts gpu_vram_kb > 0, num_gpus >= 1.

### 6. `test_detect_gpu_vram_windows_wmic`
- `monkeypatch.setattr(platform, "system", lambda: "Windows")`.
- Patches wmic output:
  ```
  AdapterRAM=8589934592
  Name=NVIDIA GeForce RTX 3060
  ```
- Asserts total_vram_kb == 8_388_608 (8GB).

### 7. `test_lookup_model_context_unknown_returns_zero`
- `_lookup_model_context("completely-unknown-model")` returns `0`.

### 8. `test_lookup_model_context_prefix_match`
- `_lookup_model_context("deepseek-r1:7b")` matches `deepseek-r1` entry and returns its context.
- `_lookup_model_context("llama-3.1-8b-instruct")` matches `llama-3.1-8b`.

### 9. `test_detect_model_context_ollama_probe`
- No config file specifies a model.
- `ollama list` is on PATH (patch `shutil.which`).
- Patches subprocess to return:
  ```
  NAME           ID     SIZE    MODIFIED
  llama-3.1-8b   abc    4.7GB   2 days ago
  ```
- Asserts the returned context matches the `llama-3.1-8b` entry.

### 10. `test_run_command_windows_powershell_wrapper`
- Show that on Windows, a PowerShell cmdlet invocation goes through
  `powershell -NoProfile -NoLogo -Command "..."` (assert argv[0] is powershell
  when cmd is a PS string).

### 11. `test_detect_ram_linux_regression` (LOCKED — do not modify)
- If this test already exists, keep its byte-for-byte assertions. If not, add
  an exact match on `(total_kb, available_kb)` for a specific `/proc/meminfo`
  fixture to prevent subtask-2 from regressing Linux output.

## Acceptance criteria

1. `python3 -m pytest tests/test_vram_detect.py -v` exits 0 with all new tests passing.
2. Total `python3 -m pytest tests/ -v` still exits 0.
3. **Streak:** 10 consecutive clean `python3 -m pytest tests/ -v` runs.
4. No live `subprocess` against real `system_profiler`/`nvidia-smi`/`wmic` — every
   external call goes through `monkeypatch.setattr`.
5. Every new test runs < 500ms (mock only, no I/O).

## Anti-spin rails

- If a subtask-2 function signature doesn't support what a test needs, STOP and
  report. Do not edit `vram_detect.py` yourself and do not weaken the test to fit.
  Escalate via Orchestrator.
- No `pytest.mark.skip` unless the platform genuinely doesn't support the feature
  (e.g. skip a Windows test on Linux only if it can't be mocked — but mocking is
  the whole point, so this should never happen).
- Do not add `pytest-cov` or any new deps.

## Recommended approach

1. Read `scripts/vram_detect.py` and confirm subtask-2's signatures.
2. For each test, write the fixture data as a module-level constant (multiline string).
3. Use `monkeypatch.setattr` for `platform.system`, `subprocess.run`, `shutil.which`,
   `Path.exists`, `Path.read_text`. Never call the real thing.
4. Use `capfd` for stdout assertions where the SPEC calls for print messages.
5. Run `python3 -m pytest tests/test_vram_detect.py -v` until green.
6. Run the full suite streak verifier.