I think the scaladoc here is quite misleading. The listOfN function calls buildableOfN which generalizes the generation for any Buildable and which docs says the following:

The size of the generated container is limited by n. Depending on what kind of container that is generated, the resulting container may contain fewer elements than n, but not more.

That basically means that if the supplied Buildable can drop some elements then the result size can be less than n. For example:

Gen.buildableOfN[Set[Char], Char](37, Gen.numChar)

Apparently this generator will never produce more than 10 elements since the inner generator produces chars in range 0..9.

But I cannot come up with any example where listOfN could generate less then the passed n.

It does what I expect from the name and not what I expect from the docs and I usually end up sampling to remember what it really does.

I don't know that it should be a primitive, but I've had luck mixing it with Poisson when there's no hard max. It gives me outliers without killing test performance:

val g = Gen.poisson(10).flatMap(n => Gen.listOfN(n, Gen.asciiChar))

One concern with fixing is that people have written generators and tests that also do what they "expected", and what ScalaCheck does(!), and not what the doc describes. However, we could probably try making this change in a minor release, which would be 1.16.0, and add release notes and see how it goes.

Indeed, there's probably not a way to change buildableOfN because it is the underlying implementation of other collections like Set and Map and would have averse outcomes for even trivial generators.

I opened an initial PR, #845, to give more variation to the size for Gen.listOfN. This variation only modifies this method for Lists, and won't affect other collections, for the reasons I said above. There's a chance we could try it for others.

There were tests even in ScalaCheck's test suite that were disrupted by this change. Changing a popular method like listOfN is likely going to cause failures for any users who also have fragile tests that are expecting to generate lists of an exact size of N.

Sergey commented on the PR and suggested that these generator methods shouldn't behave inconsistently.

I am not sure that it is a good idea overall. Having listOfN which behaves differently from containerOfN and buildableOfN would be really confusing. Personally I like to have all of them behaving in a similar way.

Wouldn't it be better to create a separate function (or functions) for creating generators like this one above? Something like listOfAtMostN, containerOfAtMostN and buildableOfAtMostN

It's a valid point and why I did plan on investigating the other collection types besides List. The current naming conventions in Gen aren't always ideal, and the duplicate implementations aren't really helping avoid confusion, so this may be an opportunity to make improvements.

Georgi Krastev mades a similar conclusion on the PR on what it is that could be done:

I will just weigh in my opinion as a user - I think changing the behaviour in this way has the potential to break too many tests. Also the current behaviour is consistent with the name listOfN. For these reasons I think it would be better to just change the documentation of listOfN and add new methods with "at most" semantics. If it's possible, calling buildableOfN for Set and Map could then be deprecated.

Sounds like I was tricked by the documentation. In fact, the name of the method is pretty accurate and the scaladoc is not.

Wouldn't it be better to create a separate function (or functions) for creating generators like this one above? Something like listOfAtMostN, containerOfAtMostN and buildableOfAtMostN

That sounds like exactly what I was looking for, I'd love to see them in scalacheck :) If that's something the maintainers want and nobody else would like to work on that (and if it's a good first issue), I'd be happy to spend some time on implementing them.

I don't know that it should be a primitive, but I've had luck mixing it with Poisson when there's no hard max. It gives me outliers without killing test performance:

val g = Gen.poisson(10).flatMap(n => Gen.listOfN(n, Gen.asciiChar))

I'll give that one a try for now and see if it helps in my particular case

@L7R7 do you think this issue is safe to be closed now?

Yes, can be closed.