Tests¶

The analyzer types PHPUnit assertions, mocks and Prophecy doubles. The checks report assertions that always pass, doubles that a type or a docblock gets wrong, and mistakes in Drupal's test classes. The phpunit plugin does the PHPUnit and Prophecy work and depends on nothing in Drupal. The drupal plugin has the checks for Drupal's test classes.

Emptiness assertions¶

PHPUnit 11 puts @phpstan-assert on assertTrue(), assertFalse(), assertNull(), assertNotNull(), assertInstanceOf(), assertSame() and the assertIs*() family, and Mago reads it, so those assertions narrow the value on their own. assertNotEmpty() and assertEmpty() don't have such a tag, and Drupal's tests use those two a lot. A loaded entity then stays nullable for the rest of the test, and every call on it is reported.

The phpunit plugin narrows the value for these two: after assertNotEmpty() it isn't empty, and after assertEmpty() it is empty.

Not narrowed:

• a Countable, Traversable or plain object value after assertEmpty(). PHPUnit counts such an object, so an empty collection passes the assertion.

$node = Node::load(1);
$this->assertNotEmpty($node);
$node->label();            // narrowed, no possible-method-access-on-null

Mock unions¶

Drupal's older tests document a mock as @var X|MockObject, from before PHP had intersection types. Mago checks each half of a union on its own, so expects() is missing on X, and the call comes back as mixed, which loses the type of the rest of the chain. phpstan-phpunit reads the union as X&MockObject. A hook for that doesn't exist in Mago, and a provider type on the property would count as a magic property, so the phpunit plugin types the two methods on X instead.

Typed, as InvocationMocker:

• expects() with one argument, which is checked by Mago against InvocationOrder;
• method() with a string literal that names a method of the type.

The plugin answers only when the type doesn't declare the method, and it sees that one type, not the union.

Not typed:

• PHPUnit's own types, so expects() on the Stub half of an X|Stub union or on a MockBuilder is still reported.

/** @var \Drupal\Core\Extension\ModuleHandlerInterface|\PHPUnit\Framework\MockObject\MockObject */
protected $moduleHandler;

$this->moduleHandler->expects($this->once())->method('invokeAll')->willReturn([]);  // no issues

Since the plugin never sees the union, it also answers when the type is X alone. phpunit/mock-call-on-plain-type reports those calls.

A union mock passed where the mocked type goes is accepted too. Mago checks each member of the union against the parameter and reports the MockObject half as possibly-invalid-argument. The plugin drops that report when every other member of the union is the expected type or a class that fits it. A null member is left to possibly-null-argument, and any other member keeps the report. Core 11.4's UnitTestCase::getStringTranslationStub() returns such a union too.

$this->worker->setStringTranslation($this->getStringTranslationStub());  // no issues

The other direction stays reported. Calling invokeAll() on the union still reports it missing on MockObject, once per call and with the type of the call intact, since the plugin never sees X from that side. A typed chain also lets Mago check calls that stay unchecked on mixed, such as with() after method() on a stub, which PHPUnit's InvocationStubber doesn't have.

Prophecy calls¶

$prophecy->getFoo() on an ObjectProphecy<Foo> goes through __call(), which returns a MethodProphecy. Mago reports every such call as undocumented, since the class doesn't have a @method tag for it. The phpunit plugin types the call as a MethodProphecy when the prophesized class declares the method, or when the class isn't known. A method that the class lacks stays reported, since Prophecy throws for it.

$storage = $this->prophesize(EntityStorageInterface::class);
$storage->load(1)->willReturn($node);  // MethodProphecy, no non-documented-method
$storage->notAMethod();                // still reported

A prophecy documented as a union with its class, such as @var Foo|ObjectProphecy, is typed half by half. The bare ObjectProphecy doesn't name a class, so its half gets a MethodProphecy. A ProphecyInterface half doesn't have such a method at all. The Foo half gets the result of the real method, although a prophecy is never a Foo. phpunit/prophecy-union reports the docblock.

willImplement() and willExtend() declare @phpstan-this-out static<T&U>, which isn't applied by Mago (mago#2395). The plugin adds the type that they name to the prophecy: through the return type for a chain, and by narrowing the variable for a call on one. A prophecy told to implement an interface inside an if is a union afterwards, and a later call adds its type to each member.

$block = $this->prophesize(BlockPluginInterface::class);
$block->willImplement(PreviewFallbackInterface::class);
$block->getPreviewFallbackString()->willReturn('Placeholder');  // found on the added interface

When an interface extends Traversable but neither Iterator nor IteratorAggregate, Prophecy makes its double an Iterator. The plugin accepts current(), key(), next(), rewind() and valid() on such a prophecy.

$items = $this->prophesize(FieldItemListInterface::class);
$items->valid()->willReturn(TRUE, FALSE);  // added by Prophecy, no non-documented-method

phpunit/redundant-assertion¶

