Running specific tests using Gulp TDD in Laravel Elixir

Today my team was trying to refactor some code and we wanted phpUnit to continually tell us if anything was breaking. Jeffrey Way’s excellent Elixir package that is included with Laravel now includes the option to run gulp tdd which watches the tests being edited and runs the tests once the files are saved. In our case today, however, I didn’t want it to run all of the tests since we have a fairly significant test suite. I’ll quickly go through a few ways this can be done!

To be clear, below is all that it takes to get Laravel Elixir up and running using phpUnit. Once you have added this mix.phpUnit(); to your gulpfile.js, all you need to do is run gulp tdd from your command line and you are off to the races!

elixir(function(mix) {
    mix.sass('app.scss');
    mix.phpUnit();
});

After looking through the gulp-phpunit API and the Elixir implementation, I realized there were two options that could be passed into mix.phpunit(). They are mix.phpunit([src], [options]).

[src] specifies where phpUnit should look for the source files to run against. In my case, I have a set of directories inside my tests folder so my value for src needed to be ‘/tests/**/*Test.php’. This will run inside one level of subdirectories with any file that ends with Test.php.

[options] is where you can go all kinds of crazy passing things into phpUnit. All you need to do is pass in an object with whatever settings you would like to use. Many other things can be passed in other than just a specific class. For the entire listing of options that can be passed in, go to https://github.com/mikeerickson/gulp-phpunit#api and check out the API documentation for the gulp-phpunit package.

So what did the entire thing look like once it was completed?

mix.phpUnit(['tests/**/*Test.php'], {
    testClass: 'tests/TestSubdir/SpecificTaskTest.php'
});

Another way this could be done is by using the filter option which allows a pattern to be passed instead of a specific file. Say I have 3 files in my TestSubdir that I want to run and they are named SpecificTaskTest.php, SomeOtherTest.php, and AnotherTaskTest.php. I could specify a pattern of *TaskTest.php and it would run the two tests that end in TaskTest.php. The way this would be used is as follows:

mix.phpUnit(['tests/**/*Test.php'], {
    filter: 'tests/TestSubdir/*TaskTest.php'
});

Check out the latest documentation for additional filter examples if desired: https://phpunit.de/manual/current/en/textui.html#textui.examples.filter-patterns. You can also use a testSuite or a group to specify the individual tests that should run.

One of the other interesting options was configurationFile. With this, you can actually specify a different phpunit.xml file to be used when running gulp tdd. I could see this being useful in instances where your tdd workflow looks a bit different from when you run your entire test suite (perhaps with code coverage or other more time-consuming tasks that you may not want to run when performing quick tdd/refactoring).