Troubleshooting
Most problems with a test runner come down to a handful of causes: it looks for files in a different place than you think, it loads a different config than you think, or something in the environment changes its behaviour. This page goes through the common symptoms, what causes them and how to fix them. MicroUnit tries hard to say what went wrong in its error messages, so the quoted messages below are the real ones, which makes this page easy to search.
No tests found
No test files found. Test files must match: *-tests.php
MicroUnit only loads files whose name matches one of the configured patterns. The default pattern is *-tests.php, so a PHPUnit-style CartTest.php is ignored until you say otherwise:
return MicroUnitConfigBuilder::create()
->withTestDir('tests')
->withTestFilePatterns('*Test.php')
->build();
Things worth knowing about patterns:
- They match the file name, not the path, and they are case-insensitive.
*,?and character classes likeTest[A-Z]*.phpwork. withTestFilePatterns()sets the list,addTestFilePattern()adds one more. As soon as you configure any pattern, the default*-tests.phpno longer applies, so list it again if you still want it.- Directories named
vendor,node_modules,.gitand.microunitare never searched. - A file you name on the command line (
vendor/bin/microunit tests/cart.php) runs even if it doesn’t match a pattern. A directory on the command line is searched with the patterns.
Without withTestDir(), MicroUnit searches tests/ next to the config file; microunit init creates it with a first test. A directory that doesn’t exist is an error:
The test directory '/app/spec' does not exist. Check withTestDir()/withTestGroup() in your config.
Note that a run that finds no test files still exits with 0. If CI suddenly reports “0/0 passed”, the patterns or the directory are the first thing to check.
If the files are found but a suite is empty, check that the file actually registers tests: TestSetup::getTester('Suite') and at least one $tester->define(...). vendor/bin/microunit --list shows what MicroUnit sees without running anything.
Your configuration is not applied
MicroUnit looks for a file named exactly microunit.config.php, starting in the current working directory and walking up through its parents. The first one it finds wins. If it finds none, it runs with the defaults, without a warning.
So if your settings seem to be ignored, one of these is usually true:
- The file has a different name.
microunit.phpormicrounit.config.dist.phpare not picked up. - It is not on the search path. A config in
tools/is never found when you run from the project root, because the search only goes up, never sideways or down.
/my-project
├── tools/
│ └── microunit.config.php # not found: not on the way up from /my-project
├── tests/
└── vendor/
- Another config is closer. A stray
microunit.config.phpin a subdirectory wins when you run from inside it.
To take the guessing out of it, name the file explicitly:
vendor/bin/microunit --config=tools/microunit.config.php
The config file 'tools/microunit.config.php' does not exist.
Paths inside the config (withTestDir(), withBootstrapFile(), coverage paths, the runtime directory) are relative to the config file, not to the directory you run from. Absolute paths work too, so __DIR__ . '/tests' is fine.
The config file must return the config
/app/microunit.config.php must return a MicroUnit\Config\MicroUnitConfig, but returned int. Did you forget 'return' or '->build()'?
The file has to return the result of build():
<?php
use MicroUnit\Config\MicroUnitConfigBuilder;
return MicroUnitConfigBuilder::create() // "return" is easy to forget
->withTestDir('tests')
->build(); // and so is build()
“returned int” is what you get without return (PHP’s require returns 1), “returned MicroUnit\Config\MicroUnitConfigBuilder” means ->build() is missing. MicroUnit exits with code 2 for configuration errors, so CI fails clearly instead of running nothing.
No output at all
If a run prints nothing, check whether your config calls withTestWriters(). It replaces the default console writer, so this config produces no console output:
->withTestWriters(new JUnitTestWriter('build/junit.xml')) // the console writer is gone
Use addTestWriter() to keep the console output, or list the console writer explicitly:
->withTestWriters(new MinimalStringTestWriter(), new JUnitTestWriter('build/junit.xml'))
The output page lists every writer.
Classes are not found, or the bootstrap fails
MicroUnit loads your Composer autoloader for you: it looks for vendor/autoload.php from the working directory upwards (falling back to the one MicroUnit itself was installed with). You don’t need a bootstrap file just to autoload.
When a class is not found:
- Test helpers and fixtures classes usually live in an
autoload-devnamespace ("Tests\\": "tests/"). Check that the mapping exists and runcomposer dump-autoloadafter adding it. - Classes declared in test files are only available once that file is loaded. Put shared helpers in their own autoloaded files instead.
- A missing
usestatement forAssertorTestSetupshows up the same way. Every test file needsuse MicroUnit\Assertion\Assert;anduse MicroUnit\Setup\TestSetup;(or whatever it uses).
A bootstrap file configured with withBootstrapFile() must exist, relative to the config file:
The bootstrap file '/app/tests/bootstrap.php' does not exist.
Don’t require your own source files from microunit.config.php itself. It works for running tests, but those files are then loaded before coverage starts and can’t be measured. The bootstrap file is the right place.
Warnings and fatal errors
MicroUnit keeps PHP’s warnings, notices and deprecations out of the test output and writes them to a run log in .microunit/logs/. Only the latest run’s log is kept, unless you configure persistRunLogs(). A fatal error stops the run with a pointer to that log:
MicroUnit stopped on a fatal error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 20480 bytes)
in /app/src/Importer.php:88
Full log: /app/.microunit/logs/2026-11-19T00-50-39Z-19136.log
If something behaves oddly and the test output gives no reason, look in that log first.
Coverage is zero or suspiciously low
Go through these in order:
- OPcache. If the run prints
Coverage: OPcache is enabled for the CLI and may bypass instrumentation, OPcache is serving cached code instead of the instrumented version. Run withphp -d opcache.enable_cli=0 vendor/bin/microunit --coverage, or setopcache.enable_cli=0in thephp.iniyour CI uses. - Files loaded too early.
Coverage: N file(s) were loaded before coverage started and cannot be measuredmeans something included source files before the tests started, typicallymicrounit.config.php. Move those includes into the bootstrap file. - The include path.
withCoverage()measuressrc/by default, relative to the config file. If your code lives inapp/orlib/, say so:->withCoverage(include: 'app'). - Files that could not be parsed.
Coverage: /app/src/Weird.php is not measured (...)means the instrumenter didn’t understand some syntax in that file and left it out. The file still runs; it just isn’t counted. - No tokenizer. Coverage needs PHP’s tokenizer extension, which some minimal Docker images leave out.
Files that no test loads are reported with 0%, on purpose: untested code should lower the number. The coverage page explains how the measurement works.
The Test Explorer does not open
It is opt-in: a run opens it only with --explorer or withTestExplorer() in the config. Even then it stays closed when:
- the
CIenvironment variable is set (even locally, if your shell profile sets it), - the output is piped or redirected, or the tests run inside a tool that captures output (including AI agents),
- the run used
--no-explorer.
vendor/bin/microunit explorer opens it on demand in all of these cases.
The port is busy
The Test Explorer could not be started on port 7357. See /app/.microunit/explorer/server.log
Something else is listening on port 7357, often the explorer of another project. The server log says so (Test Explorer: port 7357 is not available (...)). Pick another port for this project:
->withTestExplorer(port: 7358)
The browser doesn’t open
MicroUnit opens the URL with start on Windows, open on macOS and xdg-open on Linux. If that fails (a server without a desktop, WSL without a browser bridge, a missing xdg-open), the URL is still printed: open http://127.0.0.1:7357/ yourself.
“Explorer stopped”
The explorer server shuts down after 30 minutes without requests. An open tab then shows “Explorer stopped · run microunit to restart”. Run the tests or vendor/bin/microunit explorer and the same tab reconnects. See the Test Explorer page for the details.
A parallel worker stopped unexpectedly
RuntimeException: The parallel worker running this test stopped unexpectedly (exit code 255).
A test in that worker took the process down: a fatal error, an exit() or die() in the code under test, a segfault in an extension, or running out of memory. Every test the worker was given is reported with this message, so the named suite is a starting point, not the culprit itself. When the worker printed something before it died, the last part of it is included under “Worker output”.
To find the real error, run the suite sequentially, where the fatal error is reported normally:
vendor/bin/microunit --no-parallel --filter=ImporterSuite
If tests pass sequentially and fail in parallel without crashing, they probably share something outside of PHP’s memory: a database, a file, a port. Give each worker its own copy using the TEST_TOKEN environment variable, as described in parallel runs.
Workers start with the same php.ini and memory limit as the main process, but other settings passed with -d on the command line do not reach them. If a -d setting fixes a sequential run but not a parallel one, move it into php.ini or into ini_set() in the bootstrap file.
Framework integration: “Is the framework (and phpunit/phpunit) installed?”
The test case class Illuminate\Foundation\Testing\TestCase does not exist. Is the framework (and phpunit/phpunit) installed?
The Laravel, Symfony and CodeIgniter integrations run your tests inside the framework’s own test case class, so the framework’s helpers (actingAs(), assertDatabaseHas(), the HTTP client) behave exactly as they do under PHPUnit. Those test case classes extend PHPUnit’s TestCase. MicroUnit itself has no dependencies, but with a framework integration your project needs phpunit/phpunit in require-dev. A new Laravel project already has it; keep it there after migrating from PHPUnit. The frameworks page has the details.
JSON output appears when you did not ask for it
If your terminal suddenly shows one long line of JSON instead of the usual output, MicroUnit thinks an AI agent is running the tests. It decides that from two environment variables:
CLAUDECODE=1, which Claude Code sets for the commands it runs. A terminal opened from within a Claude Code session, or a shell that inherited its environment, has it too.MICROUNIT_AGENT=1, which you or a tool may have exported in a shell profile.
Check with echo $CLAUDECODE $MICROUNIT_AGENT (or echo $env:CLAUDECODE in PowerShell). For a single run, pass --no-agent. To turn agent output off for the project regardless of the environment:
->withAgentOutput(false)
The reverse also happens: an agent sees no JSON because the config has withAgentOutput(false). The AI agents page explains the switches.
--failed runs everything
When --failed finds nothing to re-run, it prints “No failed tests in the previous run” and runs the full selection instead.
--failed reads the results the previous run saved in .microunit/explorer/. If that run had no failures, if .microunit was deleted, or if the previous run happened with a different config (and therefore a different runtime directory), there is nothing to re-run.
A data set or fixture gets the wrong arguments
ArgumentCountError: Too few arguments to function MicroUnit\Cli\Application::{closure:/app/tests/math-tests.php:8}(), 2 passed in ... and exactly 3 expected
Parameters of a test closure are filled in this order: parameters named like a fixture get that fixture, everything else is filled from the positional values. The positional values are, in order, the value returned by setUp() (or by setUpOnce() when there is no setUp()) if it returned anything, then the values of the data set. The error above usually means one of two things:
- a data set has fewer values than the closure has non-fixture parameters, or
setUp()returns a value, which then takes the first positional slot and shifts the data set values by one.
Give every data set the same number of values as the closure expects, and either accept the setUp() value as the first non-fixture parameter or stop returning it (fixtures are usually the better tool). Writing tests covers fixtures and data sets in detail.
Windows notes
MicroUnit’s own test suite runs on Windows, Linux and macOS in CI, so most things just work. A few details:
- Running it.
vendor/bin/microunitworks in PowerShell and Git Bash; in CMD, Composer’svendor\bin\microunit.batproxy does the same. - Regular expressions in Git Bash. Git Bash turns arguments that start with
/into Windows paths, so--filter=/^Cart::/selects nothing. Prefix the command withMSYS_NO_PATHCONV=1, or use a plain-text filter (--filter=Cart::). - Colours. MicroUnit enables ANSI colours in Windows Terminal and modern consoles. If you see escape codes like
[32minstead of colours in an old console, pass--no-colors. - The explorer server runs in its own process group, so pressing Ctrl+C in the terminal does not take it down with the test run.
- Paths. Coverage include and exclude paths are compared case-insensitively on Windows, matching the file system. Paths in the agent JSON use forward slashes.
- Parallel runs use the
NUMBER_OF_PROCESSORSenvironment variable to decide how many workers “one per core” means. -dsettings and parallel workers. As on every OS, workers readphp.iniand inherit the memory limit, but not other-dflags. On Windows installs without aphp.ini, workers start with no ini file at all, so extensions you enable with-d extension=...are missing there. Create aphp.iniinstead.
Still stuck?
Run with --no-parallel --no-coverage --no-agent to rule out the moving parts, check the run log in .microunit/logs/, and if it still looks wrong, open an issue with the command, the output and your microunit.config.php. The CLI and configuration pages document every flag and option.