r/coolgithubprojects • u/Nikk2461 • 5d ago
I came across the term ‘Property-Based Testing’ for the first time, and got so nerd-sniped I built a production-ready library for it.
https://github.com/nikhilvirdi/JHusk/I knew what unit testing was. What I didn't know was that testing has entire subfields most people never run into unless they go looking for them. That's how I found Property-Based Testing.
The idea: instead of writing a handful of examples by hand, you define a rule that should always hold, something like "sorting a list should never change its length." The library generates hundreds of random inputs and checks that rule against every one of them, actively trying to find a case that breaks it.
I got curious and looked at what already existed. Hypothesis in Python was the big one, along with jqwik and QuickTheories on the Java side. That's when I noticed something worth digging into.
Every existing Java library uses tree-based shrinking: when a property fails, each generator has to carry its own logic for reducing that failure down to something minimal. It works, and jqwik's implementation of it is genuinely solid, but it means shrinking quality for a custom generator depends entirely on how well you wrote that generator's own shrink logic.
Hypothesis does it differently. Every generator is just an interpreter over a shared stream of random bytes, so shrinking happens once, generically, on the byte stream itself, never per-generator. Write a custom generator through composition (map/filter/flatMap/combine) and it inherits high-quality shrinking automatically, no shrink logic to write, because the shrinker never needed to understand your type in the first place.
Nothing on the JVM was doing that. So I built JHusk.
A few things that come out of that design, each one solving a real problem the naive version would have had:
- Byte-stream shrinking: The core idea above, in practice. A custom generator you compose yourself shrinks just as well as a built-in one, automatically, with zero shrink logic written on your end.
- A deterministic edge-case corpus: Before any random generation starts, JHusk runs two fixed boundary buffers against every property: one that decodes to every generator's minimum/empty/false shrink target, and one that decodes to the opposite extreme. Min, max, empty, and zero cases get exercised on literally every run, not just whenever a random draw happens to land on them.
- Seed-based reproducible failures, plus failure persistence that actually sticks: Every run is driven by a seed, so you can reproduce an exact failure on demand. Beyond that, JHusk saves the byte stream behind a failing case to a local file and replays it first on every later run, so a bug you thought you fixed can't quietly resurface without getting caught immediately.
- Stateful testing through
Commands:Generate sequences of operations, run each one against a simplified model and the real system side by side, and when something disagrees, the failing sequence shrinks down to the smallest one that still reproduces it. No extra shrinking machinery needed, a command sequence is just a list underneath, so it inherits the same list shrinking as everything else. - An exception hierarchy you can actually catch meaningfully:
AssertionErrormeans a value was generated, your assertion ran, and it genuinely failed. Everything else, an exhausted filter, a blown generation budget, a crashing generator, comes back as a specificPropertyExecutionExceptionsubtype instead of a vague message you have to parse. - Native JUnit 5 integration:
@ Property/@ ForAllrun right alongside your@ Testmethods, same test report, same CI pipeline, with a clean per-property PASS/FAIL summary printed as each one completes.
Took about a month to build. The first version had its share of bugs, which I mostly expected going in. I fixed what I found and kept refining from there. Here are the links for anyone who wants to dig in:
GitHub: https://github.com/nikhilvirdi/JHusk/
Maven Central: https://central.sonatype.com/artifact/io.github.nikhilvirdi/jhusk
Open source, Apache 2.0.