Nightshift: test-gap analysis — Microck/veyoff

Task: test-gap
Category: analysis
Repo: Microck/veyoff
Date: 2026-04-20

Summary

Veyoff has zero automated tests for its Python module (src/veyoff/) and no test infrastructure for the C++ Windows binary (src/windows/veyoff-windows.cpp). The CI workflow (.github/workflows/build.yml) only compiles the C++ binary — no test step exists.

Codebase Overview

Findings

P1 — Python module has zero test coverage

Severity: P1 (High)
Files: src/veyoff/{main,filter,overlay,hotkey,capture,daemon}.py

The Python module contains well-structured, testable code with clear separation of concerns:

• filter.py — blacklist loading, window enumeration, blackout rendering
• hotkey.py — FreezeController state machine, HotkeyManager
• capture.py — ScreenCapture with caching
• overlay.py — TCP connection parsing, master detection
• main.py — capture loop orchestration

These modules use dependency injection and have pure functions that are straightforward to unit test.

Missing tests for:

1. filter.load_blacklist() — empty file, missing file, comments, whitespace handling
2. filter.title_matches_blacklist() — case-insensitive matching, partial matches
3. filter.find_blacklisted_windows() — filtering with empty/full blacklist
4. overlay._parse_ss_output() — TCP connection parsing (already has structured output)
5. overlay.detect_master_connection() — port matching logic with mock connections
6. hotkey.FreezeController — freeze/unfreeze/toggle state transitions
7. capture.ScreenCapture — cached frame behavior when frozen vs live
8. main._status_from_state() — all 4 state combinations

Recommendation: Add tests/ directory with pytest. Start with filter.py and hotkey.py (purest logic, no OS dependencies). Use pytest-mock for Xlib/PIL/mss mocking.

P2 — CI pipeline has no test step

Severity: P2 (Medium)
File: .github/workflows/build.yml

The build workflow compiles the C++ binary and uploads it as an artifact, but never runs tests. There's no test job or step.

Recommendation: Add a test step after the build step. For Python: pip install pytest && pytest. For C++: add a test target in CMakeLists.txt.

P2 — No test files exist anywhere in the repo

Severity: P2 (Medium)
Path: (entire repo)

There are no test_*.py, *_test.py, *_test.cpp, or *Tests/* directories. No test framework is configured in CMakeLists.txt (no gtest or Catch2). No pytest.ini, pyproject.toml test config, or setup.cfg test runner.

Recommendation: Set up pytest for Python with pyproject.toml [tool.pytest.ini_options]. Consider Catch2 or doctest for C++.

P3 — Python module functions are testable despite OS dependencies

Severity: P3 (Low)
Files: src/veyoff/filter.py, src/veyoff/overlay.py

Good news: the code is well-structured for testing:

• _parse_ss_output() accepts raw string output (easy to test with fixtures)
• detect_master_connection() accepts an optional connections parameter (mockable)
• WindowFilter loads from file path (testable with temp files)
• FreezeController is a pure state machine (no I/O)

The code already uses pragma: no cover comments, suggesting testing was planned but not implemented.

Recommendation: Leverage the existing dependency injection patterns. No refactoring needed to start testing.

P3 — C++ binary lacks test hooks

Severity: P3 (Low)
File: src/windows/veyoff-windows.cpp

The 2,300-line C++ file is a monolithic Windows application with deeply coupled Win32 API calls. It cannot be tested on Linux CI runners. Testing would require:

1. Extracting pure logic into separate translation units
2. Adding a test harness with mocked Win32 APIs
3. Running on windows-latest runners

Recommendation: Low priority given Windows-only nature. Focus on Python tests first. Consider extracting RFB protocol handling into a testable class.

Recommended Test Implementation Plan

Estimated total: ~60 tests, 15-20 hours of implementation.