Tests: Difference between revisions

Having a thorough [https://en.wikipedia.org/wiki/Test_suite test suite] is something very important which is usually overlooked.  It is an incredible help in preventing regression bugs and quickly assess the status of old code. For example, many packages in Octave Forge become deprecated after losing their maintainer simply because they have no test suite.

GNU Octave has multiple tools that help in creating a comprehensive test suite, accessible to both developers and end-users, as detailed on the [http://www.gnu.org/software/octave/doc/interpreter/Test-Functions.html Octave manual]. Basically, test blocks are {{codeline|%!test}} comment blocks, typically at the end of a source file, which are ignored by the Octave interpreter and only read by the {{manual|test}} function.

To run all the tests of a specific function, simply use the {{manual|test}} command at the Octave prompt.  For example, to run the tests of the Octave function {{manual|mean}} type:

  >> test mean

These tests are written in the Octave language [http://hg.savannah.gnu.org/hgweb/octave/file/6443693a176f/scripts/statistics/base/mean.m#l130 at the bottom of <code>mean.m</code>] which defines the {{manual|mean}} function.  It is important that these tests are also available for the end users so they can test the status of their installation.  The whole Octave test suite can be run with:

  >> __run_test_suite__

To run tests in a specific file, one can simply specify the path instead of a function name:

   test /full/path/to/file.m

 

function [x, y, z] = foo (bar)

%!assert (foo (1))

%!assert (foo ("on"), "off")

%!error <must be positive integer> foo (-1)

%!error <must be positive integer> foo (1.5)

%!demo

%! ## see how cool foo() is:

%! foo([1:100])

// Copyright

//

// A block with the copyright notice

DEFUN_DLD (foo, args, ,

"-*- texinfo -*-\n\

A block with the help text")

{

   // some amazing code

}

/*

%!assert (foo (1))

%!assert (foo (1:10))

%!assert (foo ("on"), "off")

%!error <must be positive integer> foo (-1)

%!error <must be positive integer> foo (1.5)

*/

{{codeline|%!assert}} lines are the simplest tests to write and also the most

%!assert (foo (bar))      # test fails if "foo (bar)" returns false

%!assert (foo (bar), qux) # test fails if "foo (bar)" is different from "qux"

an Octave function that throws an error when two arguments fail to compare.

While single {{codeline|%!assert}} lines are the most common used tests, {{codeline|%!test}} blocks offer more features and flexibility. The code within {{codeline|%!test}} blocks is simply processed through the Octave interpreter.  If the code generates an error, the test is said to fail.  Often {{codeline|%!test}} blocks end with a call to {{codeline|assert}}:

%!test

%! a = [0 1 0 0 3 0 0 5 0 2 1];

%! b = [2 5 8 10 11];

%! for i = 1:5

%!  assert (find (a, i), b(1:i))

%! endfor

%!test foo (bar)

%!error foo ()  # test that causes any error

%!error <BAR must be a positive integer> foo (-1.5)  # test that throws specific error message

%!error id=Octave:invalid-fun-call foo ()  # test that throws specific error id

%!warning foo ()  # test that causes any warning

%!warning <negative values might give inaccurate results> foo (-1.5)  # test that triggers a specific warning message

%!warning id=BAR:possibly-inaccurate-result foo (-1.5)  # test that triggers a specific warning id

It is often useful to share a function among multiple tests.  Sometimes

%!assert (foo (bar), slow_foo (bar))

%! for i = -100:100

%!  bar = qux (i);