Printing debug output to console in Codeception

Printing debug output to console in Codeception

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

Stefan Bogdanescu

Founder & Senior Architect

Printing debug output to console in Codeception

When you are deep inside a failing acceptance test, relying solely on standard assertion messages can feel insufficient. You often need to inspect internal state, check variable contents, or trace execution flow without dropping into an Xdebug session. The immediate instinct is to reach for var_dump() or echo, but in the context of Codeception, these approaches frequently fail to produce visible output in your terminal. This happens because Codeception runs tests within a specific bootstrap process that can suppress direct standard output, and because the test framework expects structured logging rather than raw stdout streams.

Why Standard Output Fails

In a typical PHP script, echo or var_dump() writes directly to STDOUT. However, when running through PHPUnit (which Codeception relies on), the testing framework often captures this output to prevent it from cluttering the console with verbose noise during normal test execution. If you run your tests via the standard CLI command (vendor/bin/codecept run), any direct echo statements inside your steps or CPT files will be swallowed unless explicitly configured otherwise.

Attempting to use WebDebug's makeAResponseDump() is a valid strategy for inspecting HTTP responses, but it is not a general-purpose solution for printing arbitrary variable data. That method is designed specifically to format and assert on response objects, not to serve as a free-form debugging tool for complex application state or custom logic variables.

Using Codeception's Built-in Debugger

Codeception provides a native mechanism for inspecting data that aligns with its testing philosophy: the debug() helper method. This function is designed to output formatted data to the console while respecting the framework's logging configuration. Unlike raw echo, debug() integrates seamlessly with PHPUnit's output handlers and can be configured to show up in your terminal logs.

To use this effectively, you must ensure that the test suite is configured to display debug messages. In many default configurations, these messages are hidden by default to keep the console clean. You can enable them by adjusting the codeception.yml file or passing specific flags during execution.

Here is how you might implement a debug check within a CPT step:

use Codeception\Lib\Driver\PHP;

public function _before(Test $I)
{
    $data = ['username' => 'admin', 'role' => 'super'];
    
    // This will print the variable content to the console
    $I->debug($data);
}

When running the tests, you need to ensure that the output is not being filtered out. If debug() appears to do nothing, check your terminal for a warning indicating that debug output was suppressed. Often, simply adding the --debug flag when invoking Codeception forces PHPUnit to respect these calls:

vendor/bin/codecept run --debug

Alternatively, you can configure the codeception.yml file to always show debug messages by setting the colors and output_format options appropriately, though explicit flags often yield more immediate results in a development environment.

Alternative Approaches with Monolog

If debug() does not meet your specific formatting needs or if you require structured logging that persists beyond the test run, integrating with PHP's Monolog library is another robust path. Codeception supports using Monolog as its underlying logger. By configuring your bootstrap file to instantiate a Monolog handler that writes to STDOUT, you can inject custom debug messages into the global log stream.

This approach requires modifying the bootstrap logic (often found in tests/_bootstrap.php or the main configuration file) to ensure that a console handler is active:

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$logger = new Logger('codecept');
$handler = new StreamHandler('php://stdout', Logger::DEBUG);
$handler->setFormatter(new \Monolog\Formatter\LineFormatter("[%datetime%] %channel%.%name_level_name%%message%", "DATE_TIME"));
$logger->pushHandler($handler);

Once this is in place, you can use $logger->debug() or even standard var_dump() calls if they are routed through the logger's stream. However, be cautious: adding a direct php://stdout handler can sometimes interfere with PHPUnit's own progress bar rendering if not configured carefully. The trade-off here is gaining full control over log formatting at the cost of potentially complicating the test output layout.

When to Use Each Method

The choice between debug(), var_dump(), and Monolog depends on your immediate need. If you are iterating quickly and just need to see a variable's structure, debug() with the --debug flag is the least invasive option. It keeps your code clean and relies on Codeception's existing infrastructure.

If you are building custom test suites where output visibility is critical regardless of execution mode, routing everything through Monolog offers consistency. Just remember that echo remains unreliable in this environment; it bypasses the framework's logging layer entirely and gets lost in the noise of PHPUnit's internal streams. Always prefer mechanisms that integrate with the test runner's output handling to ensure your debug messages actually reach your eyes.

Our network