No Tests Found For Given Includes

You’ve written your tests, you’re ready to run them, but then you see this cryptic message:

No tests found for given includes.

It’s one of those PHPUnit errors that feels like it’s mocking you. In real terms, you can see them in your editor. You know your tests exist. But when you run .That's why /vendor/bin/phpunit, nothing happens. Or worse, you get a partial output that makes you question your entire test suite.

This isn’t just a minor hiccup—it can derail your workflow, delay releases, and leave you staring at a blank terminal wondering what went wrong. Let’s break down what’s really going on here, why it happens, and how to fix it for good.

What Is the Error?

At its core, “No tests found for given includes” is PHPUnit’s way of saying it can’t locate any valid test methods in the files you’ve told it to run. PHPUnit scans your test directories, looks for classes that extend PHPUnit\Framework\TestCase, and then searches for methods that start with test or are annotated with @test. If it can’t find any of those, it throws this error.

The Core Issue

PHPUnit doesn’t just scan for any file named Test.php. It has strict rules about what constitutes a test.

• Be in a directory PHPUnit is configured to scan (usually tests/ or test/).
• Contain a class that extends PHPUnit\Framework\TestCase.
• Have at least one method that starts with test or has the @test annotation.

When you use the @group annotation to organize tests, PHPUnit still needs to find valid test methods. If the group you’re referencing doesn’t contain any matching tests, you’ll see this error.

Common Scenarios

This error pops up most often in these situations:

• You’re running tests with --group and the group name doesn’t match any tests.
• You’ve accidentally excluded test files from your configuration.
• Your test files are in the wrong directory or named incorrectly.
• The test methods themselves have visibility issues (like being private instead of public).

Why It Matters

If you’re spending time debugging this error, it’s not just about fixing a configuration hiccup. And it’s about ensuring your test suite is reliable and comprehensive. When PHPUnit can’t find tests, you’re potentially missing critical coverage. And in a CI/CD pipeline, this error can halt deployments or give a false sense of security.

Impact on Development Workflow

Imagine you’re preparing for a release. You run your tests locally, everything passes, and you push your code. But in CI, the build fails because PHPUnit couldn’t find any tests in a specific group. You waste hours debugging, only to realize a file was misnamed or a method was accidentally made private.

Real-World Consequences

I’ve seen teams delay releases because they didn’t catch this error early. That said, in one case, a developer added new tests but forgot to make the methods public. So the tests ran fine in their IDE, but PHPUnit skipped them entirely. The bug made it to production because the test suite gave a false green light.

How It Happens

Let’s dig into the technical weeds a bit. PHPUnit uses a combination of file scanning, reflection, and configuration to locate tests. When something goes wrong, it’s usually due to a mismatch between what you expect and what PHPUnit is actually doing.

Annotation Misuse

The @group annotation is powerful, but it’s easy to misuse. If you write:

/**
 * @group critical
 */
public function testUserCanLogin()
{
    // ...
}

But then run .But /vendor/bin/phpunit --group critical, PHPUnit will look for any test in the critical group. If the annotation is misspelled (like @gropu or missing the @), PHPUnit won’t find it.

Visibility Issues

This one catches everyone at least once. Test methods must be public. If you accidentally change:

public function testSomethingImportant()
{
    // ...
}

to:

protected function testSomethingImportant()
{
    // ...
}

PHPUnit will skip it entirely. But no error, no warning—just silence. That’s why this error can be so sneaky.

File Naming Problems

PHPUnit expects test files to follow certain naming conventions. In practice, while it’s flexible, the default is that files should end with Test. php. So UserTest.And php is fine, but User_tests. php might not be picked up unless you explicitly configure it.

Configuration Errors

Your phpunit.xml.On the flip side, xml or phpunit. dist file tells PHPUnit where to look.

If you haven’t set up an explicit tests directory, PHPUnit may still search elsewhere depending on its discovery patterns. Still, a common oversight is leaving the phpunit. xml without a <tests> folder reference, which forces the runner to scan the entire project by default.

    src/tests
    *.Test.php

You can also tighten the configuration by disabling the automatic detection of groups when you deliberately want to run only a subset. Take this: if you have several functional, integration, and performance groups, you might limit the command line to:

./vendor/bin/phpunit --group unit

which ensures that only tests annotated with @group unit are executed, while preserving confidence that nothing else is silently ignored.

Another frequent culprit is an incomplete autoloader setup. If your test classes rely on namespaces or third‑party libraries that aren’t loaded via Composer’s require or a custom use statement, PHPUnit will treat those classes as unavailable rather than as hidden implementation details. Adding the necessary imports at the top of each test file—or installing the missing packages through composer require—prevents “Class not found” exceptions from masquerading as “no tests discovered”.

Don’t forget the role of the bootstrap phase. The phpunit.Worth adding: xml often contains a <autoRun> block that loads extensions before the test suite starts. If a required extension (e.On top of that, g. On the flip side, , phpunit-extl-xml for XML reporting) isn’t enabled or fails to load due to a version conflict, PHPUnit may abort early, leaving you with an empty test list despite having valid test files. Verify that all extensions needed for your workflow are declared under <extensions> and that their versions match what your project requires.

Finally, consider the impact of environment differences. Running the same test suite locally versus in a containerized CI environment can reveal subtle mismatches in the operating system, PATH, or even PHP version. A quick sanity check involves executing php -a both places; a divergence here can cause the test runner to behave unexpectedly, especially when it relies on external binaries like ffmpeg for media‑related tests.

