Handling of function calls explained in detail

I order to test the behavior of a higher level function it is typically not enough to look at the output it delivers. The behavior of the function itself is also of interest.

The difference between EXPECT and ALLOW macros

The macros EXPECT and ALLOW (and their MOCK variants) allows you to test this behavior. You can validate the parameters to any helper functions that is called and you can control the program flow by deciding their return values. If you want to validate if these function call happens at the right time and in the right order, you use the EXPECT macros. If you dont care about that, you use the ALLOW variants. The ALLOW and EXPECT macros takes one optional parameter - the return value that TestApe will return to the unit when the function is called.

The MOCK variants

Many times more elborate control and validation are needed than what can be achieved with the ALLOW and EXPECT macros - for that, each of them has a MOCK variant. The EXPECT_MOCK and ALLOW_MOCK takes an additional mandatory mock function parameter. These macros behaves like their counterparties, but instead of returning 0 or a simple value to the unit, these macros pass control to this mock function whenever the function is called. With the mock function more elborate tests can be written, e.g. they check the parameters, call other functions, or execute new tests. The MOCK variants takes also takes one or more optional parameters. These can later be retrieved in the mock function when it is called.

The allow, expect, and mock function lists

During any test, three lists of function call elements are maintained - the allow list, the expect list and the mock list. Each element contains information about one function, e.g. what mock to use ( if any ) and the return value to use ( if any ) Every function call made by the unit during execution of test is handled according to the information found in one of these lists.

How the program flow is affected by the contents in the function lists

When TestApe detects afunction call, the execution of the unit are affected according to the rules outlined below.

First TestApe determines if the function called are present in the mock list. If so, the function is called according to the information in this list. If the function is not found in mock list, it is then determined if it is present at the end of of the expect list. If that is the case the element from the end of the expect list is removed. A message is logged about a sucessfull validation and the function is called according to the information in the element. If TestApe cannot find the function in the top of the expect list, it then looks in the allow list. If the function is present here, the function is called according to the information in the element found. If the function call are not in the mock or the allow list and not at the end of the expect list an error message is logged and the function is just called directly without redireting to a mock and without changing its return value.

Controlling the content of the function lists

The contents of the mock list, are manually controlled by the test. Every MOCK adds to the mock list (or removes from the list if mocking of the function is disabled).

Any of the ALLOW macros will add to the allow list. In addition the contents in the allow list are inerited from the parent test and restored when the test completes.

The expect list are also inherited from the parent test and any of the EXPECT macros will add to the expect list. Any function call matching the element at end of the list will remove this element from the list. When a test completes the list must be empty, if not an error is logged.

Initial contents of the function lists

The initial content of the mock and the expect lists are empty lists.

TestApe assumes that you are interested in testing at the boundaries of your unit, so upon startup, all internal functions are automatically added to the allow list and inherited to each test. This means internal functions has to be added explicitly to the expect list, if you you want to validate the order of function calls to these funcitons. Oppositely it also means, that external functions has to be added explicitly to the allow list, if you dont want to validate the order of function calls to these functions.

testape

News

The latest headlines from Testape.com

TestApe Release 1171 available, Aug 20th 2014

It has been a long time since last official release and the list of bugfixes, features and supported platforms accumulating in the beta has grown substantially. I am happy to annouce that a new release is ready.

more

TestApe beta version available, Jul 21th 2014

New beta version is now available for download.

more

TestApe Release 880 available, Dec 3rd 2011

New is this release are support for floating point validations and function mocking. Also, MinGW has been added to the list of supported platforms.

more

Forum change, Mar 27th 2011

TestApe forum is now hosted on Proboards. Support questions can be posted here or send directly on email. Due to ...

more

TestApe beta release available, Sep 27th 2011

TestApe can now be used with MinGW GCC on windows. Also supported in this beta are floating point types in validations or when mocking functions

more

IPad update for WebTTY, May 15th 2011

A small fix for webtty scripts, to allow the usage from Apple IPads. Tab on textarea to bring up IPad keyboard - you may have to scroll webpage beneath keyboard, in order to actually see what you're typing.

TestApe Release 791 available, Apr 2nd 2010

This release contains a new flexible mocking system with default mocks automatically generated for unresolved functions. Installation packages are available for GCC/Linux, GCC/CygWin as well Visual Studio 2009/Windows XP or Vista.

more