Run a Single PHPUnit Test Method with --filter

PHPUnit's --filter option limits execution to test names that match a pattern. In older PHPUnit versions, place command options before the test class and file arguments. You will also learn how filters use regular expressions, how to target a method reliably, and how to diagnose commands that unexpectedly run an entire test suite.

A PHPUnit test class usually contains many test methods. During everyday development, running the entire suite can be slow or distracting when you are working on one behavior.

The --filter command-line option tells PHPUnit to run only tests whose names match a pattern. For example, a method named testSaveAndDrop can be selected with:

phpunit --filter testSaveAndDrop EscalationGroupTest escalation/EscalationGroupTest.php

The important detail for PHPUnit 3.2.8 is argument order: put options such as --filter before positional arguments such as the class name and filename. When --filter appears after the test arguments, an older command-line parser may not treat it as an option. As a result, PHPUnit receives no active filter and runs all discovered tests.

A filter is a pattern, not necessarily an exact literal method lookup. This is useful when you want to run a family of tests, but it also means a broad pattern can match more methods than expected.

Think of a test file as a tray containing many labelled folders:

• testSaveAndDrop
• testCreateGroup
• testDeleteGroup

Running PHPUnit without a filter opens every folder. --filter is like giving PHPUnit a label-search rule before it starts opening folders.

The command-line options are instructions for the test runner, while the class and filename tell it where the tray is. In older PHPUnit versions, give the instructions first; otherwise, the runner may begin interpreting test targets and overlook the later instruction.

Use --filter before the test class and file arguments:

phpunit --filter testSaveAndDrop EscalationGroupTest escalation/EscalationGroupTest.php

This runs tests whose names contain testSaveAndDrop. If that name is unique, it runs one test method.

For example, given this test class:

<?php

class EscalationGroupTest extends PHPUnit_Framework_TestCase
{
    public function testSaveAndDrop()
    {
        $this->assertTrue(true);
    }

    public function testCreateGroup()
    {
        $this->assertTrue(true);
    }
}

Run only testSaveAndDrop:

phpunit --filter testSaveAndDrop EscalationGroupTest escalation/EscalationGroupTest.php

You can also run tests from the file without explicitly supplying the class when your PHPUnit setup supports file-based discovery:

phpunit --filter testSaveAndDrop escalation/EscalationGroupTest.php

Because --filter is pattern-based, use a distinctive method name. If several tests contain the same text, they can all match.

Consider this command:

phpunit --filter testSaveAndDrop EscalationGroupTest escalation/EscalationGroupTest.php

PHPUnit processes it in this order:

1. phpunit starts the PHPUnit command-line runner.
2. --filter testSaveAndDrop stores a filter pattern before PHPUnit begins selecting tests.
3. EscalationGroupTest identifies the test class to load.
4. escalation/EscalationGroupTest.php identifies the file containing that class.
5. PHPUnit discovers methods that PHPUnit recognizes as tests, such as methods beginning with test.
6. PHPUnit compares each discovered test name with testSaveAndDrop.
7. testSaveAndDrop matches and runs.
8. Methods such as testCreateGroup do not match and are skipped.

By contrast, this older-style command can fail to apply the option as intended:

phpunit EscalationGroupTest escalation/EscalationGroupTest.php --filter=testSaveAndDrop

The class and file appear first. With older argument parsing behavior, PHPUnit may treat them as the end of the option section, leaving the filter ineffective.

Running one test method is useful when:

• Fixing a bug: repeatedly run the regression test that demonstrates the bug while changing production code.
• Writing a new feature: focus on the one test currently being implemented before running the complete suite.
• Debugging a failure: rerun one failing test with extra output such as --debug.
• Working with slow integration tests: avoid repeatedly creating databases, making HTTP calls, or loading large fixtures for unrelated tests.
• Investigating flaky tests: execute a single test repeatedly to determine whether it fails inconsistently.

For example:

phpunit --filter testSaveAndDrop --debug EscalationGroupTest escalation/EscalationGroupTest.php

The --debug option can help show which test PHPUnit is currently executing.

In real projects, developers commonly combine a focused test run with a broader verification step.

A typical workflow is:

# Fast feedback while implementing or debugging one behavior
phpunit --filter testSaveAndDrop EscalationGroupTest escalation/EscalationGroupTest.php

