feat!: rename Buildatable::random to avoid misunderstanding about the randomness of what it provides

README.md

@@ -60,7 +60,7 @@ Furthermore, it helps to have a common foundation for the adoption of the patter
 ## Usage
 
 We tried not to be too opinionated about the foundation here.
-For instance, we like to use functions like `anElephant()` instead of `ElephantBuilder::random()`
+For instance, we like to use functions like `anElephant()` instead of `ElephantBuilder::new()`
 (we find it more readable and allow us to focus on what is important) but nothing
 forces you to do the same.
 
@@ -70,11 +70,13 @@ You may found the name weird, it is a mix of "build" and "data" with the suffix
 "-able" is used to form adjectives from verbs, with the meaning "capable of, fit for, tending to".
 With this name, we want to express that the object is capable of building data as a test data builder.
 
-The `Buildotter\Core\Buildatable::random()` method is the named constructor to create a new instance of the class with random but commonly used or safe values.
+The `Buildotter\Core\Buildatable::new()` method is the named constructor to create a new instance of the class with commonly used or safe values.
 Imagine that you develop a dating app, you know the age of your customers.
 Most of the time you don't mind about the exact age, you just need one respecting the invariants of your domain
 (see [Propery-Based Testing](https://beram-presentation.gitlab.io/property-based-testing-101) for more about this).
 It is less likely that a customer is 300 or 10 years old than between 18 and 60 years old for instance.
+It means that a commonly used or safe value for the age of a customer is between 18 and 60 years old.
+So instead of choosing an arbitrary value, you may use a random value between 18 and 60 years old.
 
 The `Buildotter\Core\Buildatable::build()` method to create a new object using the values in its properties.
 
@@ -107,7 +109,7 @@ You may choose to not use them at all.
 ### Build multiple objects
 
 You may need multiple objects of the same type at once.
-`Buildotter\Core\RandomMultiple` static methods are here to help you.
+`Buildotter\Core\Many` static methods are here to help you.
 
 ## Example
 
@@ -153,7 +155,7 @@ final readonly class ElephantBuilder implements Buildatable
         private array $topics,
     ) {}
 
-    public static function random(): self
+    public static function new(): self
     {
         $random = \random();
 
@@ -228,28 +230,28 @@ function random(): \Faker\Generator
 
 function anElephant(): ElephantBuilder
 {
-    return ElephantBuilder::random();
+    return ElephantBuilder::new();
 }
 
 /**
  * @return App\Entity\Elephant[]
  */
 function someElephants(int|null $numberOfItems = null): array
 {
-    return RandomMultiple::from(ElephantBuilder::class, $numberOfItems);
+    return Many::from(ElephantBuilder::class, $numberOfItems);
 }
 
 function aTopic(): TopicBuilder
 {
-    return TopicBuilder::random();
+    return TopicBuilder::new();
 }
 
 /**
  * @return App\Entity\Topic[]
  */
 function someTopics(int|null $numberOfItems = null): array
 {
-    return RandomMultiple::from(TopicBuilder::class, $numberOfItems);
+    return Many::from(TopicBuilder::class, $numberOfItems);
 }
 ```
 

infection.json5.dist

@@ -15,13 +15,13 @@
         "DecrementInteger": {
             "ignore": [
                 // Don't know how test could prevent this more than it already does
-                "Buildotter\\Core\\RandomMultiple::numberBetween",
+                "Buildotter\\Core\\Many::numberBetween",
             ]
         },
         "IncrementInteger": {
             "ignore": [
                 // Don't know how test could prevent this more than it already does
-                "Buildotter\\Core\\RandomMultiple::numberBetween",
+                "Buildotter\\Core\\Many::numberBetween",
             ]
         }
     },

src/Buildatable.php

@@ -9,9 +9,21 @@
  */
 interface Buildatable
 {
-    public static function random(): static;
+    /**
+     * The named constructor to create a new instance of the class with commonly used or safe values.
+     *
+     * Imagine that you develop a dating app, you know the age of your customers.
+     * Most of the time you don't mind about the exact age, you just need one respecting the invariants of your domain
+     * (see [Propery-Based Testing](https://beram-presentation.gitlab.io/property-based-testing-101) for more about this).
+     * It is less likely that a customer is 300 or 10 years old than between 18 and 60 years old for instance.
+     * It means that a commonly used or safe value for the age of a customer is between 18 and 60 years old.
+     * So instead of choosing an arbitrary value, you may use a random value between 18 and 60 years old.
+     */
+    public static function new(): static;
 
     /**
+     * Create a new object using the values in its properties.
+     *
      * @return T
      */
     public function build();

src/RandomMultiple.php → src/Many.php

@@ -4,7 +4,7 @@
 
 namespace Buildotter\Core;
 
-final class RandomMultiple
+final class Many
 {
     /**
      * @template T
@@ -19,7 +19,7 @@ public static function from(string $class, int|null $numberOfItems = null): arra
 
         $collection = [];
         for ($i = 0; $i < $numberOfItems; $i++) {
-            $collection[] = $class::random()->build();
+            $collection[] = $class::new()->build();
         }
 
         return $collection;
@@ -38,7 +38,7 @@ public static function toBuildFrom(string $class, int|null $numberOfItems = null
 
         $collection = [];
         for ($i = 0; $i < $numberOfItems; $i++) {
-            $collection[] = $class::random();
+            $collection[] = $class::new();
         }
 
         return $collection;

tests/BuildatableTest.php

@@ -14,10 +14,10 @@ final class BuildatableTest extends TestCase
 {
     public function test_it_is_buildatable_with_array(): void
     {
-        $fooBuiltWithArray = FooBuilderWithArray::random()
+        $fooBuiltWithArray = FooBuilderWithArray::new()
             ->named($text = random()->name())
             ->with(['number' => $n = random()->randomNumber()])
-            ->with(['bar' => $bar = BarBuilder::random()])
+            ->with(['bar' => $bar = BarBuilder::new()])
             ->build();
 
         assertEquals(
@@ -28,10 +28,10 @@ public function test_it_is_buildatable_with_array(): void
 
     public function test_it_is_buildatable_with_arg_unpacking(): void
     {
-        $fooBuiltWithArgsUnpacking = FooBuilderWithArgUnpacking::random()
+        $fooBuiltWithArgsUnpacking = FooBuilderWithArgUnpacking::new()
             ->named($text = random()->name())
             ->with(number: $n = random()->randomNumber())
-            ->with(bar: $bar = BarBuilder::random())
+            ->with(bar: $bar = BarBuilder::new())
             ->build();
 
         assertEquals(
@@ -70,14 +70,14 @@ public function __construct(
         public Bar $bar,
     ) {}
 
-    public static function random(): static
+    public static function new(): static
     {
         $random = random();
 
         return new static(
             $random->name(),
             $random->randomNumber(),
-            BarBuilder::random()->build(),
+            BarBuilder::new()->build(),
         );
     }
 
@@ -105,14 +105,14 @@ public function __construct(
         public Bar $bar,
     ) {}
 
-    public static function random(): static
+    public static function new(): static
     {
         $random = random();
 
         return new static(
             $random->name(),
             $random->randomNumber(),
-            BarBuilder::random()->build(),
+            BarBuilder::new()->build(),
         );
     }
 
@@ -138,7 +138,7 @@ public function __construct(
         public string $value,
     ) {}
 
-    public static function random(): static
+    public static function new(): static
     {
         $random = random();
 

tests/RandomMultipleTest.php → tests/ManyTest.php

@@ -6,18 +6,18 @@
 
 use Buildotter\Core\BuildableWithArgUnpacking;
 use Buildotter\Core\Buildatable;
-use Buildotter\Core\RandomMultiple;
+use Buildotter\Core\Many;
 use PHPUnit\Framework\TestCase;
 use function PHPUnit\Framework\assertContainsOnlyInstancesOf;
 use function PHPUnit\Framework\assertCount;
 use function PHPUnit\Framework\assertGreaterThanOrEqual;
 use function PHPUnit\Framework\assertLessThanOrEqual;
 
-class RandomMultipleTest extends TestCase
+class ManyTest extends TestCase
 {
     public function test_it_builds_multiple_instances_from_builder(): void
     {
-        $bazs = RandomMultiple::from(
+        $bazs = Many::from(
             BazBuilder::class,
             $n = random()->numberBetween(2, 5),
         );
@@ -28,7 +28,7 @@ public function test_it_builds_multiple_instances_from_builder(): void
 
     public function test_it_builds_multiple_instances_from_builder_with_random_number_of_items_per_default(): void
     {
-        $bazs = RandomMultiple::from(BazBuilder::class);
+        $bazs = Many::from(BazBuilder::class);
 
         $numberOfItems = \count($bazs);
         assertGreaterThanOrEqual(1, $numberOfItems);
@@ -38,7 +38,7 @@ public function test_it_builds_multiple_instances_from_builder_with_random_numbe
 
     public function test_it_returns_multiple_builder_instances_ready_to_be_built(): void
     {
-        $bazs = RandomMultiple::toBuildFrom(
+        $bazs = Many::toBuildFrom(
             BazBuilder::class,
             $n = random()->numberBetween(2, 5),
         );
@@ -49,7 +49,7 @@ public function test_it_returns_multiple_builder_instances_ready_to_be_built():
 
     public function test_it_returns_multiple_builder_instances_ready_to_be_built_with_random_number_of_items_per_default(): void
     {
-        $bazs = RandomMultiple::toBuildFrom(BazBuilder::class);
+        $bazs = Many::toBuildFrom(BazBuilder::class);
 
         $numberOfItems = \count($bazs);
         assertGreaterThanOrEqual(1, $numberOfItems);
@@ -76,7 +76,7 @@ public function __construct(
         public string $value,
     ) {}
 
-    public static function random(): static
+    public static function new(): static
     {
         $random = random();