How to test if string contains another string in PHPUnit?

How to test if string contains another string in PHPUnit?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

How to test if string contains another string in PHPUnit

You might be searching for assertStringContains() because you are thinking of older PHPUnit versions. In PHPUnit 4 and 5, there was no built-in method specifically for checking substring containment. Developers often resorted to manual checks like strpos($needle, $haystack) !== false or even brittle regular expressions just to get the job done. That manual approach works perfectly fine in vanilla PHP, but it breaks the flow of writing clean unit tests where you want to focus on logic rather than string manipulation functions.

The confusion often stems from the fact that PHPUnit does provide assertStringStartsWith() and assertStringEndsWith(). These were added relatively early on because checking the beginning or end of a buffer is a very common validation pattern. The lack of a generic "contains" assertion initially made it feel like you had to write your own helper function or use regex, which contradicts the goal of keeping tests simple and readable.

Fortunately, if you are using PHPUnit 6.0 or later (released in 2017), assertStringContains() is now a standard part of the framework. The code snippet from the original query:

public function testRecipe() {
    $plaintext = get_bread_recipe();
    
    $this->assertStringContains('flour', $plaintext);
}

is not only valid but is exactly what you should use today. The method takes two arguments: the substring you are looking for and the string where you expect it to appear. It returns a boolean value internally, allowing PHPUnit to pass or fail the test case automatically. If 'flour' is found within $plaintext, the assertion passes. If not, it fails with a helpful message indicating what was expected versus what was actually found.

However, simply knowing the method exists isn't enough; you need to understand how it behaves under different conditions to avoid subtle bugs in your test suite. The primary consideration is case sensitivity. By default, assertStringContains() performs a case-sensitive comparison. This means that if your $plaintext variable contains "Flour" with a capital F and you are searching for "flour", the assertion will fail. While this might be what you want for strict string matching, it can be a pitfall when testing user-generated content or database fields that often mix casing.

If you need to ignore case differences, you have two main options. The first is to normalize both strings before asserting by using strtolower() on the inputs. This keeps your test logic inside the assertion line and avoids creating intermediate variables just for this check. Alternatively, if you are dealing with a scenario where case truly doesn't matter, you could construct a custom assertion helper that wraps this logic, though that often adds unnecessary abstraction for such a simple operation.

Another important detail is how the method handles null values. If your $plaintext variable is null, assertStringContains() will throw a TypeError in modern PHP versions because it expects string arguments. In legacy codebases or when testing optional data sources, you must ensure that the variable is cast to an empty string ('') if there is a possibility of it being null before passing it to the assertion. This prevents your test from crashing unexpectedly and instead allows PHPUnit to report a clear failure about the missing content.

While assertStringContains() covers 95% of use cases, there are moments when you might need more granular control over the match. For instance, if you need to verify that a substring appears exactly once or not just as part of a larger word, regular expressions become necessary again. But for standard containment checks, assertStringContains() provides a clean, declarative way to express intent without cluttering your test file with logic from strpos(). If you are building complex testing utilities or need this functionality in a Laravel application, checking the official documentation at https://laravelcompany.com can provide further context on how string assertions fit into broader validation strategies.

Our network