UnityHelperScriptsGuide.md

Unity Helper Scripts

With a Little Help From Our Friends

Sometimes what it takes to be a really efficient C programmer is a little non-C. The Unity project includes a couple Ruby scripts for making your life just a tad easier. They are completely optional. If you choose to use them, you'll need a copy of Ruby, of course. Just install whatever the latest version is, and it is likely to work. You can find Ruby at ruby-lang.org.

generate_test_runner.rb

Are you tired of creating your own main function in your test file? Do you keep forgetting to add a RUN_TEST call when you add a new test case to your suite? Do you want to use CMock or other fancy add-ons but don't want to figure out how to create your own RUN_TEST macro?

Well then we have the perfect script for you!

The generate_test_runner script processes a given test file and automatically creates a separate test runner file that includes ?main?to execute the test cases within the scanned test file. All you do then is add the generated runner to your list of files to be compiled and linked, and presto you're done!

This script searches your test file for void function signatures having a function name beginning with "test" or "spec". It treats each of these functions as a test case and builds up a test suite of them. For example, the following includes three test cases:

void testVerifyThatUnityIsAwesomeAndWillMakeYourLifeEasier(void)
{
  ASSERT_TRUE(1);
}
void test_FunctionName_should_WorkProperlyAndReturn8(void) {
  ASSERT_EQUAL_INT(8, FunctionName());
}
void spec_Function_should_DoWhatItIsSupposedToDo(void) {
  ASSERT_NOT_NULL(Function(5));
}

You can run this script a couple of ways. The first is from the command line:

ruby generate_test_runner.rb TestFile.c NameOfRunner.c

Alternatively, if you include only the test file parameter, the script will copy the name of the test file and automatically append "_Runner" to the name of the generated file. The example immediately below will create TestFile_Runner.c.

ruby generate_test_runner.rb TestFile.c

You can also add a YAML file to configure extra options. Conveniently, this YAML file is of the same format as that used by Unity and CMock. So if you are using YAML files already, you can simply pass the very same file into the generator script.

ruby generate_test_runner.rb TestFile.c my_config.yml

The contents of the YAML file my_config.yml could look something like the example below. If you're wondering what some of these options do, you're going to love the next section of this document.

:unity:
  :includes:
    - stdio.h
    - microdefs.h
  :cexception: 1
  :suit_setup: "blah = malloc(1024);"
  :suite_teardown: "free(blah);"

If you would like to force your generated test runner to include one or more header files, you can just include those at the command line too. Just make sure these are after the YAML file, if you are using one:

ruby generate_test_runner.rb TestFile.c my_config.yml extras.h

Another option, particularly if you are already using Ruby to orchestrate your builds - or more likely the Ruby-based build tool Rake - is requiring this script directly. Anything that you would have specified in a YAML file can be passed to the script as part of a hash. Let's push the exact same requirement set as we did above but this time through Ruby code directly: