Running Unit Tests – Explained

The objective of this tutorial is to clarify the various options in protected/tests/unit/TestSuite.php and provide an understanding of when to use them.   I will start by explaining the most narrow use case and broaden out.

Let us say I add something in the Accounts module, and I add a test in AccountTest.php.  The first thing I will run is:


phpunit TestSuite.php AccountTest --no-freeze

This will just test the AccountTest class in unfrozen mode. Unfrozen mode means the database schema is in flux.  This is nice to use during development.  If –no-freeze works, then I typically do:


phpunit TestSuite.php AccountTest --reuse-schema

It is important to remember though, that reuse-schema relies on a stored schema. If my development work in accounts was adding another attribute to the Account model then I should do:


phpunit TestSuite.php AccountTest

This will rebuild the database and save the schema.  The next time I run it, I can just add –reuse-schema.

Do you really need to test –no-freeze?  It depends. Production is setup with frozen, however due to the nature of some tests, those tests must be run in non-frozen model.  The framework tests only work in non-frozen.  The reason is because test models like A, B, or C do not get built in the schema auto-builder so they only work in non-frozen mode.  One day it would be nice to have an auto-build that works for development that includes all testing models etc., but for now this is how it is.

So once you are done with your work in accounts and AccountTest runs, next I usually run:


phpunit TestSuite.php accounts --reuse-schema

This is more broad and runs all tests in the Accounts module folder.

If you want to push to default, then it is important you run


phpunit TestSuite.php All --reuse-schema

This will run all tests frozen, re-using the schema.  You can do it also without –reuse-schema just to make sure you didn’t miss any schema changes.  If running “All” passes, you should try with –no-freeze, then you can check-in.

There are some additional options if you look at TestSuite.php or you can type:


phpunit TestSuite.php

Another handy tool if things go wrong during tests, is to use:


phpunit --debug TestSuite.php All

Using –debug can be used on any way TestSuite.php is run, but it lets you know as each test completes. This is especially useful if you are running a lot of tests, and there is some fatal error that is occurring which means you don’t know where this failed.

Also remember, the perInstanceTest.php and debugTest.php files are for testing. So if you want to turn debug on/off you need to do it in debugTest.php not debug.php.  Debug.php is used by the application when accessed via the browser or the command line tool.

Using phpunit.xml

Using phpunit.xml as configuration parameter might save you few key strokes as it contains some reasonable default options defined for reuse. Here is the latest version available under protected/tests:

<phpunit
    colors="false"
    convertErrorsToExceptions="true"
    convertNoticesToExceptions="true"
    convertWarningsToExceptions="true"
    stopOnFailure="false">


  <filter>
    <blacklist>
      <directory suffix=".php">../../../yii</directory>
      <directory suffix=".php">../../../redbean</directory>
    </blacklist>
  </filter>

  <selenium>
    <browser name="Internet Explorer" browser="*iexplore" />
    <browser name="Firefox" browser="*firefox" />
  </selenium>


  <listeners>
    <listener class="ExecutionTimeListener" file="listeners/ExecutionTimeListener.php" >
      <arguments>
          <integer>0</integer>
          <integer>2</integer>
      </arguments>
    </listener>
  </listeners>

</phpunit>

Passing phpunit.xml path to phpunit binary on nix-like(Linux, Unix, Mac) is as simple as:


phpunit -c `pwd`/../phpunit.xml TestSuite.php ExportItemToCsvFileUtilTest --reuse-schema

(For Windows you might have to specify absolute path manually)

You can still override each configuration defined in phpunit.xml by using appropriate switches:


phpunit -c `pwd`/../phpunit.xml --colors --verbose  TestSuite.php ExportItemToCsvFileUtilTest --reuse-schema

(colors was set to false in phpunit.xml but –colors would take precedence and turn on colors.)

Aside from being reusable  and saving keystrokes phpunit.xml also defines some additional useful stuff such as listeners. An example of such Listener would be ExecutionTimeListener that would display execution times(with seconds precision specified by second argument) of tests that take more than specified time(in seconds, provided as first argument) to execute.

Leave a Comment