feat: add @ElementOf annotation

[simonresch]

Allows picking from a fixed set of values during mutation.

@FuzzTest
void fuzz(@ElementOf(strings = {"one", "two", "three"}) String value) {
    // value is always "one", "two", or "three"
}

[Copilot]

Pull request overview

This PR introduces the @ElementOf annotation to allow restricting generated values to a fixed set of constants during mutation testing. The annotation supports all primitive types (and their boxed equivalents) as well as String.

• Adds @ElementOf annotation with type-specific array fields (bytes, shorts, integers, longs, chars, floats, doubles, strings)
• Implements ElementOfMutatorFactory to create mutators that select from the provided value sets
• Updates documentation with usage examples and annotation reference table

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/main/java/com/code_intelligence/jazzer/mutation/annotation/ElementOf.java	New annotation definition with array fields for each supported type
src/main/java/com/code_intelligence/jazzer/mutation/mutator/lang/ElementOfMutatorFactory.java	Factory implementation that creates mutators for selecting from fixed value sets
src/main/java/com/code_intelligence/jazzer/mutation/mutator/lang/LangMutators.java	Registers the new ElementOfMutatorFactory in the mutation chain
src/test/java/com/code_intelligence/jazzer/mutation/mutator/lang/ElementOfMutatorFactoryTest.java	Unit tests verifying integer and string selection behavior, plus validation
src/test/java/com/code_intelligence/jazzer/mutation/mutator/StressTest.java	Integration test case for string array selection
docs/mutation-framework.md	Documentation updates with annotation reference and usage example

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[oetr]

Nice addition, thanks!

It works great if the user never removes @ElementOf annotation from the type.

My main issue is that in the corpus we save indices and not the actual values.
This is especially bad for strings if the user's intention is to help the fuzz test boost coverage, and then delete the @ElementOf annotation.
Doing so instantly splits the coprus into two parts---one that gives you coverage with @ElementOf and one without it. You cannot join them.

It is ok-ish only for integers, that have the same byte size, because the bytes that come after are still correctly aligned.
For the other integers, the rest of the bytes is misaligned and probably worthless.

The order of the elements matters, because the corpus only contains indices.
Inserting an element in-between the element list will invalidate the corpus that contains indices for all elements after.

I think, by saving the actual values in the corpus, instead of just indices, we could make this annotation more efficient for users who tend to frequently tweak their fuzz test signature. The only tricky part is to de/serialize strings, but it will make this annotation a lot better. I have prototyped an implementation that does that, take a look at the branch element-of-copy if you like!

pre-approving this, but you know what to do!

[simonresch]

Nice addition, thanks!

It works great if the user never removes @ElementOf annotation from the type.

My main issue is that in the corpus we save indices and not the actual values. This is especially bad for strings if the user's intention is to help the fuzz test boost coverage, and then delete the @ElementOf annotation. Doing so instantly splits the coprus into two parts---one that gives you coverage with @ElementOf and one without it. You cannot join them.

It is ok-ish only for integers, that have the same byte size, because the bytes that come after are still correctly aligned. For the other integers, the rest of the bytes is misaligned and probably worthless.

The order of the elements matters, because the corpus only contains indices. Inserting an element in-between the element list will invalidate the corpus that contains indices for all elements after.

I think, by saving the actual values in the corpus, instead of just indices, we could make this annotation more efficient for users who tend to frequently tweak their fuzz test signature. The only tricky part is to de/serialize strings, but it will make this annotation a lot better. I have prototyped an implementation that does that, take a look at the branch element-of-copy if you like!

pre-approving this, but you know what to do!

Great review, thanks!
I have to admit I'm not thinking about corpus stability in the mutators to often. It seems like every other change to the fuzz test signature breaks the corpus format which makes the corpus files quite compact but requires having to re-build the corpus e.g. after adding or dropping @NotNull, re-ordering parameters, ... . In my head @ElementOf was basically syntactic sugar around creating dedicated enums with specific values. Using it temporarily as a "fuzzing booster" is an interesting use case I did not consider. It would cause a bit of bloat in the corpus files for larger string values but I suspect that would not have a huge impact. I'll play around with this a bit...

[simonresch]

@oetr I went with your suggestion to store the serialized elements directly in the corpus instead of the index. Do you want to give it another look?