Extension for repeatable randomness in tests

[toolforger]

Something like the random seed display/setter for ClassOrderer.Random and MethodOrderer.Random, but make it inject the seed into a parameter of a test.
Allows tests to use random data, but if an error shows up the seed can be re-injected to repeat the failure.

Does this exist?
If no, would you like me to write and contribute it?

One potential use case is as a building block for something like Haskell's QuickCheck - the idea is to generate random data and have a predicate that defines if a function's result matches some expectation, shifting focus from setting up test data to the properties a function result should have.

---

Background info

The ...Order.Random mechanism works like this:

• Shows the seed in the log (if CONFIG level is enabled):
  Aug. 16, 2026 10:36:33 PM org.junit.jupiter.api.MethodOrderer$Random <clinit>
CONFIGURATION: MethodOrderer.Random default seed: 213237194852764
• If the configuration parameter junit.jupiter.execution.order.random.seed is set to, say, 4711, you get:
  Aug. 17, 2026 1:21:13 AM org.junit.jupiter.api.MethodOrderer$Random <clinit>
CONFIGURATION: MethodOrderer.Random default seed: 223116304088237
Aug. 17, 2026 1:21:13 AM org.junit.jupiter.api.RandomOrdererUtils lambda$getCustomSeed$0
CONFIGURATION: Using custom seed for configuration parameter [junit.jupiter.execution.order.random.seed] with value [4711].

So if a test fails randomly, one can log the seed, note the one shown when the failure pops up again, and have a repeatable failure because now the random seed is the same.
junit.jupiter.execution.order.random.seed is just for random test order, but the JUnit team is willing to give it a more general name.

[MLuc24]

Both halves of what you're describing already exist in the repo, but they've never been joined — which is a decent argument that your proposal is the missing piece rather than a duplicate.

The seed handling you sketched lives in RandomOrdererUtils:

static final String RANDOM_SEED_PROPERTY_NAME = "junit.jupiter.execution.order.random.seed";

static final long DEFAULT_SEED = System.nanoTime();

static Long getSeed(Function<String, Optional<String>> configurationParameterLookup, Logger logger) {
    return getCustomSeed(configurationParameterLookup, logger).orElse(DEFAULT_SEED);
}

Worth noting for your implementation: that class is package-private and its members are static, sitting in org.junit.jupiter.api. So an extension can't call into it — you'd be reimplementing the property lookup, the parse-failure fallback and the CONFIG logging rather than reusing them. Not hard, but it means the seed plumbing gets duplicated unless part of this work is promoting it to something shared.

The injection half is already documented, as an example extension rather than shipped API — documentation/src/test/java/example/extensions/RandomNumberExtension.java, a ParameterResolver keyed on an @Random annotation:

public boolean supportsParameter(ParameterContext pc, ExtensionContext ec) {
    return pc.isAnnotated(Random.class) && isInteger(pc.getParameter().getType());
}

And here's the gap, in the same file:

private final java.util.Random random = new java.util.Random(System.nanoTime());

It seeds from the clock and neither reports the seed nor accepts one. So the docs show people how to inject randomness while leaving them with exactly the irreproducibility you're trying to fix. That example is probably the strongest thing to point at when you propose this — it's the same shape, minus the half that makes a failure re-runnable.

On the QuickCheck angle, expect that to be the part that draws pushback, since jqwik already does property-based testing on the JUnit Platform and maintainers tend to prefer keeping generation strategies out of core. The seed injection stands on its own without it, though — reproducing a flaky failure is useful to anyone using randomness at all, whether or not they're doing property-based testing. I'd lead with that and mention QuickCheck only as a downstream possibility.

[MLuc24]

Can't speak to the interest question — that's one for the maintainers and whoever else shows up. But since the API is going to be published to extensions, there's a design decision worth settling early, because it determines whether the thing is actually useful or just tidy.

The orderer seed is a single root value for the run:

static final long DEFAULT_SEED = System.nanoTime();

If you inject that directly as each test's seed, every test in the run draws the same sequence. That sounds harmless until two tests both ask for "a random name" and silently get identical ones, and a bug that only shows up on collisions becomes either always-reproducing or never — depending on the seed — rather than showing up at the rate it should. Derivation is the fix: seed each test from the root plus something stable about the test itself, along the lines of rootSeed ^ hash(uniqueId). One number still reproduces the entire run, each test stays independently reproducible, and the streams are decorrelated.

The stability of that second input is the part to be careful about. UniqueId survives reordering and reruns, whereas anything positional would mean a test's data changes when an unrelated test is added — which quietly breaks reproducibility across commits, the exact property you're building this for.

The other thing I'd change from the example is what gets injected. It resolves integers only:

return type == Integer.class || type == int.class;

Handing back a seeded Random, or a RandomGenerator on modern Java, is a lot more useful — the test can draw whatever shapes it needs and stays reproducible, instead of the extension having to grow a resolver per type. It also makes the QuickCheck-ish direction possible later without redesigning anything, since a generator library can be handed the same seeded source.

Worth reporting the derived seed rather than only the root, too. When someone gets a failure they want to re-run one test, not the whole suite.

[toolforger]

Heh. Yes, the whole thing started as "how do I get the test order randomness into my code".
The JUnit team is pretty helpful here, they'll publish the API to the extension (including renaming/aliasing the root seed to a name that better reflects its status).
They also suggested a look at the example code, so my current angle is to elevate that to extension status. As you rightly noted, it requires the polishing that you mention, plus some more polishing.
That all said, the main question here is: Is there interest in such an extension?

After looking into jqwik, I'm saying I'd really like to use that and drop the extension entirely, as it's pretty comprehensive and has anything about randomness one would ever want, and that's just a small building block.
Unfortunately, there's no funding for jqwik2, which would be the version for JUnit 6.
So I guess I'll pursue that humble repeatable-randomness extension instead.

[mpkorstanje]

The JUnit team is pretty helpful here, they'll publish the API to the extension (including renaming/aliasing the root seed to a name that better reflects its status).

Note: We still have to discuss that.

[toolforger]

Am 17.08.26 um 11:02 schrieb Phạm Mạnh Lực:

Can't speak to the interest question

Please don't detract from that then. All the technical points you're raising are valid, already answered, almost every one of them exactly the way you're suggesting. But that's the second step. The first step is finding out whether there's any interest, because without that, it's not worth doing. Please consider removing your postings, as they are making it hard for people with interest in the actual question to find the actually relevant discussion. I appreciate the effort you put into them btw. It's just that they aren't helpful at this stage. Thanks. Regards, Jo

[toolforger]

The JUnit team is pretty helpful here, they'll publish the API to the extension (including renaming/aliasing the root seed to a name that better reflects its status). Note: We still have to discuss that.

Oops. Sorry for misrepresenting this, my bad.