From e840d71add89d587f4548c99ae8c3fa797706c03 Mon Sep 17 00:00:00 2001 From: scawful Date: Sat, 4 Oct 2025 14:10:37 -0400 Subject: [PATCH] feat: Add End-to-End (E2E) testing documentation for improved test management - Introduced a comprehensive README for the E2E tests using ImGui Test Engine, detailing active tests and their functionalities. - Documented the process for running tests, creating new tests, and utilizing the ImGui Test Engine API. - Included troubleshooting tips and future test ideas to enhance test development and execution. - Organized the file structure and provided insights into test logging and infrastructure. --- test/e2e/README.md | 176 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 test/e2e/README.md diff --git a/test/e2e/README.md b/test/e2e/README.md new file mode 100644 index 00000000..8d0cf4da --- /dev/null +++ b/test/e2e/README.md @@ -0,0 +1,176 @@ +# End-to-End (E2E) Tests + +This directory contains E2E tests using ImGui Test Engine to validate complete user workflows. + +## Active Tests + +### ✅ Working Tests + +1. **framework_smoke_test.cc** - Basic framework validation +2. **canvas_selection_test.cc** - Canvas selection and copy/paste workflow +3. **dungeon_editor_smoke_test.cc** - Dungeon editor UI navigation and interaction +4. **overworld/overworld_e2e_test.cc** - Overworld editor workflows +5. **rom_dependent/e2e_rom_test.cc** - ROM-dependent functionality tests +6. **zscustomoverworld/zscustomoverworld_upgrade_test.cc** - ZSCustomOverworld upgrade tests + +### 📝 Dungeon Editor Smoke Test + +**File**: `dungeon_editor_smoke_test.cc` +**Status**: ✅ Working and registered + +Tests complete dungeon editor workflow: +- ROM loading +- Editor window opening +- Room selection (0x00, 0x01, 0x02) +- Canvas interaction +- Tab navigation (Object Selector, Room Graphics, Object Editor, Entrances) +- Mode button verification (Select, Insert, Edit) +- Detailed logging at each step + +## Running Tests + +### All E2E Tests (GUI Mode) +```bash +./build/bin/yaze_test --show-gui +``` + +### Specific Test Category +```bash +./build/bin/yaze_test --show-gui --gtest_filter="E2ETest*" +``` + +### Dungeon Editor Test Only +```bash +./build/bin/yaze_test --show-gui --gtest_filter="*DungeonEditorSmokeTest" +``` + +## Test Development + +### Creating New Tests + +Follow the pattern in `dungeon_editor_smoke_test.cc`: + +```cpp +#include "e2e/my_new_test.h" +#include "test_utils.h" +#include "app/core/controller.h" + +void E2ETest_MyNewTest(ImGuiTestContext* ctx) { + // Load ROM + yaze::test::gui::LoadRomInTest(ctx, "zelda3.sfc"); + + // Open editor + yaze::test::gui::OpenEditorInTest(ctx, "My Editor"); + + // Test interactions with logging + ctx->LogInfo("Starting test..."); + ctx->WindowFocus("My Editor"); + ctx->ItemClick("MyButton"); + ctx->LogInfo("Test completed"); +} +``` + +### Register in yaze_test.cc + +```cpp +#include "e2e/my_new_test.h" + +// In RunGuiMode(): +ImGuiTest* my_test = IM_REGISTER_TEST(engine, "E2ETest", "MyNewTest"); +my_test->TestFunc = E2ETest_MyNewTest; +my_test->UserData = &controller; +``` + +### ImGui Test Engine API + +Key methods available: +- `ctx->WindowFocus("WindowName")` - Focus a window +- `ctx->SetRef("WindowName")` - Set reference window for relative queries +- `ctx->ItemClick("ButtonName")` - Click an item +- `ctx->ItemExists("ItemName")` - Check if item exists +- `ctx->LogInfo("message", ...)` - Log information +- `ctx->LogWarning("message", ...)` - Log warning +- `ctx->LogError("message", ...)` - Log error +- `ctx->Yield()` - Yield to allow UI to update + +Full API: `src/lib/imgui_test_engine/imgui_te_engine.h` + +## Test Logging + +Tests log detailed information during execution. View logs: +- In GUI mode: Check ImGui Test Engine window +- In CI mode: Check console output +- Look for lines starting with date/time stamps + +Example log output: +``` +2025-10-04 14:03:38 INFO: === Starting Dungeon Editor E2E Test === +2025-10-04 14:03:38 INFO: Loading ROM... +2025-10-04 14:03:38 INFO: ROM loaded successfully +2025-10-04 14:03:38 INFO: Opening Dungeon Editor... +``` + +## Test Infrastructure + +### File Organization +``` +test/e2e/ +├── README.md (this file) +├── framework_smoke_test.{cc,h} +├── canvas_selection_test.{cc,h} +├── dungeon_editor_smoke_test.{cc,h} ← Latest dungeon test +├── overworld/ +│ └── overworld_e2e_test.cc +├── rom_dependent/ +│ └── e2e_rom_test.cc +└── zscustomoverworld/ + └── zscustomoverworld_upgrade_test.cc +``` + +### Helper Functions + +Available in `test_utils.h`: +- `yaze::test::gui::LoadRomInTest(ctx, "zelda3.sfc")` - Load ROM for testing +- `yaze::test::gui::OpenEditorInTest(ctx, "Editor Name")` - Open an editor window + +## Future Test Ideas + +Potential tests to add: +- [ ] Object placement workflow +- [ ] Object property editing +- [ ] Layer visibility toggling +- [ ] Save workflow validation +- [ ] Sprite editor workflows +- [ ] Palette editor workflows +- [ ] Music editor workflows + +## Troubleshooting + +### Test Crashes in GUI Mode +- Ensure ROM exists at `assets/zelda3.sfc` +- Check logs for specific error messages +- Try running without `--show-gui` first + +### Tests Not Found +- Verify test is registered in `yaze_test.cc` +- Check that files are added to CMakeLists.txt +- Rebuild: `make -C build yaze_test` + +### ImGui Items Not Found +- Use `ctx->ItemExists("ItemName")` to check availability +- Ensure window is focused with `ctx->WindowFocus()` +- Check actual widget IDs in source code (look for `##` suffixes) + +## References + +- **ImGui Test Engine**: `src/lib/imgui_test_engine/` +- **Test Registration**: `test/yaze_test.cc` +- **Test Utilities**: `test/test_utils.h` +- **Working Examples**: See existing tests in this directory + +## Status + +**Current State**: E2E testing infrastructure is working with 6+ active tests. +**Test Coverage**: Basic workflows covered; opportunity for expansion. +**Stability**: Tests run reliably in both GUI and CI modes. +