From 648c6c5a27c1e57596f824a088909cc5fb035cc0 Mon Sep 17 00:00:00 2001 From: Nuno Maduro Date: Sun, 24 Oct 2021 19:37:29 +0100 Subject: [PATCH] refactor: comments --- bin/pest | 4 +- src/Actions/InteractsWithPlugins.php | 50 ------------------- src/Concerns/Expectable.php | 4 +- src/Concerns/Extendable.php | 10 ++-- src/Concerns/Logging/WritesToConsole.php | 12 +++++ src/Concerns/RetrievesValues.php | 2 +- src/Console/Help.php | 12 ++++- src/Console/Thanks.php | 11 +++- src/Contracts/HasPrintableTestCaseName.php | 22 +++----- src/Contracts/Plugins/AddsOutput.php | 4 +- src/Contracts/Plugins/HandlesArguments.php | 8 +-- src/Emitters/DispatchingEmitter.php | 3 ++ src/Exceptions/AfterAllAlreadyExist.php | 2 +- src/Exceptions/AfterEachAlreadyExist.php | 2 +- src/Exceptions/AttributeNotSupportedYet.php | 2 +- src/Exceptions/BeforeEachAlreadyExist.php | 2 +- src/Exceptions/DatasetAlreadyExist.php | 2 +- src/Exceptions/DatasetDoesNotExist.php | 2 +- src/Exceptions/DatasetMissing.php | 12 ++--- src/Exceptions/FileOrFolderNotFound.php | 2 +- src/Exceptions/InvalidConsoleArgument.php | 2 +- src/Exceptions/InvalidPestCommand.php | 2 +- src/Exceptions/MissingDependency.php | 2 +- src/Exceptions/ShouldNotHappen.php | 2 +- src/Exceptions/TestAlreadyExist.php | 2 +- src/Exceptions/TestCaseAlreadyInUse.php | 2 +- .../TestCaseClassOrTraitNotFound.php | 2 +- src/Factories/TestCaseFactory.php | 18 ++----- src/{Console => }/Kernel.php | 8 ++- src/Plugins/Actions/AddsOutput.php | 30 +++++++++++ src/Plugins/Actions/HandleArguments.php | 33 ++++++++++++ src/Support/Arr.php | 13 ++--- 32 files changed, 151 insertions(+), 133 deletions(-) delete mode 100644 src/Actions/InteractsWithPlugins.php rename src/{Console => }/Kernel.php (85%) create mode 100644 src/Plugins/Actions/AddsOutput.php create mode 100644 src/Plugins/Actions/HandleArguments.php diff --git a/bin/pest b/bin/pest index badfc903..c83b6446 100755 --- a/bin/pest +++ b/bin/pest @@ -1,12 +1,10 @@ #!/usr/bin/env php $argv - * - * @return array - */ - public static function handleArguments(array $argv): array - { - $plugins = Loader::getPlugins(HandlesArguments::class); - - /** @var HandlesArguments $plugin */ - foreach ($plugins as $plugin) { - $argv = $plugin->handleArguments($argv); - } - - return $argv; - } - - /** - * Provides an opportunity for any plugins that want - * to provide additional output after test execution. - */ - public static function addOutput(int $result): int - { - $plugins = Loader::getPlugins(AddsOutput::class); - - /** @var AddsOutput $plugin */ - foreach ($plugins as $plugin) { - $result = $plugin->addOutput($result); - } - - return $result; - } -} diff --git a/src/Concerns/Expectable.php b/src/Concerns/Expectable.php index 981e443d..474a900f 100644 --- a/src/Concerns/Expectable.php +++ b/src/Concerns/Expectable.php @@ -14,13 +14,13 @@ trait Expectable /** * @template TValue * - * Creates a new expectation. + * Creates a new Expectation. * * @param TValue $value * * @return Expectation */ - public function expect($value): Expectation + public function expect(mixed $value): Expectation { return new Expectation($value); } diff --git a/src/Concerns/Extendable.php b/src/Concerns/Extendable.php index 0d689452..5cf3e79d 100644 --- a/src/Concerns/Extendable.php +++ b/src/Concerns/Extendable.php @@ -13,12 +13,14 @@ use Closure; trait Extendable { /** + * The list of extends. + * * @var array */ private static array $extends = []; /** - * Register a custom extend. + * Register a new extend. */ public static function extend(string $name, Closure $extend): void { @@ -26,7 +28,7 @@ trait Extendable } /** - * Checks if extend is registered. + * Checks if given extend name is registered. */ public static function hasExtend(string $name): bool { @@ -37,10 +39,8 @@ trait Extendable * Dynamically handle calls to the class. * * @param array $parameters - * - * @return mixed */ - public function __call(string $method, array $parameters) + public function __call(string $method, array $parameters): mixed { if (!static::hasExtend($method)) { throw new BadMethodCallException("$method is not a callable method name."); diff --git a/src/Concerns/Logging/WritesToConsole.php b/src/Concerns/Logging/WritesToConsole.php index a2965bcb..71c69754 100644 --- a/src/Concerns/Logging/WritesToConsole.php +++ b/src/Concerns/Logging/WritesToConsole.php @@ -9,21 +9,33 @@ namespace Pest\Concerns\Logging; */ trait WritesToConsole { + /** + * Writes the given success message to the console. + */ private function writeSuccess(string $message): void { $this->writePestTestOutput($message, 'fg-green, bold', '✓'); } + /** + * Writes the given error message to the console. + */ private function writeError(string $message): void { $this->writePestTestOutput($message, 'fg-red, bold', '⨯'); } + /** + * Writes the given warning message to the console. + */ private function writeWarning(string $message): void { $this->writePestTestOutput($message, 'fg-yellow, bold', '-'); } + /** + * Writes the give message to the console. + */ private function writePestTestOutput(string $message, string $color, string $symbol): void { $this->writeWithColor($color, "$symbol ", false); diff --git a/src/Concerns/RetrievesValues.php b/src/Concerns/RetrievesValues.php index a8d832b1..56f3d2c8 100644 --- a/src/Concerns/RetrievesValues.php +++ b/src/Concerns/RetrievesValues.php @@ -19,7 +19,7 @@ trait RetrievesValues * * @return TRetrievableValue|null */ - private function retrieve(string $key, $value, $default = null) + private function retrieve(string $key, mixed $value, mixed $default = null): mixed { if (is_array($value)) { return $value[$key] ?? $default; diff --git a/src/Console/Help.php b/src/Console/Help.php index 0bb43477..174625c5 100644 --- a/src/Console/Help.php +++ b/src/Console/Help.php @@ -11,7 +11,11 @@ use Symfony\Component\Console\Output\OutputInterface; */ final class Help { - /** @var array */ + /** + * The Command messages. + * + * @var array + */ private const HELP_MESSAGES = [ 'Pest Options:', ' --init Initialise a standard Pest configuration', @@ -20,11 +24,17 @@ final class Help ' --group= Only runs tests from the specified group(s)', ]; + /** + * Creates a new Console Command instance. + */ public function __construct(private OutputInterface $output) { // .. } + /** + * Executes the Console Command. + */ public function __invoke(): void { foreach (self::HELP_MESSAGES as $message) { diff --git a/src/Console/Thanks.php b/src/Console/Thanks.php index 5ae807ec..4e24b9ae 100644 --- a/src/Console/Thanks.php +++ b/src/Console/Thanks.php @@ -14,7 +14,11 @@ use Symfony\Component\Console\Question\ConfirmationQuestion; */ final class Thanks { - /** @var array */ + /** + * The Command messages. + * + * @var array + */ private const FUNDING_MESSAGES = [ '', ' - Star or contribute to Pest:', @@ -25,13 +29,16 @@ final class Thanks ' https://github.com/sponsors/nunomaduro', ]; + /** + * Creates a new Console Command instance. + */ public function __construct(private OutputInterface $output) { // .. } /** - * Asks the user to support Pest. + * Executes the Console Command. */ public function __invoke(): void { diff --git a/src/Contracts/HasPrintableTestCaseName.php b/src/Contracts/HasPrintableTestCaseName.php index 0d95d15d..e46a634d 100644 --- a/src/Contracts/HasPrintableTestCaseName.php +++ b/src/Contracts/HasPrintableTestCaseName.php @@ -4,18 +4,12 @@ declare(strict_types=1); namespace Pest\Contracts; -if (interface_exists(\NunoMaduro\Collision\Contracts\Adapters\Phpunit\HasPrintableTestCaseName::class)) { - /** - * @internal - */ - interface HasPrintableTestCaseName extends \NunoMaduro\Collision\Contracts\Adapters\Phpunit\HasPrintableTestCaseName - { - } -} else { - /** - * @internal - */ - interface HasPrintableTestCaseName - { - } +use NunoMaduro\Collision\Contracts\Adapters\Phpunit\HasPrintableTestCaseName as BaseHasPrintableTestCaseName; + +/** + * @internal + */ +interface HasPrintableTestCaseName extends BaseHasPrintableTestCaseName +{ + // .. } diff --git a/src/Contracts/Plugins/AddsOutput.php b/src/Contracts/Plugins/AddsOutput.php index a105e0d0..a2ab4aeb 100644 --- a/src/Contracts/Plugins/AddsOutput.php +++ b/src/Contracts/Plugins/AddsOutput.php @@ -10,7 +10,7 @@ namespace Pest\Contracts\Plugins; interface AddsOutput { /** - * Allows to add custom output after the test suite was executed. + * Adds output after the Test Suite execution. */ - public function addOutput(int $testReturnCode): int; + public function addOutput(int $exitCode): int; } diff --git a/src/Contracts/Plugins/HandlesArguments.php b/src/Contracts/Plugins/HandlesArguments.php index 3814150b..a3c69ac5 100644 --- a/src/Contracts/Plugins/HandlesArguments.php +++ b/src/Contracts/Plugins/HandlesArguments.php @@ -10,11 +10,11 @@ namespace Pest\Contracts\Plugins; interface HandlesArguments { /** - * Allows to handle custom command line arguments. + * Adds arguments before of the Test Suite execution. * - * @param array $arguments + * @param array $argv * - * @return array the updated list of arguments + * @return array */ - public function handleArguments(array $arguments): array; + public function handleArguments(array $argv): array; } diff --git a/src/Emitters/DispatchingEmitter.php b/src/Emitters/DispatchingEmitter.php index 8173d9ca..d8e82fda 100644 --- a/src/Emitters/DispatchingEmitter.php +++ b/src/Emitters/DispatchingEmitter.php @@ -19,6 +19,9 @@ use SebastianBergmann\GlobalState\Snapshot; */ final class DispatchingEmitter implements Emitter { + /** + * Creates a new Emitter instance. + */ public function __construct(private Emitter $baseEmitter) { // .. diff --git a/src/Exceptions/AfterAllAlreadyExist.php b/src/Exceptions/AfterAllAlreadyExist.php index b21de8f9..f74e8b51 100644 --- a/src/Exceptions/AfterAllAlreadyExist.php +++ b/src/Exceptions/AfterAllAlreadyExist.php @@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface; final class AfterAllAlreadyExist extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace { /** - * Creates a new instance of after all already exist exception. + * Creates a new Exception instance. */ public function __construct(string $filename) { diff --git a/src/Exceptions/AfterEachAlreadyExist.php b/src/Exceptions/AfterEachAlreadyExist.php index 118a4509..43faa817 100644 --- a/src/Exceptions/AfterEachAlreadyExist.php +++ b/src/Exceptions/AfterEachAlreadyExist.php @@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface; final class AfterEachAlreadyExist extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace { /** - * Creates a new instance of after each already exist exception. + * Creates a new Exception instance. */ public function __construct(string $filename) { diff --git a/src/Exceptions/AttributeNotSupportedYet.php b/src/Exceptions/AttributeNotSupportedYet.php index e30325e3..d34262f6 100644 --- a/src/Exceptions/AttributeNotSupportedYet.php +++ b/src/Exceptions/AttributeNotSupportedYet.php @@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface; final class AttributeNotSupportedYet extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace { /** - * Creates a new instance of attribute not supported yet. + * Creates a new Exception instance. */ public function __construct(string $attribute, string $value) { diff --git a/src/Exceptions/BeforeEachAlreadyExist.php b/src/Exceptions/BeforeEachAlreadyExist.php index 32fa49f7..fba76297 100644 --- a/src/Exceptions/BeforeEachAlreadyExist.php +++ b/src/Exceptions/BeforeEachAlreadyExist.php @@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface; final class BeforeEachAlreadyExist extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace { /** - * Creates a new instance of before each already exist exception. + * Creates a new Exception instance. */ public function __construct(string $filename) { diff --git a/src/Exceptions/DatasetAlreadyExist.php b/src/Exceptions/DatasetAlreadyExist.php index 0eea6a32..b5276329 100644 --- a/src/Exceptions/DatasetAlreadyExist.php +++ b/src/Exceptions/DatasetAlreadyExist.php @@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface; final class DatasetAlreadyExist extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace { /** - * Creates a new instance of dataset already exist. + * Creates a new Exception instance. */ public function __construct(string $name) { diff --git a/src/Exceptions/DatasetDoesNotExist.php b/src/Exceptions/DatasetDoesNotExist.php index b18669f6..72126fb8 100644 --- a/src/Exceptions/DatasetDoesNotExist.php +++ b/src/Exceptions/DatasetDoesNotExist.php @@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface; final class DatasetDoesNotExist extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace { /** - * Creates a new instance of dataset does not exist. + * Creates a new Exception instance. */ public function __construct(string $name) { diff --git a/src/Exceptions/DatasetMissing.php b/src/Exceptions/DatasetMissing.php index 023487e8..8d3a7cd9 100644 --- a/src/Exceptions/DatasetMissing.php +++ b/src/Exceptions/DatasetMissing.php @@ -10,24 +10,22 @@ use NunoMaduro\Collision\Contracts\RenderlessTrace; use Symfony\Component\Console\Exception\ExceptionInterface; /** - * Creates a new instance of dataset is not present for test that has arguments. - * * @internal */ final class DatasetMissing extends BadFunctionCallException implements ExceptionInterface, RenderlessEditor, RenderlessTrace { /** - * Create new exception instance. + * Creates a new Exception instance. * - * @param array $args A map of argument names to their typee + * @param array $arguments */ - public function __construct(string $file, string $name, array $args) + public function __construct(string $file, string $name, array $arguments) { parent::__construct(sprintf( "A test with the description '%s' has %d argument(s) ([%s]) and no dataset(s) provided in %s", $name, - count($args), - implode(', ', array_map(static fn (string $arg, string $type): string => sprintf('%s $%s', $type, $arg), array_keys($args), $args)), + count($arguments), + implode(', ', array_map(static fn (string $arg, string $type): string => sprintf('%s $%s', $type, $arg), array_keys($arguments), $arguments)), $file, )); } diff --git a/src/Exceptions/FileOrFolderNotFound.php b/src/Exceptions/FileOrFolderNotFound.php index 49163cc4..bd59ac2a 100644 --- a/src/Exceptions/FileOrFolderNotFound.php +++ b/src/Exceptions/FileOrFolderNotFound.php @@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface; final class FileOrFolderNotFound extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace { /** - * Creates a new instance of file not found. + * Creates a new Exception instance. */ public function __construct(string $filename) { diff --git a/src/Exceptions/InvalidConsoleArgument.php b/src/Exceptions/InvalidConsoleArgument.php index 98774b02..a3e3ad30 100644 --- a/src/Exceptions/InvalidConsoleArgument.php +++ b/src/Exceptions/InvalidConsoleArgument.php @@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface; final class InvalidConsoleArgument extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace { /** - * Creates a new instance of should not happen. + * Creates a new Exception instance. */ public function __construct(string $message) { diff --git a/src/Exceptions/InvalidPestCommand.php b/src/Exceptions/InvalidPestCommand.php index 269585db..5a5c153d 100644 --- a/src/Exceptions/InvalidPestCommand.php +++ b/src/Exceptions/InvalidPestCommand.php @@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface; final class InvalidPestCommand extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace { /** - * Creates a new instance of invalid pest command exception. + * Creates a new Exception instance. */ public function __construct() { diff --git a/src/Exceptions/MissingDependency.php b/src/Exceptions/MissingDependency.php index e7d7940d..43dc29ef 100644 --- a/src/Exceptions/MissingDependency.php +++ b/src/Exceptions/MissingDependency.php @@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface; final class MissingDependency extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace { /** - * Creates a new instance of missing dependency. + * Creates a new Exception instance. */ public function __construct(string $feature, string $dependency) { diff --git a/src/Exceptions/ShouldNotHappen.php b/src/Exceptions/ShouldNotHappen.php index dc44c509..c2bb424b 100644 --- a/src/Exceptions/ShouldNotHappen.php +++ b/src/Exceptions/ShouldNotHappen.php @@ -13,7 +13,7 @@ use RuntimeException; final class ShouldNotHappen extends RuntimeException { /** - * Creates a new instance of should not happen. + * Creates a new Exception instance. */ public function __construct(Exception $exception) { diff --git a/src/Exceptions/TestAlreadyExist.php b/src/Exceptions/TestAlreadyExist.php index 68c4be95..75f4a420 100644 --- a/src/Exceptions/TestAlreadyExist.php +++ b/src/Exceptions/TestAlreadyExist.php @@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface; final class TestAlreadyExist extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace { /** - * Creates a new instance of test already exist. + * Creates a new Exception instance. */ public function __construct(string $fileName, string $description) { diff --git a/src/Exceptions/TestCaseAlreadyInUse.php b/src/Exceptions/TestCaseAlreadyInUse.php index f407ed17..7ebf6232 100644 --- a/src/Exceptions/TestCaseAlreadyInUse.php +++ b/src/Exceptions/TestCaseAlreadyInUse.php @@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface; final class TestCaseAlreadyInUse extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace { /** - * Creates a new instance of test case already in use. + * Creates a new Exception instance. */ public function __construct(string $inUse, string $newOne, string $folder) { diff --git a/src/Exceptions/TestCaseClassOrTraitNotFound.php b/src/Exceptions/TestCaseClassOrTraitNotFound.php index b5e8c547..78b73a1c 100644 --- a/src/Exceptions/TestCaseClassOrTraitNotFound.php +++ b/src/Exceptions/TestCaseClassOrTraitNotFound.php @@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface; final class TestCaseClassOrTraitNotFound extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace { /** - * Creates a new instance of after each already exist exception. + * Creates a new Exception instance. */ public function __construct(string $testCaseClass) { diff --git a/src/Factories/TestCaseFactory.php b/src/Factories/TestCaseFactory.php index e9c288c1..d56d163f 100644 --- a/src/Factories/TestCaseFactory.php +++ b/src/Factories/TestCaseFactory.php @@ -24,15 +24,11 @@ final class TestCaseFactory { /** * Marks this test case as only. - * - * @readonly */ public bool $only = false; /** * Holds the test closure. - * - * @readonly */ public Closure $test; @@ -53,7 +49,7 @@ final class TestCaseFactory /** * An array of FQN of the class traits. * - * @var array + * @var array */ public array $traits = [ Concerns\Testable::class, @@ -61,12 +57,12 @@ final class TestCaseFactory ]; /** - * Holds the higher order messages for the factory that are proxyble. + * Holds the higher order messages for the factory that are proxyable. */ public HigherOrderMessageCollection $factoryProxies; /** - * Holds the higher order messages that are proxyble. + * Holds the higher order messages that are proxyable. */ public HigherOrderMessageCollection $proxies; @@ -80,14 +76,10 @@ final class TestCaseFactory */ public function __construct( public string $filename, - public ?string $description = null, + public ?string $description, Closure $closure = null) { - $this->test = $closure ?? function (): void { - if (Assert::getCount() === 0) { - self::markTestIncomplete(); // @phpstan-ignore-line - } - }; + $this->test = $closure ?? fn () => Assert::getCount() > 0 ?: self::markTestIncomplete(); $this->factoryProxies = new HigherOrderMessageCollection(); $this->proxies = new HigherOrderMessageCollection(); diff --git a/src/Console/Kernel.php b/src/Kernel.php similarity index 85% rename from src/Console/Kernel.php rename to src/Kernel.php index cb78e9bd..f507f7e0 100644 --- a/src/Console/Kernel.php +++ b/src/Kernel.php @@ -2,10 +2,8 @@ declare(strict_types=1); -namespace Pest\Console; +namespace Pest; -use Pest\Actions\InteractsWithPlugins; -use Pest\Bootstrappers; use PHPUnit\TextUI\Application; /** @@ -53,13 +51,13 @@ final class Kernel */ public function handle(array $argv): int { - $argv = InteractsWithPlugins::handleArguments($argv); + $argv = (new Plugins\Actions\HandleArguments())->__invoke($argv); $result = $this->application->run( $argv, false, ); - return InteractsWithPlugins::addOutput($result); + return (new Plugins\Actions\AddsOutput())->__invoke($result); } /** diff --git a/src/Plugins/Actions/AddsOutput.php b/src/Plugins/Actions/AddsOutput.php new file mode 100644 index 00000000..966affe8 --- /dev/null +++ b/src/Plugins/Actions/AddsOutput.php @@ -0,0 +1,30 @@ +addOutput($exitCode); + } + + return $exitCode; + } +} diff --git a/src/Plugins/Actions/HandleArguments.php b/src/Plugins/Actions/HandleArguments.php new file mode 100644 index 00000000..f0369d01 --- /dev/null +++ b/src/Plugins/Actions/HandleArguments.php @@ -0,0 +1,33 @@ + $argv + * + * @return array + */ + public function __invoke(array $argv): array + { + $plugins = Loader::getPlugins(Plugins\HandlesArguments::class); + + /** @var Plugins\HandlesArguments $plugin */ + foreach ($plugins as $plugin) { + $argv = $plugin->handleArguments($argv); + } + + return $argv; + } +} diff --git a/src/Support/Arr.php b/src/Support/Arr.php index a55764d5..3fbe0e61 100644 --- a/src/Support/Arr.php +++ b/src/Support/Arr.php @@ -5,16 +5,12 @@ declare(strict_types=1); namespace Pest\Support; /** - * Credits: most of this class methods and implementations - * belongs to the Arr helper of laravel/framework project - * (https://github.com/laravel/framework). - * * @internal */ final class Arr { /** - * @param array $array + * Checks if the given array has the given key. */ public static function has(array $array, string|int $key): bool { @@ -36,12 +32,9 @@ final class Arr } /** - * @param array $array - * @param null $default - * - * @return array|mixed|null + * Gets the given key value. */ - public static function get(array $array, string|int $key, $default = null) + public static function get(array $array, string|int $key, mixed $default = null): mixed { $key = (string) $key;