$ idl -e "myprogram" -args a b c

Then, in MYPROGRAM, the command line arguments could be retrieved with:

args = command_line_args()

The args string array would contain “a”, “b”, and “c”. To make it more convenient to launch IDL this way, you can create a script that calls IDL in the proper way, passing arguments of the script to arguments listed after the -args in the IDL call. If you name the wrapper script myprogram also, your calls would look like:

$ myprogram a b c

But, suppose you wanted your routine to have command line switches like:

$ myprogram --verbose --header=test.hdr test.dat

Then you had to parse the args received from COMMAND_LINE_ARGS yourself. The mg_options class simplifies this parsing and adds several other conveniences.

The mg_options class can be instantiated with the optional APP_NAME and VERSION properties:

opts = obj_new('mg_options', app_name='mgunit', version='1.0.0beta')

Next, add options using the addOption method:

opts->addOption, 'color', 'c', /boolean, $
                 help='produce color output on STDOUT'
opts->addOption, 'filename', $
                 help='specify a log filename'
opts->addOption, 'gui', 'g', /boolean, $
                 help='start a GUI to run the tests'
opts->addOption, 'html', 'm', /boolean, $
                 help='produce HTML output'

The two positional parameters of addOption are the full name of the option (used with “–”) and an optional short name (used with just a single “-”). The help keyword gives a description of the option displayed when the help option is given (the help option is automatically created for you). The boolean keyword indicates that the option does not take a value, it’s presence indicates it is “on”.

Next, add the positional parameters:

opts->addParams, [0, -1]

This indicates the minimum and maximum number of positional parameters, with -1 indicating there is no maximum number.

After defining all the options and parameters, the arguments to the program can be parsed:

opts->parseArgs, error_message=errorMsg

The ERROR_MESSAGE keyword will contain parse error message if they occur, otherwise it will be an empty string.

After the parsing, use the get method to retrieve the value of the parameters:

if (errorMsg eq '') then begin
  params = opts->get(/params, n_params=nparams)

  if (nparams gt 0L && ~opts->get('help')) then begin
    filename = opts->get('filename', present=filenamePresent)
    if (filenamePresent) then begin
      mgunit, params, $
              color=opts->get('color'), $
              filename=opts->get('filename'), $
              gui=opts->get('gui'), $
              html=opts->get('html')
    endif else begin
      mgunit, params, $
              color=opts->get('color'), $
              gui=opts->get('gui'), $
              html=opts->get('html')
    endelse
  endif
endif else begin
  message, errorMsg, /informational, /noname
endelse

Don’t forget to free the options object when finished:

obj_destroy, opts

A help option is automatically created to display information about the options:

$ mgunit --help
usage: mgunit [options] ...

options:
  --color, -c          produce color output on STDOUT
  --filename=FILENAME  specify a log filename
  --gui, -g            start a GUI to run the tests
  --help, -h           display this help
  --html, -m           produce HTML output
  --version            display version information

Because we set the APP_NAME and VERSION properties when instantiating the options object, the version option gives useful information:

$ mgunit --version
mgunit 1.0.0beta

So the command line options can be used as follows:

$ mgunit --color --filename=unittests.txt gpu_alltests_uts

This is translated in the wrapper to:

IDL> mgunit, 'gpu_alltests_uts', /color, filename='unittests.txt'

Here’s the source code (docs). You will need the hash table, array list, and abstract list classes also.

Some features of the 1.0 release:

1. Several test runners for outputting test results to various formats are available; output can be sent to stdout, log files, or html files. In addition, there is a GUI test runner that will show results and re-run tests with the push of a button (also recompiling tests before running them).

2. Contains IDL Workbench templates for making it even faster to create new test cases/suites.

3. Keywords to MGUNIT to retrieve the number of passing and failing tests.

Color output to the terminal window when possible.

Command line wrapper so that mgunit can be run from the UNIX command line (get the source distribution to use this ability).

This release also contains several bug fixes.

1. Several test runners for outputting test results to various formats are available; output can be sent to stdout, log files, or html files. In addition, there is a GUI test runner that will show results and re-run tests with the push of a button (also recompiling tests before running them).

2. Contains IDL Workbench templates for making it even faster to create new test cases/suites.

3. Keywords to mgunit to retrieve the number of passing and failing tests.

4. Color output to the terminal window when possible.

This release also contains several bug fixes.

I recommend getting the source distribution so that you don’t have to do a manual restore: source distribution and save file distribution.

The structure of tests created for this framework is straightforward. Individual tests are methods of an class that subclasses MGtestCase. Each method returns 1 for success or 0 for failure (or throws an error). Each test method’s name must start with “test”. Test cases may be (but are not required to be) grouped into test suites.

The examples (FINDGENTEST, INDGENTEST, and INDGENSUITE) of MGunit discussed are available for download.

To create a test, subclass MGtestCase like:

pro findgentest__define
  define = { findgentest, inherits MGtestCase }
end

A test is just a method whose name starts with “test”. MGunit will find the tests automatically (make sure they are either already compiled or above FINDGENTEST__DEFINE in the same file). A test case may have as many tests as necessary. For example, a simple test:

function findgentest::test2
  a = findgen(5)
  assert, array_equal(a, [0.0, 1.0, 2.0, 3.0, 4.0]), 'Correct elements'

  return, 1
end

Return 1 for success. For failure, either return 0 or throw an error. Here the helper routine ASSERT will throw an error using the given message if its condition is not met. This will be reported as a failure along with the message. To run this test, use:

IDL> mgunit, 'findgentest'

Results can be sent to a log file with the LOG_FILE:

IDL> mgunit, 'findgentest', log_file='results.log'

This should produce the output:

Starting test suite MGTESTSUITE (1 test case, 4 tests)
   Starting FINDGENTEST (4 tests)
      TEST1: failed "Wrong number of elements"
      TEST2: passed
      TEST3: passed
      TEST4: failed "Type conversion error: Unable to convert..."
      Results: 2 / 4 tests passed
   Results: 2 / 4 tests passed

One tricky situation is that sometimes invalid input must be tested to make sure the routine fails. In this case, throwing an error should indicate a success of the test, not a failure. In this case use the provided batch file error_is_pass at the beginning of the routine, like:

function findgentest::test3
  @error_is_pass

  a = findgen('string')

  return, 1
end

Multiple test cases can be specified as an array

IDL> mgunit, ['findgentest', 'indgentest']

or by creating a test suite. Test suites are very simple; they are just collections of test cases. To make a suite, subclass MGtestSuite and use the add method to add test classes. For example,

function indgensuite::init, _extra=e
  compile_opt strictarr

  if (~self->mgtestsuite::init(_extra=e)) then return, 0

  self->add, ['indgentest', 'findgentest']

  return, 1
end

pro indgensuite__define
  define = { indgensuite, inherits MGtestSuite }
end

This test suite is available for download (source / docs). MGUNIT can run test suites also,

IDL> mgunit, 'indgensuite'

MGUNIT will also accept a mixed array of test suites and test cases.