A2-test-dashboard-refactoring

YAZE GUI Test Integration Refactoring Plan

Author: Gemini Date: 2025-10-11 Status: Proposed

1. Introduction & Motivation

The yaze application includes a valuable feature for developers: an in-application "Test Dashboard" that allows for viewing and running various test suites directly within the GUI. However, the current implementation, located primarily in src/app/test/, is tightly coupled with both the main application and the command-line test executables.

This tight coupling has led to several architectural and practical problems:

• Conditional Compilation Complexity: Excluding the test dashboard from release or CI/CD builds is difficult, as its code is intertwined with core application logic. This unnecessarily bloats release binaries with test code.
• Circular Dependencies: The yaze_test_support library, which contains the TestManager, links against nearly all other application libraries (yaze_editor, yaze_gui, etc.). When the main application also links against yaze_test_support to display the dashboard, it creates a confusing and potentially circular dependency graph that complicates the build process.
• Mixed Concerns: The current TestManager is responsible for both the core logic of running tests and the UI logic for displaying the dashboard. This violates the Single-Responsibility Principle and makes the code harder to maintain.

This document proposes a plan to refactor the test integration system into a modular, layered, and conditionally compiled architecture.

1. Goals
   • Decouple Test Infrastructure: Separate the core test framework from the test suites and the GUI dashboard.
   • Create an Optional Test Dashboard: Make the in-app test dashboard a compile-time feature that can be easily enabled for development builds and disabled for release builds.
   • Eliminate Complex Dependencies: Remove the need for the main application to link against the entire suite of test implementations, simplifying the build graph.
   • Improve Maintainability: Create a clean and logical structure for the test system that is easier to understand and extend.
2. Proposed Architecture

The test system will be decomposed into three distinct libraries, clearly separating the framework, the UI, and the tests themselves.

1 +--------------------------------------------------------------—+ 2 | Main Application ("yaze") | 3 | (Conditionally links against test_dashboard) | 4 +--------------------------------------------------------------—+ 5 | ^ 6 | Optionally depends on | 7 v | 8 +--------------—+ +--------------—+ +--------------—+ 9 | test_dashboard | --> | test_framework | <– | test_suites | 10 | (GUI Component) | | (Core Logic) | | (Test Cases) | 11 +--------------—+ +--------------—+ +--------------—+ 12 ^ ^ 13 | | 14 |----------------------------------------------—| 15 | 16 v 17 +--------------------------------------------------------------—+ 18 | Test Executables (yaze_test_stable, etc.) | 19 | (Link against test_framework and test_suites) | 20 +--------------------------------------------------------------—+

3.1. test_framework (New Core Library)

• Location: src/test/framework/
• Responsibility: Provides the core, non-GUI logic for managing and executing tests.
• Contents:
  • TestManager (core logic only: RunTests, RegisterTestSuite, GetLastResults, etc.).
  • TestSuite base class and related structs (TestResult, TestResults, etc.).
• Dependencies: yaze_util, absl. It will not depend on yaze_gui or any specific test suites.

3.2. test_suites (New Library)

• Location: src/test/suites/
• Responsibility: Contains all the actual test implementations.
• Contents:
  • E2ETestSuite, EmulatorTestSuite, IntegratedTestSuite, RomDependentTestSuite, ZSCustomOverworldTestSuite, Z3edAIAgentTestSuite.
• Dependencies: test_framework, and any yaze libraries required for testing (e.g., yaze_zelda3, yaze_gfx).

3.3. test_dashboard (New Conditional GUI Library)

• Location: src/app/gui/testing/
• Responsibility: Contains all ImGui code for the in-application test dashboard. This library will be conditionally compiled and linked.
• Contents:
  • A new TestDashboard class containing the DrawTestDashboard method (migrated from TestManager).
  • UI-specific logic for displaying results, configuring tests, and interacting with the TestManager.
• Dependencies: test_framework, yaze_gui.

Migration & Refactoring Plan

1. Create New Directory Structure:
   • Create src/test/framework/.
   • Create src/test/suites/.
   • Create src/app/gui/testing/.
2. Split TestManager:
   • Move test_manager.h and test_manager.cc to src/test/framework/.
   • Create a new TestDashboard class in src/app/gui/testing/test_dashboard.h/.cc.
   • Move the DrawTestDashboard method and all its UI-related helper functions from TestManager into the new TestDashboard class.
   • The TestDashboard will hold a reference to the TestManager singleton to access results and trigger test runs.
3. Relocate Test Suites:
   • Move all ..._test_suite.h files from src/app/test/ to the new src/test/suites/ directory.
   • Move z3ed_test_suite.cc to src/test/suites/.
4. Update CMake Configuration:
   • src/test/framework/CMakeLists.txt: Create this file to define the yaze_test_framework static library.
   • src/test/suites/CMakeLists.txt: Create this file to define the yaze_test_suites static library, linking it against yaze_test_framework and other necessary yaze libraries.
   • src/app/gui/testing/CMakeLists.txt: Create this file to define the yaze_test_dashboard static library.
   • Root CMakeLists.txt: Introduce a new option: option(YAZE_WITH_TEST_DASHBOARD "Build the in-application test dashboard" ON).
   • src/app/app.cmake: Modify the yaze executable's target_link_libraries to conditionally link yaze_test_dashboard based on the YAZE_WITH_TEST_DASHBOARD flag.
   • test/CMakeLists.txt: Update the test executables to link against yaze_test_framework and yaze_test_suites.
   • Remove src/app/test/test.cmake: The old yaze_test_support library will be completely replaced by this new structure.

Expected Outcomes

This plan will resolve the current architectural issues by:

• Enabling Clean Builds: Release and CI builds can set YAZE_WITH_TEST_DASHBOARD=OFF, which will prevent the test_dashboard and test_suites libraries from being compiled or linked into the final yaze executable, resulting in a smaller, cleaner binary.
• Simplifying Dependencies: The main application will no longer have a convoluted dependency on its own test suites. The dependency graph will be clear and acyclic.
• Improving Developer Experience: Developers can enable the dashboard for convenient in-app testing, while the core test infrastructure remains robust and decoupled for command-line execution.