How can I run only one test from a suite?

How can I run only one test from a suite?

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

Stefan Bogdanescu

Founder & Senior Architect

Running Isolated Tests in Codeception

When debugging a flaky test or verifying a specific fix, you often need to isolate a single scenario within a larger suite. In Codeception, this is a common requirement when your acceptance tests contain multiple distinct scenarios defined as methods on a Cest class. While running the entire file via codecept run tests/acceptance/VisitorCest.php executes every method inside it, executing just one specific test requires a more targeted approach.

The standard way to invoke Codeception is by specifying the scenario name directly in the command line. You do not pass the method name as an argument; instead, you pass the full class and scenario path. The command structure generally follows this pattern:

codecept run tests/acceptance/VisitorCest.php:aboutPage

In this syntax, the part before the colon represents the file path (or sometimes the step name if using functional steps), while the part after the colon is the specific test method you wish to execute. Codeception parses this string and loads the class VisitorCest, then instantiates the scenario named aboutPage. This allows the test runner to skip over contactPage entirely, saving execution time and keeping your output focused on the failing or changing logic.

However, simply running a single test is not always the end of the story. You must understand how Codeception handles context between tests. The _before() and _after() methods defined in your Cest class are lifecycle hooks that execute once per scenario. When you run aboutPage in isolation, _before() will still fire to set up the initial state for that specific test, and _after() will clean up afterward. This ensures that running a single test does not leave shared resources like database tables or browser sessions in an inconsistent state.

It is important to distinguish between running a single step versus a single scenario. Codeception also supports a step: syntax, which allows you to run individual steps within a single scenario if they are defined as separate methods. For example, if your test looked like this:

public function aboutPage(AcceptanceTester $I)
{
    $I->amOnPage('/about');
    $I->see('About Us', 'h1');
}

You could technically run just $I->see using codecept run ...:aboutPage::see, but this is less common. Usually, the atomic unit of a test is the entire method containing the scenario name. Running the whole method ensures that the preconditions set in _before() are respected.

One potential pitfall involves the order of execution. If your test suite relies on a global setup file (like tests/_bootstrap.php) to clear caches or seed data, Codeception will execute this once before running the specific scenario you requested. This is beneficial because it ensures a clean slate for that single run without needing to manually reset the environment each time. Conversely, if your tests rely on previous test results to function, running them in isolation might cause failures because the shared state isn't carried over. In such cases, you would need to ensure your _before() method handles all necessary initialization independently of prior test runs.

If you are working within a Laravel project and want to integrate these acceptance tests seamlessly into your development workflow, consider how Codeception interacts with your application's environment. Tools like phpunit often handle single test execution differently, but Codeception's convention remains consistent across its modules. For more advanced integration patterns or if you need to run specific scenarios within a complex Laravel context, visiting https://laravelcompany.com can provide additional insights into best practices for maintaining robust acceptance suites alongside your unit tests.

Ultimately, the ability to run aboutPage in isolation is a powerful feature for rapid debugging. It lets you verify that a specific interaction works without waiting for other unrelated scenarios to complete. Just remember to check your _before() logic to ensure it correctly prepares the environment for every single test execution.

Our network