Smoke Tests
Run these tests after installing a new build to verify core functionality. Each test lives in its own file under docs/smoke_tests/ so you can read and review one feature at a time without scrolling through the whole catalogue.
For automated regression testing, use the /regression-test skill, which covers unit tests, CLI commands, config validation, and binary variant verification.
Core
| Test | What it covers |
|---|---|
| Basic Verification | --version, --help, daemon startup, and config defaults |
| Recording Cycle | Idle to Recording to Transcribing to Outputting state transitions |
| Service Restart Cycle | systemctl --user restart voxtype leaves the daemon in a healthy state |
| Single Instance Enforcement | A second voxtype daemon invocation refuses to start |
| Signal Handling | SIGTERM and SIGINT shut the daemon down cleanly |
| Config Validation | Invalid config produces a useful error, not a panic |
CLI and file I/O
| Test | What it covers |
|---|---|
| CLI Overrides | --model, --engine, --device, and other per-invocation flags |
| File Output | --file, append vs overwrite, config-based paths, directory creation |
| Transcribe Command | voxtype transcribe <wav> for offline file transcription |
Recording behaviour
| Test | What it covers |
|---|---|
| Smart Auto-Submit | Auto-stop on silence, CLI/env/config layering, negative cases |
| Rapid Successive Recordings | Back-to-back recordings don't leak state |
| Long Recording | Multi-minute recordings transcribe cleanly without OOM |
Voice activity detection
| Test | What it covers |
|---|---|
| Voice Activity Detection | Energy VAD, Whisper VAD, auto selection, threshold tuning, transcribe-command integration |
Engines and models
| Test | What it covers |
|---|---|
| Multi-Engine Transcription | Quick smoke per engine, daemon integration, error handling, perf comparison |
| Model Switching | Swap models at runtime without restarting the daemon |
| Engine Switching via Model Selection | Picking a model from another engine flips the engine automatically |
| Multilingual Model Verification | Non-English models load and transcribe |
| Invalid Model Rejection | Bogus model names fail loudly with a remediation hint |
| Whisper CLI Backend | Out-of-process Whisper via subprocess |
| Parakeet with Preloaded Model | Eager preload removes load latency on first recording |
| Parakeet Backend Switching | Switching between Parakeet variants at runtime |
| Remote Transcription | OpenAI-compatible HTTP backend |
| On-Demand Model Loading | Lazy load reduces idle memory; load latency hides behind recording |
| Eager Processing | Eager preload paths warm caches before the first recording |
GPU
| Test | What it covers |
|---|---|
| GPU Isolation Mode | gpu_isolation = true releases VRAM after each transcription |
| GPU Backend Switching | Switching between CUDA, Vulkan, and CPU at runtime |
| Multi-GPU Selection | CUDA_VISIBLE_DEVICES and explicit device pinning |
Output
| Test | What it covers |
|---|---|
| Output Drivers | wtype, dotool, ydotool, clipboard selection |
| dotool Fallback | dotool path probes and falls back when uinput is unavailable |
| dotool Keyboard Layout | DOTOOL_XKB_LAYOUT handles non-US layouts |
| ydotool Fallback | ydotool path probes and falls back when the daemon is missing |
| X11 Session Clipboard | xclip/xsel clipboard output on X11 |
| Output Chain Verification | Full fallback chain wtype, dotool, ydotool, clipboard |
| Delay Options | --delay and per-driver inter-keystroke delays |
| Post-Processing Command | LLM cleanup command runs on the transcript before output |
Integrations
| Test | What it covers |
|---|---|
| Audio Feedback | Start, stop, and completion cues play through the configured device |
| Compositor Hooks | voxtype record start/stop/toggle from Hyprland, Sway, River |
| Waybar JSON Output | voxtype status --follow emits valid JSON for Waybar |
Meeting mode
| Test | What it covers |
|---|---|
| Meeting Mode | Lifecycle, list, show, export, delete, speaker labels, AI summary, error handling, dual audio, diarization backends |
v0.7.6 release verification
Tests for bug fixes and tweaks introduced in v0.7.6.
| Test | Issue |
|---|---|
| TUI Audio/VAD float serialization | #451 |
| Engine vs binary mismatch detection | #450 |
| Setup retry-hint | #449 |
| Streaming + non-streaming model fail-fast | #442 |
| Model downloads via Cloudflare R2 | (CDN rollout) |
v0.6.6 release verification
Tests for bug fixes and enhancements introduced in v0.6.6.
Quick reference
| Test | What it covers |
|---|---|
| Quick Smoke Test Script | A compressed script that hits the most-broken-things-first paths |
Adding a new test
Drop a new file under docs/smoke_tests/ (or docs/smoke_tests/<release>/ for release-themed verification batches) and add a row to the appropriate table above. Each file is its own document: open with an # H1 heading, then the test body. There's no enforced template, but most tests follow the same shape: a one-line description, unit-test commands if there are any, a structural grep with expected counts, then a runtime checklist with "Expected:" lines.