From 927cf58d344a11f202b0241df5231c6f8472139b Mon Sep 17 00:00:00 2001
From: Michael Telgmann <m.telgmann@shopware.com>
Date: Fri, 21 Aug 2026 11:28:40 +0200
Subject: [PATCH] feat: Discourage assert(Not)Empty if "empty" usage is
 disallowed

fixes: https://github.com/phpstan/phpstan-phpunit/issues/270
---
 README.md                                     |  1 +
 rules.neon                                    |  5 ++
 .../PHPUnit/AssertEmptyIsDiscouragedRule.php  | 62 +++++++++++++++++++
 .../AssertEmptyIsDiscouragedRuleTest.php      | 31 ++++++++++
 .../data/assert-empty-is-discouraged.php      | 23 +++++++
 5 files changed, 122 insertions(+)
 create mode 100644 src/Rules/PHPUnit/AssertEmptyIsDiscouragedRule.php
 create mode 100644 tests/Rules/PHPUnit/AssertEmptyIsDiscouragedRuleTest.php
 create mode 100644 tests/Rules/PHPUnit/data/assert-empty-is-discouraged.php

diff --git a/README.md b/README.md
index c86df268..34f69785 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,7 @@ It also contains this strict framework-specific rules (can be enabled separately
 * Check that you are not using `assertSame()` with `count($variable)` as second parameter. `assertCount($variable)` should be used instead.
 * Check that you are not using `assertEquals()` with same types (`assertSame()` should be used)
 * Check that you are not using `assertNotEquals()` with same types (`assertNotSame()` should be used)
+* When PHPStan Strict Rules' `disallowedEmpty` rule is enabled, disallow PHPUnit's `assertEmpty()` and `assertNotEmpty()` assertions as well.
 
 ## How to document mock objects in phpDocs?
 
diff --git a/rules.neon b/rules.neon
index 9d2d9477..d194cf32 100644
--- a/rules.neon
+++ b/rules.neon
@@ -12,6 +12,8 @@ rules:
 conditionalTags:
 	PHPStan\Rules\PHPUnit\AssertEqualsIsDiscouragedRule:
 		phpstan.rules.rule: [%strictRulesInstalled%, %featureToggles.bleedingEdge%]
+	PHPStan\Rules\PHPUnit\AssertEmptyIsDiscouragedRule:
+		phpstan.rules.rule: %strictRulesInstalled%
 
 	PHPStan\Rules\PHPUnit\DataProviderDataRule:
 		phpstan.rules.rule: %featureToggles.bleedingEdge%
@@ -39,5 +41,8 @@ services:
 	-
 		class: PHPStan\Rules\PHPUnit\AssertEqualsIsDiscouragedRule
 
+	-
+		class: PHPStan\Rules\PHPUnit\AssertEmptyIsDiscouragedRule
+
 	-
 		class: PHPStan\Rules\PHPUnit\DataProviderDataRule
diff --git a/src/Rules/PHPUnit/AssertEmptyIsDiscouragedRule.php b/src/Rules/PHPUnit/AssertEmptyIsDiscouragedRule.php
new file mode 100644
index 00000000..02d80f87
--- /dev/null
+++ b/src/Rules/PHPUnit/AssertEmptyIsDiscouragedRule.php
@@ -0,0 +1,62 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\PHPUnit;
+
+use PhpParser\Node;
+use PhpParser\Node\Expr\CallLike;
+use PhpParser\Node\Expr\FuncCall;
+use PhpParser\Node\Expr\MethodCall;
+use PhpParser\Node\Expr\StaticCall;
+use PhpParser\Node\Identifier;
+use PhpParser\Node\Name;
+use PHPStan\Analyser\Scope;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+use function count;
+use function in_array;
+use function sprintf;
+use function strtolower;
+
+/**
+ * @implements Rule<CallLike>
+ */
+class AssertEmptyIsDiscouragedRule implements Rule
+{
+
+	public function getNodeType(): string
+	{
+		return CallLike::class;
+	}
+
+	public function processNode(Node $node, Scope $scope): array
+	{
+		if ($node->isFirstClassCallable() || count($node->getArgs()) < 1) {
+			return [];
+		}
+
+		if ($node instanceof MethodCall || $node instanceof StaticCall) {
+			if (!$node->name instanceof Identifier || !in_array($node->name->toLowerString(), ['assertempty', 'assertnotempty'], true)) {
+				return [];
+			}
+			if (!AssertRuleHelper::isMethodOrStaticCallOnAssert($node, $scope)) {
+				return [];
+			}
+		} elseif ($node instanceof FuncCall) {
+			if (!$node->name instanceof Name || !in_array(strtolower($scope->resolveName($node->name)), ['phpunit\\framework\\assertempty', 'phpunit\\framework\\assertnotempty'], true)) {
+				return [];
+			}
+		} else {
+			return [];
+		}
+
+		return [
+			RuleErrorBuilder::message(sprintf(
+				'%s() is not allowed. Use more strict assertion.',
+				$node instanceof FuncCall ? $node->name->getLast() : $node->name->toString(),
+			))
+				->identifier('empty.notAllowed')
+				->build(),
+		];
+	}
+
+}
diff --git a/tests/Rules/PHPUnit/AssertEmptyIsDiscouragedRuleTest.php b/tests/Rules/PHPUnit/AssertEmptyIsDiscouragedRuleTest.php
new file mode 100644
index 00000000..f2503b57
--- /dev/null
+++ b/tests/Rules/PHPUnit/AssertEmptyIsDiscouragedRuleTest.php
@@ -0,0 +1,31 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\PHPUnit;
+
+use PHPStan\Rules\Rule;
+use PHPStan\Testing\RuleTestCase;
+
+/**
+ * @extends RuleTestCase<AssertEmptyIsDiscouragedRule>
+ */
+final class AssertEmptyIsDiscouragedRuleTest extends RuleTestCase
+{
+
+	public function testRule(): void
+	{
+		$this->analyse([__DIR__ . '/data/assert-empty-is-discouraged.php'], [
+			['assertEmpty() is not allowed. Use more strict assertion.', 15],
+			['assertNotEmpty() is not allowed. Use more strict assertion.', 16],
+			['assertEmpty() is not allowed. Use more strict assertion.', 17],
+			['assertNotEmpty() is not allowed. Use more strict assertion.', 18],
+			['assertEmpty() is not allowed. Use more strict assertion.', 19],
+			['assertNotEmpty() is not allowed. Use more strict assertion.', 20],
+		]);
+	}
+
+	protected function getRule(): Rule
+	{
+		return new AssertEmptyIsDiscouragedRule();
+	}
+
+}
diff --git a/tests/Rules/PHPUnit/data/assert-empty-is-discouraged.php b/tests/Rules/PHPUnit/data/assert-empty-is-discouraged.php
new file mode 100644
index 00000000..8a90fb9e
--- /dev/null
+++ b/tests/Rules/PHPUnit/data/assert-empty-is-discouraged.php
@@ -0,0 +1,23 @@
+<?php declare(strict_types = 1);
+
+namespace AssertEmptyIsDiscouragedTest;
+
+use PHPUnit\Framework\Assert;
+use PHPUnit\Framework\TestCase;
+use function PHPUnit\Framework\assertEmpty;
+use function PHPUnit\Framework\assertNotEmpty;
+
+final class AssertEmptyTest extends TestCase
+{
+
+	public function test(): void
+	{
+		$this->assertEmpty([]);
+		$this->assertNotEmpty([1]);
+		Assert::assertEmpty([]);
+		static::assertNotEmpty([1]);
+		assertEmpty([]);
+		assertNotEmpty([1]);
+	}
+
+}