Boiling it down, the “Cannot find tests” error is rarely a mysterious mystery—it usually stems from one of three categories: mis‑configured test directories, incorrect visibility declarations (public vs. protected), or broken discovery settings within phpunit.By systematically reviewing these areas—adding explicit test folders, enforcing public visibility, tightening group annotations, and confirming autoloading and bootstrap integrity—you eliminate the blind spots that let flaky or non‑existent tests slip through unnoticed. Practically speaking, xml. This disciplined approach not only resolves the immediate issue but also builds a strong testing foundation that scales with your codebase, keeps your CI pipelines honest, and ultimately delivers higher‑quality software.

Want to learn more? We recommend why does an ice cube melt and how many centimeters is a dollar bill for further reading.

Dive Deeper into Each Root Cause

1. Mis‑configured test directories

• Folder layout matters – PHPUnit walks the directory tree looking for files that match the default pattern Test.php (or a custom pattern you define in <testsuites>). If your tests live in src/Tests or a nested folder such as tests/Unit/Integration, the scanner may never reach them.
• Naming conventions – The class name must end with Test (e.g., UserRepositoryTest). A mismatch between the file name and the class name creates a silent “no tests discovered” situation.
• Recursive scanning – By default PHPUnit descends into sub‑directories, but you can limit the depth with the <directory> element. An overly restrictive <directory> entry (e.g., pointing only to tests/Unit) will hide tests placed elsewhere.
• Quick sanity check – Run ./vendor/bin/phpunit --list-tests from the project root. The output lists every test class that the loader has found; if your expected class is absent, the directory configuration is the likely culprit.

2. Visibility declarations (public vs. protected)

• Method visibility – Only public methods are considered test cases. A protected or private method, even if annotated with @test, will be ignored.
• Class visibility – The test class itself must be public (or at least class‑level visibility that allows instantiation). A final class with a private constructor can still be instantiated by PHPUnit, but if the constructor throws an exception before the test method runs, the test may appear “missing” because the runner aborts early.
• Explicit annotation – Adding @test (or @doesNotPerformAssertions) on a public method makes the intention crystal‑clear and helps static analysis tools flag accidental visibility changes.
• Tip – When you generate a test skeleton with an IDE, verify that the method signature reads public function testSomething(): void.

3. Broken discovery settings in phpunit.xml

• <testsuites> definition – If you have more than one test suite, each suite can point to a different directory or set its own exclusions. An accidental <exclude> pattern (e.g., <exclude>*/Integration/*</exclude>) can hide whole directories.
• <directory> entries – Verify that the path you provide actually exists relative to the location of phpunit.xml. A typo such as tests/ vs. test/ will cause PHPUnit to scan an empty folder.
• Group filters – The --group CLI option (or the <group> element in the XML) can unintentionally filter out all tests if the annotated class does not match the specified group. Double‑check that the group name you pass on the command line matches the one in the annotation.
• XML reporting extensions – If you enable <extensions><phpunit‑extl‑xml/></extensions> but the extension is not installed or its version conflicts with your PHP version, the bootstrap may fail before any test discovery occurs.

Practical Debugging Workflow

1. Run with verbose output

   ./vendor/bin/phpunit --verbose
   

   The log will show which directories are scanned, which files are loaded, and whether any errors abort the bootstrap.

2. List discovered tests

   ./vendor/bin/phpunit --list-tests
   

   If your expected test class does not appear, the problem lies in discovery (directory, naming, or autoload).

3. Validate autoload
   Execute composer dump-autoload -o to regenerate the optimized autoloader cache, then re‑run the list‑tests command.

4. Check bootstrap inclusion
   Ensure the <bootstrap> element in phpunit.xml points to a file that successfully loads all required dependencies (e.g., a bootstrap.php that runs require_once 'vendor/autoload.php';). A missing require will cause “class not found” errors that surface as “no tests discovered”.

5. Confirm environment parity
   Run php -v and php -i | grep extension_dir inside the same container or shell where the CI job executes. Mismatched PHP versions or missing extensions (e.g., intl, xml) can prevent the bootstrap from completing, resulting in an empty test list.

Checklist for a Reliable Test Discovery Setup

• [ ] Test files reside under a directory covered by <testsuites><directory>.
• [ ] Each test class file name ends with Test.php and the class name ends with Test.
• [ ] All test methods are public and annotated with @test.
• [ ] The test class itself is public (or at least instantiable).
• [ ] No unintended <exclude> patterns in <testsuites> or <phpunit> sections.
• [ ] Composer autoloader is up‑to‑date (composer dump-autoload).
• [ ] Bootstrap file loads the autoloader and any required extensions without error.
• [ ] phpunit.xml is located in the project root (or the directory from which you invoke the command).
• [ ] CI environment uses the same PHP version, extensions, and working directory as your local machine.

Final Thoughts

When “Cannot find tests” surfaces, the answer is almost always rooted in a configuration mismatch rather than a mysterious bug. By systematically verifying directory placement, method visibility, and the exact parameters of the discovery engine, you eliminate the hidden gaps that let flaky or absent tests slip through.

Adopting the checklist above not only resolves the immediate error but also establishes a repeatable, team‑wide process that keeps your test suite healthy as the codebase evolves. With a solid discovery foundation, your CI pipelines stay honest, developers gain rapid feedback, and the confidence in your software’s correctness grows proportionally.