Creating unit test suites

You can create suites of unit tests through the model annotations

  • aimmsunit::TestSuite
  • aimmsunit::Setup
  • aimmsunit::TearDown

Creating a test suite

You can create a suite of unit tests by setting the annotation aimmsunit::TestSuite to the name of the test suite you want to create

  • for all procedures separately that you want to be part of the test suite, or
  • on a section in your model that contains all the procedures that you want to add to the test suite

Adding setup and teardown procedures

By default, all procedures in a test suite will be considered as procedures that contain unit tests to be executed when testing the given test suite. By setting the additional annotations aimmsunit::Setup or aimmsunit::TearDown to the value 1 you indicate that these procedure do not contain tests, but are intended to set up the data and/or state of your model necessary for the tests in the test suite to run successfully (for aimmsunit::Setup), or to restore the model to its original state (for aimmsunit::TearDown). Any assertion evaluators in the setup and teardown procedures of a test suite will be ignored.

Assertion evaluators

The results of your unit tests reported back by the AIMMS Unit Test framework are completely driven by the assertion evaluators * aimmsunit::AssertTrue * aimmsunit::AssertFalse * aimmsunit::AssertThrow

aimmsunit::AssertTrue(desc, expression)

The function evaluates whether the given expression evaluates to true. If it evaluates to false, this will be caught by the AIMMS Unit Test framework and reported back to the user with the given description.

Arguments:
  • desc – description to be displayed when the assertion fails
  • expression – expression to be evaluated

For example, the test

p := 1;
aimmsunit::AssertTrue("p should be equal to 1", p = 1);

will succeed, while the test

p := 2;
aimmsunit::AssertTrue("p should be equal to 1", p = 1);

will fail. The latter will then throw an exception with description "p should be equal to 1".

aimmsunit::AssertFalse(desc, expression)

The function evaluates whether the given expression evaluates to false. If it evaluates to true, this will be caught by the AIMMS Unit Test framework and reported back to the user with the given description.

Arguments:
  • desc – description to be displayed when the assertion fails
  • expression – expression to be evaluated
aimmsunit::AssertThrow(desc)

By default, when a test procedure raises a runtime error, the test runner will catch the error and report it as a failed test. Through the aimmsunit::AssertThrow evaluator you indicate to the AIMMS Unit Test framework that the test is supposed to give rise to an AIMMS runtime error.

Arguments:
  • desc – description to be displayed when the function does not throw

For example, the test

aimmsunit::AssertThrow("This procedure should throw");
a := 1/0;

will succeed, because the division by zero in the assignment will cause a runtime error.

Comparing multi-dimensional identifier data

A very common test you might want to use, is to compare the contents of two multi-dimensional identifiers.

aimmsunit::CompareEqual(p1, p2, eps)

This function test whether the given identifier slices are equal, where equality means:

  • same dimension,
  • same root domain sets,
  • same value type, and
  • tuple-wise value equality within the given relative tolerance
Arguments:
  • p1 – first identifier slice to compare
  • p2 – second identifier slice to compare
  • eps – relative tolerance for testing equality (optional argument, default 1.0e-14)

The following three tests will all succeed.

p1(i) := 1;
p2(i) := 1 + 9.9e-15;
aimmsunit::AssertTrue("p1 should be equal to p2 within relative tolerance", aimmsunit::CompareEqual(p1,p2));

p1(i) := 1;
p2(i) := 1 + 1.1e-14;
aimmsunit::AssertFalse("p1 should be unequal to p2 within relative tolerance", aimmsunit::CompareEqual(p1,p2));

p1(i) := 0;
p2(i) := 1e-15;
aimmsunit::AssertTrue("p1 should be equal to p2 within absolute tolerance", aimmsunit::CompareEqual(p1,p2));