Integration Testing Flow
Relevant source files
The following files were used as context for generating this wiki page:
The Integration Testing Flow automates the verification of the spike CLI tool by recording actual screen and audio sessions and performing mechanical validation of the resulting media files. It ensures that system audio capture, microphone track separation, and window-scoped recording function correctly within the macOS environment.
The testing suite uses a shell script to orchestrate multiple test scenarios, a helper Swift application to generate predictable audio signals, and the spike inspect command to analyze output file metadata, including Root Mean Square (RMS) levels and track counts.
Sources: scripts/integration-test.sh:1-12, README.md
Test Orchestration and Environment
The integration-test.sh script manages the lifecycle of the testing process. It builds the project, prepares test assets, executes recording commands, and cleans up temporary directories and system configurations.
Key Components
| Component | Description |
|---|---|
spike | The main CLI tool being tested, located in .build/debug/spike. |
soundapp | A minimal Swift application that plays a loop of audio to a specific window title (SpikeSoundWindow) for scope testing. |
VOICE | An AIFF audio file generated via the say command used as a test signal. |
inspect | A subcommand of spike that outputs track presence, duration, and audio levels (RMS/Peak). |
Sources: scripts/integration-test.sh:17-25, scripts/soundapp.swift:1-15, Sources/Spike/InspectCmd.swift:7-11
Execution Flow
The following diagram illustrates the high-level execution flow of the integration test suite.
The script uses a trap on EXIT to ensure the cleanup function restores the system's default audio output if the monitor setup was active and terminates any background processes like soundapp.
Sources: scripts/integration-test.sh:27-41, scripts/integration-test.sh:84-100
Validation Logic
Verification relies on mechanical analysis of the recorded .mov or .m4a files. The script extracts specific fields from the spike inspect output to determine if a test passed.
Analysis Metrics
- RMS Threshold: Audio capture is considered successful if the Root Mean Square (RMS) value is above
0.005. - Track Counting: Commands like
rec-system --micare validated by checking if the number of audio tracks (audio[n]) is at least 2. - Window Scoping: Validated by ensuring the RMS is near zero (e.g.,
< 0.00005) when recording a window that is not producing sound, even if other system sounds are playing.
Sources: scripts/integration-test.sh:56-78, Sources/Spike/InspectCmd.swift:35-50
Test Scenarios
The suite covers various functional areas of the recording engine, defined as numbered tests (T1 to T10).
Core Recording Tests
- System Recording (T3): Verifies that
rec-systemcaptures both video and system audio. - Dual Track Recording (T4): Verifies that adding the
--micflag creates a second independent audio track. - Audio Only (T5): Ensures that
rec-audio-onlyproduces a file withvideo: absent. - Application Scoping (T6-T8): Uses
soundappto verify that audio is only captured from the target window/process when using the--matchflag.
Sources: scripts/integration-test.sh:113-178, Sources/Spike/RecWindowCmd.swift:12-25
Hardware and Loopback Tests
- BlackHole Loopback (T9): Tests the
monitor setupcommand which creates a "kilde Monitor" aggregate device. It sets this as the default output and records through theBlackHoleUID to verify audio loopback. - Signal Handling (T10): Sends a
SIGINT(Ctrl+C) to a running recording process. The test passes if the process exits with code 0 and the resulting file duration is within the expected range, proving theMovieWriterfinalized correctly.
Sources: scripts/integration-test.sh:182-205, Sources/Spike/MonitorCmd.swift:49-65, Sources/Spike/Util.swift:68-79
Implementation Details
The validation is supported by the MovieWriter and InspectCmd classes within the spike tool.
MovieWritertracks appended and dropped samples for both video and audio, providing a report used during the final stages of the recording command.analyzeAudioTrack(inUtil.swift) decodes the recorded file back to Linear PCM to calculate the exact RMS and Peak levels.
Sources: Sources/Spike/MovieWriter.swift:157-176, Sources/Spike/Util.swift:105-132
The integration testing flow ensures the reliability of the kilde recording engine by simulating real-world usage and programmatically verifying that media tracks are synchronized and contain valid data.