Home /Modules/ballum/06-status-and-testing.md

06-status-and-testing.md

lib/ballum/tutorials/06-status-and-testing.md · 83 line(s) · markdown

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

CodeMeaningFirst response
0OKRecord success only after the call returns this status.
1Invalid argumentInspect IDs, ranges, null/empty values, and expected encodings.
2Backend unavailableCheck backend compilation, selection, session type, and host support.
3Backend errorPreserve diagnostic context and investigate the native layer.
4Display not foundRe-enumerate and verify the display ID.
5Out of boundsRecheck dimensions and coordinate arithmetic.
6Buffer too smallConfirm the required capacity and the actual supplied size.
7Unsupported capabilitySkip the feature or use a supported alternative.
8Permission deniedFollow the operating system's documented permission flow.
9Not initializedCheck initialization order and object lifetime.
100SLeeLa-side bridge requiredVerify 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

Expected result: invalid inputs are rejected consistently, without memory errors, out-of-range writes, or misleading success logs.

2. Environment and capability

Expected result: unsupported conditions are reported cleanly, and the program can continue or exit according to its documented policy.

3. Input polling

Expected result: polling terminates predictably, does not spin forever, and never reads event fields after a failed poll.

4. Integration

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.