diff --git a/README.md b/README.md index 8be644e..86100dc 100644 --- a/README.md +++ b/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,7 +230,7 @@ function random(): \Faker\Generator function anElephant(): ElephantBuilder { - return ElephantBuilder::random(); + return ElephantBuilder::new(); } /** @@ -236,12 +238,12 @@ function anElephant(): ElephantBuilder */ 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(); } /** @@ -249,7 +251,7 @@ function aTopic(): TopicBuilder */ function someTopics(int|null $numberOfItems = null): array { - return RandomMultiple::from(TopicBuilder::class, $numberOfItems); + return Many::from(TopicBuilder::class, $numberOfItems); } ``` diff --git a/infection.json5.dist b/infection.json5.dist index 4ba4680..4ec2e74 100644 --- a/infection.json5.dist +++ b/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", ] } }, diff --git a/src/Buildatable.php b/src/Buildatable.php index 40cb90e..9d303e9 100644 --- a/src/Buildatable.php +++ b/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(); diff --git a/src/RandomMultiple.php b/src/Many.php similarity index 89% rename from src/RandomMultiple.php rename to src/Many.php index 211399f..30286b8 100644 --- a/src/RandomMultiple.php +++ b/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; diff --git a/tests/BuildatableTest.php b/tests/BuildatableTest.php index 59cf758..0733d0f 100644 --- a/tests/BuildatableTest.php +++ b/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(); diff --git a/tests/RandomMultipleTest.php b/tests/ManyTest.php similarity index 86% rename from tests/RandomMultipleTest.php rename to tests/ManyTest.php index 86b1275..f80dbc3 100644 --- a/tests/RandomMultipleTest.php +++ b/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();