diff --git a/docs/reference.md b/docs/reference.md index d60d882..9158037 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -181,6 +181,13 @@ to `TypeSpecifier::specifyTypesInCondition()`. Supports `null`, `notNull`, `true `truthy`, `falsey`, `same`, `notSame`, `type` (built-in type strings and class/interface names). A shipped feature, not test-only. +### Assert::fail() as early-terminating (earlyTerminatingMethodCalls, not a PHP extension) + +`Tester\Assert::fail()` is listed in `earlyTerminatingMethodCalls`, so code after it is +unreachable and narrowing holds (`if ($x === null) Assert::fail(...)` leaves `$x` non-null). It +can't be native `never`: an `Assert::$onFailure` handler may swallow the failure and continue. +Consistent with the type-narrowing assertions, which assume the same. + ### Assets family (`MapperTypeResolver` shared service) `MapperTypeResolver` resolves mapper IDs → mapper class types from a `mapping` config diff --git a/extension-nette.neon b/extension-nette.neon index 8a4603e..e2439a2 100644 --- a/extension-nette.neon +++ b/extension-nette.neon @@ -9,6 +9,12 @@ parameters: - Nette\Security\SimpleIdentity - Nette\Utils\Html + earlyTerminatingMethodCalls: + # fail() returns void because an Assert::$onFailure handler may swallow the failure, + # but like every other assertion it is meant to end the test + Tester\Assert: + - fail + ignoreErrors: - # Form event-handler callbacks (onSuccess, onClick, ...) receive data coerced diff --git a/readme.md b/readme.md index e2c58d5..3b2a26a 100644 --- a/readme.md +++ b/readme.md @@ -84,7 +84,7 @@ parameters: **Subject narrowing after match** — inside `if (Strings::match($s, '#\d+#'))` the subject `$s` is narrowed (e.g. to `non-empty-string`) based on the pattern. -**Assert type narrowing** — PHPStan understands type guarantees after `Tester\Assert` calls like `notNull()`, `type()`, `true()`, etc. +**Assert type narrowing** — PHPStan understands type guarantees after `Tester\Assert` calls like `notNull()`, `type()`, `true()`, etc. Code after `Assert::fail()` is treated as unreachable. **False positive suppression** — silences known PHPStan false positives in Nette patterns (arrow functions passed as `void` callbacks, runtime type validation closures, callbacks assigned to Form event-handler properties like `$onSuccess`, `$onClick`). diff --git a/src/Tester/TypeAssert.php b/src/Tester/TypeAssert.php index 67a3534..3b273dc 100644 --- a/src/Tester/TypeAssert.php +++ b/src/Tester/TypeAssert.php @@ -144,7 +144,6 @@ private static function processAssertTypeCall(Node $node, Scope $scope): ?array $expectedType->describe(VerbosityLevel::precise()), $node->getStartLine(), )); - return null; } $actualType = $scope->getType($node->getArgs()[1]->value); diff --git a/tests/Tester/assert-type-narrowing.php b/tests/Tester/assert-type-narrowing.php index fb5824e..7500c37 100644 --- a/tests/Tester/assert-type-narrowing.php +++ b/tests/Tester/assert-type-narrowing.php @@ -142,3 +142,12 @@ function testTypeInterface(mixed $val): void Assert::type(Countable::class, $val); assertType('Countable', $val); } + + +function testFailTerminates(?int $val): void +{ + if ($val === null) { + Assert::fail('must not be null'); + } + assertType('int', $val); +}