PHPUnit: assertInstanceOf() not working when passing type as second argument as non-string
A common stumbling block when writing PHPUnit tests involves the assertInstanceOf() method. Developers often confuse how to pass the expected class name versus the actual instance being tested. The specific error pattern describedâwhere a test fails with "use of undefined constant" while attempting to check if a variable is an object of a specific typeâusually stems from a misunderstanding of the method's argument order and PHP's scoping rules regarding constants.
The core issue lies in how assertInstanceOf() interprets its second parameter. When you write $this->assertInstanceOf($user, User), you are inadvertently passing the instance as the first argument and a raw identifier as the second. The PHPUnit method signature expects the expected type (usually a string class name) in the first position and the actual instance in the second. By swapping them, you force PHPUnit to treat your $user object variable as the "expected" type and the literal identifier User as the object to check.
In PHP, identifiers like User are treated as constants unless they are enclosed in quotes or explicitly defined as a class name string. When PHPUnit encounters assertInstanceOf($user, User), it attempts to resolve User as a constant. If you haven't declared define('User', 'App\Models\User') or similar, PHP assumes the identifier is undefined. This triggers the specific error message: "use of undefined constant User - assumed 'User'". The test framework then tries to cast this non-existent constant into the expected type check, leading to a confusing failure state that doesn't clearly indicate the argument order was wrong.
Correct Argument Order
The method signature is strict about parameter positions:
public function assertInstanceOf($expectedType, $actual, string $message = '')
To verify that $user is an instance of the User class, the code must look like this:
$this->assertInstanceOf(User::class, $user);
Using User::class is preferred over 'User' because it provides a string at runtime without relying on constant definitions. This approach is robust against namespace changes and avoids the "undefined constant" pitfall entirely. If you are in a legacy context where string literals are acceptable, ensure they are quoted:
$this->assertInstanceOf('App\Models\User', $user);
However, mixing an object instance ($user) as the first argument is never valid for this assertion. The first argument must describe the type you expect to find, and the second must be the value you want to validate.
Type Hinting vs. Class Names
It is also worth noting that while PHP supports type hints in function definitions, assertInstanceOf() does not accept a class object (e.g., the result of new User()) as the expected type argument. It strictly requires a string representation of the class name or an interface/trait name. Attempting to pass the actual instance first is a logical error that leads directly to the constant resolution failure seen in the source material.
Practical Application
When refactoring tests, always verify the order of arguments before assuming the logic is flawed. If you find yourself debugging an "undefined constant" error inside a PHPUnit test, check if you accidentally passed a variable name or object instance where a string class name was expected. This is a frequent source of confusion when transitioning from dynamic typing checks to strict static assertions within the testing framework.
For teams utilizing modern PHP practices, leveraging User::class ensures type safety and eliminates ambiguity. If your project structure involves deep namespaces, passing a simple 'User' string might work only if the current namespace is implicitly correct, but User::class remains the most reliable pattern regardless of where the test file resides.