API Suggestion: Creating Arbitraries of Fundamental Types

[jlink]

In Jqwik 1 all fundamental type arbitraries were rooted in class Arbitraries. Therefore, you create an arbitrary for Strings with Arbitraries.strings() and integers with Arbitraries.integers() and so on. Also, more fundamental arbitrary types, like simply choosing one of several values or selecting one arbitraries from many, started there. This lead to many (43) static public methods in Arbitraries; too many to navigate easily.

In order to make navigation easier, I suggest to put those fundamental creation methods on several base classes:

• Class Numbers will contain creation methods for all Java number types, e.g.

  • Numbers.integers()
  • Numbers.bigDecimals()
  • etc.

• Class Strings, with

  • Strings.strings()
  • Strings.unicodCodepoints()
  • Strings.chars()

• Class Values, with

  • Values.just(..)
  • Values.of(..)
  • Values.frequency(..)
  • Values.oneOf(..) for choosing among arbitraries
  • Values.lazy(..)
  • Values.defaultFor(..)
  • etc.

Other base classes - potentially located in modules outside the core - could be:

• Maps for creating a map from one type to another
• Dates, Times, ....

Design Questions

• Does distributing static creation methods over several class help discoverability or harm it?
• Are there other approaches with good discoverability, e.g. starting from one main arbitrary builder function and specializing from there. E.g.: Arbitraries.numbers().bigIntegers() ?

[SimY4]

IMO it's a loss of discoverability. There's not better way to put it other than in a class as static functions.

One thing I've experimented with in the past is having static nested classes instead of static methods.

interfaces Arbitrary<A> {
  ...

  final class Numbers {
    ...
  }
}

var arb = Arbitrary.Numbers.integral()

It saves you from using braces in between "words" making it look slightly closer to normal text. But discovery is still worse than just a kitchen sink with static methods.

To add to that of I may, I'd suggest to unfinalize the Arbitraries class and make its constructor accessible so that users could extend it. Similar thing is followed by all of the assertions libraries. E.g. so this become possible:

class MyArbitraries extends Arbitraries {
  ...
}

The latter can be done for jqwik v1. 😉

[jlink]

One thing I've experimented with in the past is having static nested classes instead of static methods.

I like this idea. The drawback I see is that only the core module would be able to use that approach. Additional modules would have to come with their own base class(es).