[FEATURE] UI Audio Logic Unit Tests (GUT):: Confirmation & Cancellation Triggering

[ikostan]

Sub-Issue 3: GUT Unit Testing Suite

Title: [FEATURE] UI Audio Logic Unit Tests (GUT)
Labels: testing

Description:
Create a comprehensive automated test suite using the GUT (Godot Unit Testing) plugin to verify that the hybrid UI audio framework correctly intercepts, routes, and suppresses input actions according to the updated design specifications.

The test suite is split into two specialized test files to explicitly isolate global navigation and cancellation behaviors from local pop-up confirmation sequences.

Test Architecture & Layout

1. Global Navigation & Escape Input Tests

• File: res://test/unit/test_nav_escape_sfx.gd
• Target under Test: Globals (globals.gd)
• Scope: Verifies global menu state detection, directional navigation ticks, horizontal slider exclusions, text field suppression gates, input echo mitigation, and global ui_cancel (Escape) interception.

2. Quit Game Dialog Confirmation Tests

• File: res://test/unit/test_quit_game_confirm_dialog_sfx.gd

• Target under Test: MainMenu (main_menu.gd)

• Scope: Verifies signal-driven routing for explicit confirmation selections (_on_quit_dialog_confirmed) , cancellation triggers (_on_quit_dialog_canceled), and flat button safety boundaries.

• Mocks: Utilize GUT's spy/double capabilities on AudioManager to intercept and assert calls made to AudioManager.play_sfx().

---

Code Review Requirements

• Standard menu buttons must not manually invoke AudioStreamPlayer.play() or AudioManager.play_sfx("ui_accept") to trigger action-map confirmations.
• Local theme-driven button audio hooks (such as hover or focus sounds configuration in the Godot Inspector) must remain entirely decoupled from the global action-map system.
• Confirmation audio execution pathways must remain completely centralized within their respective contextual scripts.

---

Verification & Automated Testing Criteria

Verification Criteria

Functional Manual Verification

• Keyboard Confirmation: Pressing ui_accept (Enter/Space) inside a modal popup (like QuitDialog) triggers ui_accept.wav completely and smoothly before the application exits or redirects.
• Gamepad Confirmation: Pressing a controller button mapped to ui_accept on a modal dialog choice triggers ui_accept.wav exactly once.
• Flat Button Protection: Pressing ui_accept while highlighting standard flat main menu or options menu buttons does not superimpose a global confirmation sound over the button's native theme audio.
• Keyboard Cancellation: Pressing ui_cancel (Escape) inside any valid menu panel layer or dialog box triggers ui_cancel.wav exactly once.
• Gamepad Cancellation: Pressing a controller button mapped to ui_cancel to close a submenu panel triggers ui_cancel.wav exactly once.
• Echo Mitigation: Holding down a bound keyboard key or gamepad button does not generate rapid, machine-gun repeating audio loops.
• LineEdit Gate: Typing or pressing Enter to submit data inside a focused text field box completely suppresses interface navigation/confirmation sound events.
• Slider Control Gate: Modifying values using horizontal directional inputs while a volume or difficulty Slider node has focus does not emit a global navigation tick sound.

Automated Testing Rules (GUT)

1. Specifications for test_nav_escape_sfx.gd

• Global Cancellation Test Case: Assert that simulating a ui_cancel input event when is_menu_context == true triggers a single call to AudioManager.play_sfx("ui_cancel").
• Global Out-of-Context Test Case: Assert that no interface audio streams (ui_cancel or navigation directional inputs) are triggered if input events occur while is_menu_context == false.
• Menu Context Exit Test Case: Assert that immediately after leaving a menu context, subsequent ui_cancel inputs do not trigger UI cancellation audio (verifies context state updates cleanly).
• Input Repeat Gate (Echo Mitigation): Assert that repeated InputEventAction instances explicitly flagged as echo == true completely bypass the audio framework, generating zero additional playback requests.
• Navigation Positive Test Case: Assert that when a standard focused interface component receives a directional input action (ui_up, ui_down), the system successfully triggers the internal navigation audio node exactly once.
• Single Dispatch Guarantee: Assert that a single discrete navigation input event produces exactly one audio trigger request, protecting against overlapping hooks between Globals and local scripts.
• Value-Editing Text Gate: Assert that when a LineEdit or TextEdit control node holds active focus owner status, global interface input audio triggers are completely suppressed.
• Slider Double-Audio Gate: Assert that when a Slider control node holds active focus owner status, horizontal input actions (ui_left and ui_right) are bypassed by the navigation audio framework to eliminate overlapping audio artifacts.
• Unrelated Action Integrity: Assert that unrelated input actions (e.g., weapon firing, pause toggles, or gameplay movement vectors) never trigger menu selection, navigation, or cancellation audio.

2. Specifications for test_quit_game_confirm_dialog_sfx.gd

• Dialog Confirmation Audio Test Case: Assert that calling the localized _on_quit_dialog_confirmed() sequence triggers a distinct call to AudioManager.play_sfx("ui_accept").
• Dialog Cancellation Audio Test Case: Assert that invoking _on_quit_dialog_canceled() triggers a distinct call to AudioManager.play_sfx("ui_cancel").
• Flat Button Anti-Trigger Protection: Assert that simulating a ui_accept action while a standard menu navigation button (such as StartButton or OptionsButton) has focus explicitly does not invoke the global AudioManager.play_sfx("ui_accept") confirmation chime, ensuring local theme-driven button audio behaves natively.