What does Kotest's `Arb<A>.orNull()` produce, and how would you use it to exercise a nullable API contract without swamping the run with nulls?

## Lifting a generator into nullable Kotlin's type system distinguishes `A` from `A?`, and so does Kotest's generator API. `Arb<A>.orNull()` returns an `Arb<A?>`: a generator that draws from the source generator most of the time and yields `null` the rest of the time. ```kotlin val maybeName: Arb<String?> = Arb.string(minSize = 1, maxSize = 20).orNull() ``` The frequency is controlled by the `nullProbability` parameter. The default is deliberately small — `null` should be visible early in a run without dominating it. Setting it to `0.0` gives you effectively no nulls (at which point you should just use the source generator), and setting it high makes the null path the main subject of the property. ## Why this is more than a convenience The null case is the archetypal cheap bug: a field that is optional in the schema, required in the code, and never exercised because every hand-written test fixture fills it in. Generating nullability puts that case into the run automatically, and — crucially — puts it into *combination* with other generated values. A property over a data class whose optional fields use `orNull` explores "note absent while quantity is at its maximum" and "both optional fields absent" without anyone writing those fixtures. It also composes: an `Arb<A?>` is an ordinary generator, so it can be mapped, constrained, or used as a field generator when building a larger value. That is why nullable-aware generators pay off most in data-class generation, where the number of null/non-null combinations grows combinatorially and hand-enumeration stops being practical. ## Choosing the probability Think about what the property is claiming. - **Null is a rare production case** and the property is mostly about the happy path: keep the probability low. You still get null coverage, but most iterations exercise real values. - **Null is the interesting case** — you are testing default substitution, a fallback, or an error message: raise the probability so a meaningful fraction of iterations exercise it. Better still, consider a dedicated property or example test for the null path where the assertion can be specific. - **Null must never occur** in the domain: do not use `orNull` at all. Generating a value your contract forbids and then asserting around it tests nothing useful. A subtlety worth stating: a low probability plus a low iteration count can mean zero nulls in a given run. If the null case genuinely must be covered every time, cover it with an example test as well — property generation gives you exploration, not a guarantee that a particular value was drawn. ## Assertions must handle both branches Because the generated type is `A?`, the property body sees a nullable value and Kotlin will force you to deal with it. Resist the temptation to `!!` it or to skip the iteration with an early return when it is null: both convert a generated case back into an untested one. Write the assertion so it states the true property for both branches — for example, "rendering never returns null", or "the output contains the note when present and the placeholder when absent". ```kotlin checkAll(Arb.string(1..20).orNull()) { note -> val rendered = render(note) if (note == null) rendered shouldContain "(no note)" else rendered shouldContain note } ``` If the property becomes an awkward two-branch conditional, that is often a hint that there are really two properties — one for present and one for absent — and splitting them makes both assertions sharper. ## Relationship to the rest of the generator surface `orNull` sits alongside the other domain-shaping tools: ranges and sizes constrain *which* values appear, `orNull` decides whether the absence of a value is in the domain at all. Together they are how a generator becomes an executable statement of the input contract: "a name of 1 to 20 alphanumeric characters, a quantity from 1 to 99, and an optional note". Reviewing generators with that sentence in mind is the fastest way to spot a property testing the wrong domain — including the very common case of a field that is nullable in the data class but was never generated as null.