# Broader confidence before committing changes
phpunit

Useful conventions make filtering easier:

• Give tests descriptive, unique names such as testSaveAndDropRemovesTheGroupFromStorage.
• Keep a test focused on one observable behavior.
• Use a small test file or class for a cohesive unit of behavior.
• Add a regression test whenever a bug is fixed, then use its name as the filter during the fix.

Developers also use filters to run a group of related tests. For example, a shared name prefix can select several persistence tests:

phpunit --filter testSave EscalationGroupTest escalation/EscalationGroupTest.php

This can match testSave, testSaveAndDrop, and testSaveWithInvalidData, so use it only when that broader selection is intentional.

Putting --filter after test arguments

In PHPUnit 3.2.8, options should come first.

# Risky with older PHPUnit command-line parsing
phpunit EscalationGroupTest escalation/EscalationGroupTest.php --filter=testSaveAndDrop

Use:

phpunit --filter testSaveAndDrop EscalationGroupTest escalation/EscalationGroupTest.php

Expecting an exact match from a broad pattern

A filter is pattern-based. This command can run multiple methods if their names contain testSave:

phpunit --filter testSave EscalationGroupTest escalation/EscalationGroupTest.php

Prefer the complete, unique method name:

phpunit --filter testSaveAndDrop EscalationGroupTest escalation/EscalationGroupTest.php

Filtering by a file path

The filter selects test names, not source filenames. The file belongs in the test target position, while the method name belongs in --filter.

# Not a useful method-name filter
phpunit --filter escalation/EscalationGroupTest.php escalation/EscalationGroupTest.php

Using an incorrect method name

PHP test method names are case-sensitive. Confirm that the method is exactly named testSaveAndDrop.

public function testSaveAndDrop()
{
    // Test code
}

Forgetting to run the full suite afterward

A single test gives fast feedback, but it cannot prove that a change did not break other behavior. Run the full relevant suite before finishing the work.

A filename limits where PHPUnit looks. A filter limits which discovered tests run. These can be used together:

phpunit --filter testSaveAndDrop escalation/EscalationGroupTest.php

# PHPUnit 3.2.8: place options before class/file arguments
phpunit --filter testSaveAndDrop EscalationGroupTest escalation/EscalationGroupTest.php

# Select from a test file
phpunit --filter testSaveAndDrop escalation/EscalationGroupTest.php

# Run a family of tests whose names contain "testSave"
phpunit --filter testSave EscalationGroupTest escalation/EscalationGroupTest.php

# Add diagnostic output
phpunit --filter testSaveAndDrop --debug EscalationGroupTest escalation/EscalationGroupTest.php

• --filter matches test names using a pattern.
• Put options before positional test targets in older PHPUnit versions.
• Use a unique, complete method name to avoid unintended matches.
• A file path is a test target, not normally the filter value.
• Run the full suite after focused development or debugging.

Why does PHPUnit run every test even though I used --filter?

With PHPUnit 3.2.8, the option may not be applied if it appears after the class or file arguments. Put --filter first.

What is the command to run testSaveAndDrop only?

phpunit --filter testSaveAndDrop EscalationGroupTest escalation/EscalationGroupTest.php

Does --filter accept a test file path?

No. The filter is for matching test names. Provide the file path separately as the test target.

Can --filter run more than one test?

Yes. It matches patterns, so --filter testSave can run every test whose name includes testSave.

Should I include the test class name in the filter?

Usually, filtering by the unique method name is simpler. The class and file can be supplied as separate arguments to narrow the search area.

Is a filtered run enough before I commit my code?

It is useful for quick feedback, but you should run the full relevant test suite afterward to catch regressions elsewhere.

Why should test method names be descriptive?

Descriptive names communicate behavior and make it easy to run the exact test you need with --filter.

• PHPUnit test cases — A test class contains the individual methods that PHPUnit discovers and executes.
• Test naming conventions — Clear test... method names improve readability and make filters more precise.
• Regular expressions — PHPUnit filters are pattern-based, so regex concepts explain why one filter can match multiple tests.
• Command-line arguments — Understanding options versus positional arguments prevents argument-order problems.
• Test suites — Suites organize many test classes and are useful when moving from one focused test to broader verification.
• Debugging automated tests — Focused execution and diagnostic output are common techniques for finding failures.