Write an example once, use it three ways

One trustworthy example

A case contains inputs, an expected result, a name, and an optional description. Generated docstrings, mock matching, and implementation checks use that same case.

Because the example lives at the top of the function, reviewers can inspect behavior and implementation together.

Three operating modes

The safe default is production. From Python, prefer configure(mode=Mode.TEST), Mode.MOCK, or Mode.PRODUCTION for completion and type checking. String modes remain supported for compatibility and brevity. Choose test or mock before importing the target module.

• mock: return a fixed value when given exactly matches the call
• test: call the real function and compare its result
• production (default): pass through the decorator and skip the specification block

Relationship with pytest

niltest is for nearby representative examples. Continue to use pytest for broad boundary coverage, fixtures, integration tests, and detailed exception assertions.