Testing and Reporting Issues¶
Found a bug? This page explains how to report it so it gets fixed, and how to define a test case that prevents it from coming back silently.
Reporting a bug¶
Follow the MoonModules issue reporting guide for the full checklist. The short version:
- Describe what you expected and what you actually saw.
- Include the device and firmware version (visible in the SystemStatus module or
GET /api/system). - Include steps to reproduce — the more specific, the faster it gets fixed.
- Open an issue at github.com/ewowi/projectMM/issues.
A good issue title names the module and the symptom, for example:
"BrightnessModifier: setting brightness to 0 in the UI still shows dim pixels"
Turning your bug into a test¶
The most useful thing you can add alongside a bug report is a description of the exact check that would have caught it. Developers can then write a test that:
- fails against the broken code, confirming the bug is real
- passes after the fix, confirming the fix is correct
- stays in the suite forever, preventing the bug from silently reappearing
You do not need to write C++ yourself. Describe the scenario in plain language inside your issue.
Example: BrightnessModifier pixel output¶
User question: "When testing the BrightnessModifier module, is there a test that actually checks that the raw bytes being sent vary with the brightness setting?"
Answer: Yes. The test "BrightnessModifierModule - loop() output scales with brightness from KvStore" in tests/test_brightness_mod.cpp does exactly this:
- It sets
brightness = 0in the shared KvStore, runs one loop tick, and checks that every RGB pixel byte in the output buffer is0(black). - It then sets
brightness = 1.0, runs one loop tick, and checks that every pixel byte is approximately127(mid-scale).
If someone accidentally broke the brightness scaling (for example, by always multiplying by 1 instead of reading KvStore), this test would catch it.
If the test did not exist and you found this bug: a good issue description would be:
"Steps to reproduce: add a BrightnessModifier, set it to 0 in the UI, the preview still shows light output. Expected: all pixels dark."
"Test I would expect: set brightness=0 in KvStore, call loop(), check that every pixel R/G/B byte is 0."
That description is enough for a developer to write the regression test. See the developer testing guide for the C++ implementation.
What makes a useful test description¶
When filing an issue that includes a test scenario, include:
| Field | Example |
|---|---|
| Module under test | BrightnessModifierModule |
| Input state | brightness = 0.0 via KvStore; frequency = 0 |
| Action | call loop() once |
| Expected output | every Channel::pixels[i].r/g/b == 0 |
| What was actually observed | pixels were approximately 127 (mid-scale) |
The more precise the "expected output" and "actual output", the faster the test can be written and the bug fixed.
Types of checks¶
You do not need to know C++ to describe a check at the right level. Here are the four levels used in this project, with plain-language descriptions:
| Level | Plain description | Example |
|---|---|---|
| Smoke | "the module does not crash when I add it and tick it once" | TasksModule loads without error |
| Format | "the control panel shows a 'brightness' slider" (schema shape check) | BrightnessModifier has a frequency control in its schema |
| Behavioral | "when I set brightness to 0, the output is black" (output value check) | the raw pixel bytes are 0 when brightness=0 |
| Integration | "when SineEffect is wired into BrightnessModifier, the brightness follows the sine amplitude" (pipeline check) | full effect-to-modifier pipeline produces expected pixel values |
Most bug reports fall into the behavioral or integration category — the ones that actually verify the output, not just that the UI renders.
After the fix¶
Once a fix is merged, check docs/status/test-results.md to confirm the new test case appears in the suite and passes. The test count and per-module breakdown are updated automatically on every build.
If you want to follow up on an issue or verify a fix on your own device, see Getting Started for build and flash instructions.