PHPStorm, PHPUnit and Vagrant

If you are using Vagrant (VirtualBox) as your development environment and PHPStorm as your IDE, you might have already tried to run PHPUnit tests through the IDE. The problem is that the IDE is running on one machine and your development environment is another (virtual) machine. In this case you can’t use the PHP CLI directly or you have to install it on both machines. And then you are missing the point why to use an extra development environment. But PHPStorm does support remote PHPUnit test execution, just the IDE configuration is not exactly straight forward.

The solution, which you might expect, is to run tests through the ssh. But for now you have to do it manually as PHPStorm doesn’t support this feature yet.

But you have the IDE, you have tests and you have dev machine where you want to run tests. Well, how to do it? Official PHPStorm documentation is not great, but it points you in the right direction – to run PHPUnit tests on server –

A better description is available on the Dutch web alliance site –

It’s closer but still not what I wanted and needed. I need to run PHPUnit tests from the IDE, sometimes I need to use remote debugging (Xdebug) individually for each test case, each test.

So how does PHPStorm supports remote test execution? It uses Apache (web server) not CLI. When you run tests, it uses _intellij_phpunit_launcher.php file (stored to filesystem by IDE) as a proxy for test execution. This works well for simple projects, where all classes and tests are accessible through the webserver – under document root.

But to be honest any half-decent project shouldn’t expose it’s classes and tests. Usually you have something like /public/index.php which is an entry point – dispatcher and the rest is and must be hidden from site visitors.

When you try to run tests through your project vhost it wouldn’t work.

There is one very simple way around it. It’s not the nicest solution and definitely you should use it only for isolated development environment. But it is very simple to configure and works pretty well.

So what is the trick?

The trick is to create another vhost one level above your projects and execute your tests in any project through this dummy project (default site).

Your project could be stored for example in /vagrant_data and have similar structure:

    |-- my_project
    | |-- httpdocs
    | | |-- application
    | | |-- docs
    | | |-- library
    | | |-- public
    | | |-- scripts
    | | |-- tests

Then what you need is to setup the vhost – could be default site and have document root pointed to /vagrant_data – one level above your project.

In PHPStorm you must execute PHPUnit test as “PHPUnit on Server”.

Now important is to not use your project server but the default one.

And for vagrant usage you must set correct mapping.

And ignore message that local path is outside your project.

One important thing – if you need to use bootstrap file or to pass any other argument to PHPUnit, you can add a value to “Test runner option”. For the bootstrapfile I used:


This way you can run and debug any test case, any test method and it works.

Added 4th of December 2014:

PHPStorm 8 brought an option to execute PHP script over SSH as is described in PHPStorm, PHPUnit and Vagrant II

Latest News & Insights

Say connected – get Loft updates straight to your inbox.