eepp/.agent/rules/unit-tests.md

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.

• Standard Execution: bin/unit_tests/eepp-unit_tests-debug
• Linux & FreeBSD Execution (Required for Desktop Environments): Tests open ~50 individual windows. To prevent disrupting the desktop environment, run them in an isolated framebuffer using xvfb-run: ASAN_OPTIONS=detect_leaks=0 xvfb-run -a -s "-screen 0 1280x1024x24" bin/unit_tests/eepp-unit_tests-debug
• Filtering Tests: Use the --filter parameter to run specific tests (supports glob patterns). Example (runs all tests with "Offset" in the name): bin/unit_tests/eepp-unit_tests-debug --filter="FontRendering.*Offset*"

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).