Lesson 6 — Status Codes and Testing
Ballum uses explicit result codes so an application can distinguish invalid input from missing platform support or a native operation failure. The exact meaning of a code should come from the package source for the version being built. Preserve the returned status instead of collapsing every nonzero result into a generic “failed” message.
Common status codes
| Code | Meaning | First response |
|---|---|---|
| 0 | OK | Record success only after the call returns this status. |
| 1 | Invalid argument | Inspect IDs, ranges, null/empty values, and expected encodings. |
| 2 | Backend unavailable | Check backend compilation, selection, session type, and host support. |
| 3 | Backend error | Preserve diagnostic context and investigate the native layer. |
| 4 | Display not found | Re-enumerate and verify the display ID. |
| 5 | Out of bounds | Recheck dimensions and coordinate arithmetic. |
| 6 | Buffer too small | Confirm the required capacity and the actual supplied size. |
| 7 | Unsupported capability | Skip the feature or use a supported alternative. |
| 8 | Permission denied | Follow the operating system's documented permission flow. |
| 9 | Not initialized | Check initialization order and object lifetime. |
| 100 | SLeeLa-side bridge required | Verify that the program is using the real VM bridge rather than a model-only path. |
Use the package's status-name helper when available, but keep the numeric code in logs as well. A readable name is helpful for people; the number is useful for comparing reports across environments.
Test categories
A robust test suite includes positive cases, negative cases, environmental cases, and integration cases.
1. Input validation
- Valid and invalid display IDs.
- Zero or invalid dimensions if the API permits them to reach the boundary.
- Negative coordinates.
- Coordinates exactly equal to width or height.
- Values just below, at, and just above each documented control limit.
- Incorrect gamma scaling.
- Buffer sizes below the required amount.
Expected result: invalid inputs are rejected consistently, without memory errors, out-of-range writes, or misleading success logs.
2. Environment and capability
- No display or a headless CI runner.
- Display present but pixel operations unsupported.
- Control capability absent on one display and present on another.
- Backend unavailable or not compiled into the runtime.
- Permission denied by the operating system.
- Display removed or reconfigured between enumeration and operation, where this can be safely simulated.
Expected result: unsupported conditions are reported cleanly, and the program can continue or exit according to its documented policy.
3. Input polling
- No input event ready.
- One event.
- A burst of events.
- An error from the poll path.
- Maximum event limit reached.
- Unsupported platform/input backend.
Expected result: polling terminates predictably, does not spin forever, and never reads event fields after a failed poll.
4. Integration
- SLeeLa source compiles with the intended compiler version.
- The VM build includes the Ballum bridge.
- The native manager tests pass.
- The backend selected at runtime matches the target operating system.
- A live operation is verified on supported hardware, with permissions and settings documented.
Test layers are not interchangeable
A unit test of range validation does not prove a platform backend works. A native manager test does not prove the VM bridge is linked. A successful SLeeLa compile does not prove the operating system accepted a request. Keep separate results for compilation, unit tests, bridge integration, and real-device smoke tests.
The native manager test source is documented in the project as tests/test_ballum_manager.c; verify its current build instructions and test target before running it. Do not report tests as passing unless they were actually executed and their output inspected.
A useful bug report
Include the OS/version, compiler/runtime version, commit or build identifier, graphical/headless session, bridge/backend configuration, display geometry and capability mask, operation attempted, numeric status, readable status name, and a minimal reproduction. Exclude unnecessary personal input data.
Practice
Use 05-headless-safe.sleela to think through unavailable-host behavior, then review 02-safe-pixel.sleela for a negative bounds test. Confirm which tests you actually ran; label unexecuted tests as pending.
Checkpoint: explain the difference between backend unavailable, unsupported capability, permission denied, and a native backend error.