Mirrors/eepp
1
0
Fork 0
mirror of https://github.com/SpartanJ/eepp.git synced 2026-09-22 13:01:05 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
f200850941cb6ce13d6c331641ddfdaa130c635b
eepp/.agent/rules/unit-tests.md
Martín Lucas Golini 95d52cdbb3 eepp: 
- add reusable-buffer String::toUtf8() conversion
  - extract shared find-bar CSS into UIFindBarStyle
  - reuse the shared style from UIDocFindReplace

  ecode:
  - enable terminal find, next, and previous shortcuts
  - install terminal bindings after conflicting editor bindings are removed

  eterm:
  - add searchable terminal history with plain text, RegEx, and LuaPattern modes
  - support case-sensitive and whole-word matching across wrapped rows
  - debounce searches and avoid unnecessary string allocations
  - add an animated find bar with status and wrapped result navigation
  - expose find commands through configurable keybindings and the context menu
  - render and navigate search matches in terminal history
  - forward right-button releases when applications capture the mouse
  - fix UITabWidgetSplitter ownership during shutdown

  tests:
  - cover UTF-8 buffer reuse and terminal search behavior
  - verify wrapped lines, Unicode, pattern modes, invalid expressions, and navigation
  - verify SGR right-button release encoding

  tooling:
  - clarify the mandatory optimized build workflow for performance work
  - require direct release test execution before falling back to Xvfb
2026-09-10 00:57:56 -03:00

3.9 KiB
Raw Blame History

Unit Testing Requirements & Guidelines

This project relies on a comprehensive suite of unit tests to prevent regressions. You must ensure all existing tests pass after making modifications.

Running Tests

The test binary manages its own current working directory, so you can execute it from anywhere.

The required default workflow is:

  1. Build the release unit-test target.
  2. Run bin/unit_tests/eepp-unit_tests directly, without Xvfb.
  3. If sandbox restrictions prevent access to the host display, retry that same direct command with elevated permissions.
  4. Use Xvfb only after direct execution has failed outside the sandbox because no usable graphical display is available. Xvfb is the last fallback, not the default headless convenience path.

Do not infer that a session is headless merely because its first sandboxed command cannot connect to the display. A sandbox can hide or deny access to an otherwise usable host display.

  • Use the release test binary during normal development: When AddressSanitizer or other debug-only diagnostics are not required, build and run bin/unit_tests/eepp-unit_tests. The optimized release suite is substantially faster and is the required default for iterative testing. Use bin/unit_tests/eepp-unit_tests-debug only when investigating memory safety, assertions, or other behavior that specifically requires the debug configuration.
  • Default Execution on a Graphical Linux Desktop: Unit-test windows are created hidden, so run the release suite directly against the desktop: bin/unit_tests/eepp-unit_tests This keeps the windows invisible and unfocused while preserving hardware OpenGL acceleration. Confirm that the renderer log names the real GPU rather than llvmpipe when validating rendering behavior or performance.
  • Filtered Tests on a Graphical Linux Desktop: Use the same direct hardware-backed command for focused runs: bin/unit_tests/eepp-unit_tests --filter="FontRendering.*Offset*"
  • Last Fallback for Headless CI and Systems Confirmed to Lack a Usable Desktop Display: Keep projects/scripts/xvfb-run-eepp as the fallback when no desktop display is available: projects/scripts/xvfb-run-eepp bin/unit_tests/eepp-unit_tests The wrapper provides a race-safe isolated display at 1280x1024x24 and injects ASAN_OPTIONS=detect_leaks=0. Xvfb can use llvmpipe, so do not use wrapper timings to evaluate hardware-rendered performance.
  • Wrapper Fallback: If projects/scripts/xvfb-run-eepp itself fails before launching the test binary, report that failure and use: xvfb-run -a -s "-screen 0 1280x1024x24" bin/unit_tests/eepp-unit_tests Do not use plain xvfb-run as the first headless attempt.
  • Non-window Tests: Tests known not to create windows can run without selecting a video driver: bin/unit_tests/eepp-unit_tests --filter="NonWindowTest.*"
  • Filtering Tests: Use the --filter parameter to run specific tests (supports glob patterns). Keep the same harness as the full suite: direct execution on a graphical Linux desktop, or the wrapper in a genuinely headless environment.

Writing New Tests

Writing new tests is highly encouraged, but depends on the context of your changes:

  • Core Framework (eepp): If you add new logic, math, or framework-level features, you are expected to write unit tests for them.
  • Application/Tools (ecode): Application-level UI changes or tool integrations are often difficult to mock/test. Tests for these are optional and should only be added if practical to set up.

Testing Workflow:

  1. All tests are located in src/tests/unit_tests/.
  2. Before modifying code, run the existing tests most relevant to your change to ensure a baseline.
  3. For reference on how tests are structured in this project, review src/tests/unit_tests/fontrendering.cpp (the most complete set of text rendering tests).