• Level: warning
• Source: phpstan-phpunit

phpstan-phpunit reports a PHPUnit assertion that always passes, given the type of the value. Such an assertion doesn't test anything.

Reports:

• an assertion that the type of its value already guarantees, such as assertTrue(TRUE), or assertInstanceOf() on a value already typed as that class.

The check covers assertInstanceOf(), assertNotNull(), assertNull(), assertTrue(), assertFalse(), assertNotTrue(), assertNotFalse(), and assertIsArray(), assertIsBool(), assertIsFloat(), assertIsInt(), assertIsNumeric(), assertIsObject(), assertIsScalar() and assertIsString(). A type from a docblock counts, and so does one supplied by the plugins, such as the class of a service from a services file.

Not reported:

Mago types some values more narrowly than the code behaves, and these are left alone:

• $this->name, unless the native type of the property passes the assertion too. Mago keeps the narrowed type of a property across calls that may change it, such as a callback that sets $this->fired. A property typed only by @var never counts: PHP doesn't check the tag, and the property is NULL until something is assigned. A magic property, which doesn't have a declaration, never counts either;
• another object's property, $other->name, since the check doesn't know the class of that object;
• a variable that an inline @var tag names in the same method. The tag is the test's own claim, often over a load() that can return NULL, and the assertion is what checks it at runtime;
• a variable that a static or global statement in the file declares. Its value can come from an earlier call or change elsewhere, which isn't followed by Mago;
• $items[0], since Mago's ArrayAccess stub types offsetGet() without null, while an empty field item list returns null;
• isset(), which tests __isset() or ArrayAccess rather than a type;
• any of these behind a !;
• an assertion that can never pass. When the value is a variable, Mago reports it as impossible-type-comparison, and otherwise it isn't reported.

// Reported.
namespace Drupal\Tests\example\Unit;

use PHPUnit\Framework\TestCase;

final class ExampleTest extends TestCase {

  public function testNames(): void {
    $names = $this->names();
    $this->assertIsArray($names);
  }

  /**
   * @return list<string>
   */
  private function names(): array {
    return ['a', 'b'];
  }

}

// Fine.
namespace Drupal\Tests\example\Unit;

use PHPUnit\Framework\TestCase;

final class ExampleTest extends TestCase {

  public function testNames(): void {
    $names = $this->names();
    $this->assertNotEmpty($names);
  }

  /**
   * @return list<string>
   */
  private function names(): array {
    return ['a', 'b'];
  }

}

phpunit/mock-call-on-plain-type¶

• Level: warning
• Source: PHPStan

A mock typed as the mocked class alone, without MockObject, doesn't have expects() or method() for Mago. The mock union types answer for such a call all the same, since they see one type at a time. This check sees the whole type of the value and reports the call: the value is a mock at runtime, but the property, parameter or return type that it comes from leaves MockObject out. PHPStan reports the same calls as undefined methods.

Reports:

• an expects() or method() call on a value whose type doesn't name a PHPUnit class or declare the method. The check takes an expects() call with one argument, and a method() call that names a method of the type.

Not reported:

• a value whose type includes a PHPUnit type, such as X|MockObject or X&MockObject;
• any other call, which stays Mago's own report of a missing method.

namespace Drupal\example;

interface GreeterInterface {

  public function greet(): string;

}

// Reported.
namespace Drupal\Tests\example\Unit;

use Drupal\example\GreeterInterface;
use PHPUnit\Framework\TestCase;

final class GreeterTest extends TestCase {

  /**
   * @var \Drupal\example\GreeterInterface
   */
  protected $greeter;

  protected function setUp(): void {
    $this->greeter = $this->createMock(GreeterInterface::class);
  }

  public function testGreet(): void {
    $this->greeter->expects($this->once())->method('greet');
  }

}

// Fine.
namespace Drupal\Tests\example\Unit;

use Drupal\example\GreeterInterface;
use PHPUnit\Framework\TestCase;

final class GreeterTest extends TestCase {

  /**
   * @var \Drupal\example\GreeterInterface&\PHPUnit\Framework\MockObject\MockObject
   */
  protected $greeter;

  protected function setUp(): void {
    $this->greeter = $this->createMock(GreeterInterface::class);
  }

  public function testGreet(): void {
    $this->greeter->expects($this->once())->method('greet');
  }

}

phpunit/prophecy-union¶

• Level: warning
• Source: Prophecy's own types

A prophecy is never an instance of the class that it prophesizes, so a type that unions the two is wrong. Calls on such a value, and the calls chained on them, are reported on one half or the other, far from the docblock that causes them. The check reports the docblock once, with the type to use instead, ObjectProphecy<Foo>.

Reports:

• a docblock type that unions ProphecyInterface or ObjectProphecy with another class. The check reads the @var, @param and @return tags of properties, parameters and return types in a class or a trait.

// Reported.
namespace Drupal\Tests\example\Unit;

use PHPUnit\Framework\TestCase;

