TESTING.md

Regression coverage

Run the baseline suite from the project root:

python -m pip install -r requirements/dev.txt
python -m unittest discover -s tests -v
node tests/gui-state.cjs

For optional analysis and feedback unit tests:

python -m pip install -r requirements/analysis.txt -r requirements/audit.txt
python -m unittest discover -s tests -v

Use the project's .venv/bin/python or .venv\Scripts\python.exe as appropriate. The GitHub Actions matrix runs the baseline suite on Linux and Windows with Python 3.10, 3.12, 3.13 and 3.14. Optional real-emulator tests require VICE and BITSQUEEZER_TEST_VICE=1 and remain explicitly opt-in.

macOS is unsupported and excluded from CI. All eight supported combinations retain their existing test commands and failure handling. Tests that simulate platform-specific paths do not establish native macOS support. See platform support.

Component/unit	Tests and behavior covered
paths, project_version, command wrappers	test_layout, test_launcher: imports from src, shared resource root, VERSION, CLI help/version, caller directory, spaces, fresh setup and reuse
audio_pipeline	test_audio, test_filters: resampling, packing, sample counts, silence, EQ response, normalization, clipping, input validation and metadata
output_naming, GUI naming settings	test_output_naming: safe Unicode prefixes, all export formats, remembered A/B setting, upload basenames after restart, denied writes, HTTP authentication, comparison path collisions, valid PCM/VICE report references and identical audio bytes in both naming modes
capacity	test_audio, test_layout: payload capacity, odd padding, duration and resource lookup
prg_export, makeprg	test_audio, test_player, test_launcher, test_legacy: exact assets, timing, memory boundaries, overflow, CLI and legacy behavior
cart_export, makecart	test_audio, test_filters, test_launcher: CRT packet layout, bank limits, preserved diagnostics and optional cartconv errors
dependencies, environment_setup	test_gui_dependencies, test_install_all: isolated native import/runtime/version probes, missing tools, consent/noninteractive behavior, all-package coverage, install/recheck failures, no GUI on installer-only runs, HTTP capability enforcement and wrapper forwarding
launcher	test_launcher, test_windows_setup: virtual environment lifecycle, pins, failure status, configured Python/tools, optional tools and GUI recovery
runtime_config	test_windows_setup, test_launcher, test_components: platform/INI validation, executable paths, fallback discovery and log locations
windows_setup	test_windows_setup: Python/pip/audio checks, INI comments, backups, incomplete tools, missing installer and noninteractive behavior
Windows wrappers/runtime	test_windows_setup: native Windows command dispatch before Python is available, foreign caller directory and redirected input
Windows VICE detection/reuse	test_windows_vice: silent successful Windows version response, sibling identity, unrelated banners, crashes/timeouts, WinGet user/machine locations, stale PATH, coexisting editions, explicit overrides, partial installs, portable verification and no duplicate downloads
optional_tools	test_launcher, test_components: found/missing status, decline, ZIP path safety and optional dependency guidance
preview	test_preview, test_workbench: full-track/excerpt mapping, source/converted timing, PCM and VICE readiness
multipass	test_workbench: aliases and baseline selection with analysis dependencies; optional dependency failures retained
sid_feedback	test_components, test_preview: sample verification, mismatch/truncation and optional actual-emulator continuity checks
analysis.audit_tones	test_feedback_progress, test_components: trace parsing, capture progress, process timeout/reaping, diagnostic preservation and sample verification
analysis.profile_audio_loss	test_loss_profiler: alignment, polarity, gains, known band removal, noise coherence, silence and PCM scaling
gui.server	test_workbench, test_output_directory: actual HTTP upload/load/render, session/origin checks, disconnects, subprocess cleanup, save locations and restart preferences
gui.storage	test_storage, test_components: create missing folders, unreadable/unwritable paths, blocked paths, root fallback, flat-source compatibility and preferences failures
gui.desktop_paths	test_output_directory, test_components: file-manager invocation, paths with spaces and missing-folder/desktop errors; no Tkinter chooser
GUI HTML/JavaScript	gui-state.cjs: both drop areas, source loading, concurrent actions, playback/render states, completion visibility, local folder link/errors, stale responses, naming settings save/cancel/failure, folder navigation directory warnings and unavailable-feature controls
scripts/sort-layout.py	test_layout: dry run, archive checksums/traversal, symlinks, missing replacements, backups, local edits, checkpoint notes, idempotence and rollback after write failure
scripts/release.sh	test_release: local disposable Git/gh fixtures verify staging, generated-log exclusion, archive and release orchestration

The test map describes behavior exercised, not a guarantee that every possible platform interaction has been tested. Native browser appearance/desktop drag interaction, real WinGet installation and the actual VICE opt-in tests require the corresponding runtime. Specific checkpoint results are in the release notes.