final class ExampleTest extends TestCase {

  /**
   * @var \Drupal\Core\Extension\ModuleHandlerInterface|\Prophecy\Prophecy\ProphecyInterface
   */
  protected $moduleHandler;

}

// Fine.
namespace Drupal\Tests\example\Unit;

use PHPUnit\Framework\TestCase;

final class ExampleTest extends TestCase {

  /**
   * @var \Prophecy\Prophecy\ObjectProphecy<\Drupal\Core\Extension\ModuleHandlerInterface>
   */
  protected $moduleHandler;

}

drupal/test-modules-visibility¶

• Level: error
• Source: phpstan-drupal
• Ports: phpstan-drupal's TestClassesProtectedPropertyModulesRule

phpstan-drupal reports a test class whose $modules property is public. Drupal's test bases declare it protected, see the change record.

Reports:

• a public $modules property, static or not, typed or not, declared in a class that descends from PHPUnit's TestCase.

Not reported:

• a $modules that the class inherits from a parent or gets from a trait. The class that declares it is the one to fix.

drupal/browser-test-default-theme¶

• Level: error
• Source: phpstan-drupal
• Ports: phpstan-drupal's BrowserTestBaseDefaultThemeRule

phpstan-drupal reports a functional test that doesn't set $defaultTheme. When the install profile of the test doesn't install a theme, Drupal throws while it sets up the test.

Reports:

• a browser test on a themeless profile that doesn't set $defaultTheme. The test is a concrete BrowserTestBase descendant whose name ends in Test, and the property counts when it is set on the class, on a base class, or by a trait that either of them uses.

The check finds the test's $profile the same way, on the class, a base class or a trait. A profile is themeless when it doesn't ship a system.theme config in config/sync or config/install, which is checked by Drupal when the test runs. Profiles are read from core, from the site's profiles directory, and from the tests/profiles directories of core's modules and of extensions. A profile not found there counts as themeless when it is one of core's themeless test profiles, such as testing.

Not reported:

• a class that overrides installDefaultThemeFromClassProperty(), itself, through a base class or through a trait, since the override may set the theme at runtime;
• a class that assigns $this->defaultTheme itself, such as in setUp();
• update path tests, which install from a database dump;
• a test on a NULL or FALSE profile, which installs from existing configuration and takes its theme;
• a profile that isn't a string literal, such as one read from a constant.

// Reported.
namespace Drupal\Tests\example\Functional;

use Drupal\Tests\BrowserTestBase;

final class ExampleTest extends BrowserTestBase {

  public function testPage(): void {}

}

// Fine.
namespace Drupal\Tests\example\Functional;

use Drupal\Tests\BrowserTestBase;

final class ExampleTest extends BrowserTestBase {

  /**
   * {@inheritdoc}
   */
  protected $defaultTheme = 'stark';

  public function testPage(): void {}

}

drupal/component-test-core-base¶

• Level: error
• Source: Drupal core's PHPStan rules
• Ports: core's ComponentTestDoesNotExtendCoreTest rule

Core's component tests run without Drupal, so they can't extend a test base that boots Drupal or needs its classes. Core's own PHPStan rules report a component test that does.

Reports:

• a class in the Drupal\Tests\Component namespace that extends UnitTestCase, KernelTestBase, BuildTestBase or BrowserTestBase, directly or through its parents.

WebDriverTestBase counts, since it extends BrowserTestBase. The report is on the class whose own parent lies outside the component tests. So a component test base that extends a core one is reported once, and not again on the tests below it.

drupal/test-class-name¶

• Level: error
• Source: phpstan-drupal
• Ports: phpstan-drupal's TestClassSuffixNameRule, the part that needs the class's ancestry

PHPUnit runs only the files named *Test.php, and so do phpunit -c core and run-tests.sh, so a test class whose name doesn't end in Test never runs. The lint rule drupal/test-class-suffix reports most of them from the parent's name, with no types. The check reports the ones that the lint rule can't tell apart from other classes.

Reports:

• a concrete class that descends from PHPUnit's TestCase, whose name doesn't end in Test, and that drupal/test-class-suffix doesn't take for a test. That is a class outside the lint rule's test directories, such as one directly in tests/src or in src, a class whose parent's name doesn't end in Test, TestBase or TestCase, and a class whose parent is declared in the same file without such a parent of its own.

Not reported:

• a class that the lint rule reports, so a class gets one report when both run;
• an abstract class and an anonymous class.

namespace Drupal\Tests\example\Unit;

use Drupal\Tests\UnitTestCase;

abstract class ExampleUnitBase extends UnitTestCase {
}

// Reported.
namespace Drupal\Tests\example\Unit;

final class ExampleChecks extends ExampleUnitBase {
}

// Fine.
// The class and its file are named ExampleChecksTest.
namespace Drupal\Tests\example\Unit;

final class ExampleChecksTest extends ExampleUnitBase {
}