Merge pull request #29 from arstrube/master

Include new functionality and fix up some missing

Author: basvodde

_includes/header.html

@@ -22,15 +22,17 @@ <h2>CppUTest unit testing and mocking framework for C/C++</h2>
 	        <div class="navbar navbar-inverse">
 		        <div class="navbar-inner">
 			        <a class="brand" href="index.html">CppUTest</a>
+			        <a class="brand" href='https://coveralls.io/github/arstrube/cpputest?branch=master'><img src='https://coveralls.io/repos/github/arstrube/cpputest/badge.svg?branch=master' alt='Coverage Status' /></a>
+
 			        <ul class="nav">
 			        	<li class="divider-vertical"></li>
 				        <li><a href="manual.html">Core Manual</a></li>
 			        	<li class="divider-vertical"></li>
 				        <li><a href="mocking_manual.html">CppUMock Manual</a></li>
 				        <li class="divider-vertical"></li>
-				        <li><a href="stories.html">Platforms stories</a></li>
+				        <li><a href="plugin_manual.html">Plugin Manual</a></li>
 				        <li class="divider-vertical"></li>
-				        <li><a href="docs/index.html">Doxygen</a></li>
+				        <li><a href="stories.html">Platforms stories</a></li>
 				        <li class="divider-vertical"></li>
 				        <li><a href="https://github.com/cpputest/cpputest"><span class="github_icon"></span><span>View on
 				        GitHub</span></a></li>

manual.markdown

@@ -137,15 +137,26 @@ The failure of one of these macros causes the current test to immediately exit:
 
 * CHECK(boolean condition) - checks any boolean result.
 * CHECK_TEXT(boolean condition, text) - checks any boolean result and prints text on failure.
+* CHECK_FALSE(condition) - checks any boolean result
+* CHECK_FALSE_TEXT(condition, text) - checks any boolean result and prints text on failure.
 * CHECK_EQUAL(expected, actual) - checks for equality between entities using ==. So if you have a class that supports operator==() you can use this macro to compare two instances.  You will also need to add a StringFrom() function like those found in SimpleString. This is for printing the objects when the check failed.
 * CHECK_THROWS(expected_exception, expression) - checks if expression throws expected_exception (e.g. std::exception). CHECK_THROWS is only available if CppUTest is built with the Standard C++ Library (default).
-* STRCMP_EQUAL(expected, actual) - check const char* strings for equality using strcmp().
-* LONGS_EQUAL(expected, actual) - Compares two numbers.
-* BYTES_EQUAL(expected, actual) - Compares two numbers, eight bits wide.
-* POINTERS_EQUAL(expected, actual) - Compares two pointers.
-* DOUBLES_EQUAL(expected, actual, tolerance) - Compares two doubles within some tolerance
+* STRCMP_EQUAL(expected, actual) - checks const char* strings for equality using strcmp().
+* STRNCMP_EQUAL(expected, actual, length) - checks const char* strings for equality using strncmp().
+* STRCMP_NOCASE_EQUAL(expected, actual) - checks const char* strings for equality, not considering case.
+* STRCMP_CONTAINS(expected, actual) - checks whether const char* actual contains const char* expected.
+* LONGS_EQUAL(expected, actual) - compares two numbers.
+* UNSIGNED_LONGS_EQUAL(expected, actual) - compares two positive numbers.
+* BYTES_EQUAL(expected, actual) - compares two numbers, eight bits wide.
+* POINTERS_EQUAL(expected, actual) - compares two pointers.
+* DOUBLES_EQUAL(expected, actual, tolerance) - compares two floating point numbers within some tolerance
+* FUNCTIONPOINTERS_EQUAL_TEXT(expected, actual, text) - compares two void (*)() function pointers
+* MEMCMP_EQUAL(expected, actual, size) - compares two areas of memory
+* BITS_EQUAL(expected, actual, mask) - compares expected to actual bit by bit, applying mask
 * FAIL(text) - always fails
 
+*NOTE* Many macros have _TEXT() equivalents, which are not explicitly listed here.
+
 <a id="setup_teardown"> </a>
 
 *CHECK_EQUAL Warning:*
@@ -222,16 +233,22 @@ The test execution of this will *likely* (no guarantee of order in CppUTest) be:
 
 ## Command line Switches
 
-* *-v* verbose, print each test name as it runs
 * *-c* colorize output, print green if OK, or red if failed
-* *-r#* repeat the tests some number (#) of times, or two times if # is not specified. This is handy if you are experiencing memory leaks. A second run that has no leaks indicates that someone is allocating statics and not releasing them.
-* *-g* group only run test whose group contains the substring group
-* *-sg* group only run test whose group exactly matches the string group
-* *-n* name only run test whose name contains the substring name
-* *-sn* name only run test whose name exactly matches the string name
-* *"TEST(group, name)"* only run test whose group and name matches the strings group and name. This can be used to copy-paste output from the -v option on the command line.
-* *-ojunit* output to JUnit ant plugin style xml files (for CI systems)
+* *-g group* only run test whose group contains the substring *group*
 * *-k* package name, Add a package name in JUnit output (for classification in CI systems)
+* *-lg* print a list of group names, separated by spaces
+* *-ln* print a list of test names in the form of *group.name*, separated by spaces
+* *-n name* only run test whose name contains the substring *name*
+* *-ojunit* output to JUnit ant plugin style xml files (for CI systems)
+* *-oteamcity* output to xml files (as the name suggests, for TeamCity)
+* *-p* run tests in a separate process.
+* *-r#* repeat the tests some number (#) of times, or twice if # is not specified. This is handy if you are experiencing memory leaks. A second run that has no leaks indicates that someone is allocating statics and not releasing them.
+* *-sg group* only run test whose group exactly matches the string *group*
+* *-sn name* only run test whose name exactly matches the string *name*
+* *-v* verbose, print each test name as it runs
+* *-xg group* exclude tests whose group contains the substring *group* (v3.8)
+* *-xn name* exclude tests whose name contains the substring *name* (v3.8)
+* *"TEST(group, name)"* only run test whose group and name matches the strings group and name. This can be used to copy-paste output from the -v option on the command line.
 
 You can specify multiple -s&#124;sg, -s&#124;sn and "TEST(group, name)" parameters: 
 
@@ -241,6 +258,27 @@ Specifying only test names with multiple -s&#124;sn parameters will run all test
 
 Mixing multiple -s&#124;sg and -s&#124;sn parameters (or using "TEST(group, name)" will only run tests whose groups match as well as their names.
 
+Combining one -xg parameter with one -xn parameter will run only those tests that satisfy both criteria.
+
+Combining -s&#124;sg with -xn, or -s&#124;sn with -xg will run only those tests that satisfy both criteria.
+
+Specifying several -xg or -xn with each other or in other combinations has no effect.
+
+*NOTE* Be careful with *-p*:
+
+* Some systems do not support this feature, in which case tests will fail
+  with a suitable message.
+* Using *-p* to run tests in a separate process can have unexpected side
+  effects.
+* While running tests in a separate process can help to get more information
+  about an unexpected crash, when an expected crash is part of the test scenario,
+  the *-p* command line option should not be used, but running in a separate
+  process should be enabled on a per-test basis like this:
+  {% highlight c++ %}
+  TestRegistry::getCurrentRegistry()->setRunTestsInSeperateProcess();
+  {% endhighlight %}
+  Examples for this can be found in CppUTests's own tests.
+
 <a id="memory_leak_detection"> </a>
 
 ## Memory Leak Detection
@@ -353,73 +391,10 @@ Test plugins let you add a pre-action and a post-action to each test case.  Plug
 
 * Memory leak detector (provided)
 * Pointer restore mechanism (provided) - helpful when tests overwrite a pointer that must be restored to its original value after the test.  This is especially helpful when a pointer to a function is modified for test purposes.
-* All Mutex's released - you could write a plugin that checks that any Mutexs or other shared resource is released before the test exists.
-
-Example of a main with a SetPointerPlugin:
-
-{% highlight c++ %}
-int main(int ac, char** av)
-{
-    TestRegistry* r = TestRegistry::getCurrentRegistry();
-    SetPointerPlugin ps("PointerStore");
-    r->installPlugin(&ps);
-    return CommandLineTestRunner::RunAllTests(ac, av);
-}
-
-TEST_GROUP(HelloWorld)
-{
-   static int output_method(const char* output, ...)
-   {
-      va_list arguments;
-      va_start(arguments, output);
-      cpputest_snprintf(buffer, BUFFER_SIZE, output, arguments);
-      va_end(arguments);
-      return 1;
-   }
-   void setup()
-   {
-      //overwrite the production function pointer witha an output method that captures
-      //output in a buffer.
-      UT_PTR_SET(helloWorldApiInstance.printHelloWorld_output, &output_method);
-   }
-   void teardown()
-   {
-   }
-};
-
-TEST(HelloWorld, PrintOk)
-{
-   printHelloWorld();
-   STRCMP_EQUAL("Hello World!\n", buffer)
-}
-
-//Hello.h
-#ifndef HELLO_H_
-#define HELLO_H_
-
-extern void printHelloWorld();
-
-struct helloWorldApi {
-   int (*printHelloWorld_output) (const char*, ...);
-};
-
-#endif /*HELLO_H_*/
+* IEEE754 Floating point exceptions (provided; v3.8) - automatically checks whether any floating point exception flags are set at the end of every test and if so, fails the test.
+* All Mutex's released - you could write a plugin that checks that any Mutexs or other shared resource is released before the test exits.
 
-//Hello.c
-
-#include <stdio.h>
-#include "hello.h"
-
-//in production, print with printf.
-struct helloWorldApi helloWorldApiInstance = {
-   &printf
-};
-
-void printHelloWorld()
-{
-   helloWorldApiInstance.printHelloWorld_output("Hello World!\n");
-}
-{% endhighlight %}
+Complete Documentation for provided plugins can be found on the [Plugins Manual](plugins_manual.html) page.
 
 <a id="scripts"> </a>
 
@@ -553,6 +528,22 @@ int main(int ac, char** av)
 
 You can leave out TEST_GROUP_C_SETUP() / TEST_GROUP_C_TEARDOWN() and TEST_GROUP_C_SETUP_WRAPPER() / TEST_GROUP_C_TEARDOWN_WRAPPER(), if you don't need them.
 
+The following assertion macros are supported in the pure C interface:
+
+{% highlight c++ %}
+CHECK_EQUAL_C_INT(expected,actual);
+CHECK_EQUAL_C_REAL(expected,actual,threshold);
+CHECK_EQUAL_C_CHAR(expected,actual);
+CHECK_EQUAL_C_STRING(expected,actual);
+CHECK_EQUAL_C_POINTER(expected,actual); /* v3.8 */
+CHECK_EQUAL_C_BITS(expected, actual, mask); /* v3.8, pending */
+FAIL_TEXT_C(text);
+FAIL_C();
+CHECK_C(condition);
+{% endhighlight %}
+
+These macros ensure tests get terminated in a way appropriate for pure C code.
+
 <a id="gmock"> </a>
 
 ## Using Google Mock

mocking_manual.markdown

@@ -21,12 +21,14 @@ The main idea is to make manual mocking easier, rather than to make automated mo
 * [Using Parameters](#parameters)
 * [Objects as Parameters](#objects_as_parameters)
 * [Output Parameters](#output_parameters)
+* [Output Parameters Using Objects](#output_parameters_using_objects)
 * [Return Values](#return_values)
 * [Passing other data](#other_data)
 * [Other MockSupport](#other_mock_support)
 * [MockSupport Scope](#mock_scope)
-* [MockPlugin](#mock_plugin)
+* [MockSupportPlugin](#mock_plugin)
 * [C Interface](#c_interface)
+* [Miscellaneous](#miscellaneous)
 
 <a id="simple_scenario"> </a>
 
@@ -99,6 +101,12 @@ If the call to productionCode wouldn't happen, then the test would fail with the
         ACTUAL calls that did happen:
             <none>
 
+Sometimes you expect *several identical calls* to the same function, for example five calls to productionCode. There is a convenient shorthand for that situation:
+
+{% highlight c++ %}
+mock().expectNCalls(5, "productionCode");
+{% endhighlight %}
+
 <a id="objects"> </a>
 
 ### Using Objects
@@ -213,10 +221,10 @@ public:
 
 The isEqual is called to compare the two parameters. The valueToString is called when an error message is printed and it needs to print the actual and expected values. If you want to use normal C functions, you can use the MockFunctionComparator which accepts pointers to functions in the constructor.
 
-To remove the comparators, all you needs to do is call removeAllComparators, like:
+To remove the comparators, all you needs to do is call removeAllComparatorsAndCopiers, like:
 
 {% highlight c++ %}
-mock().removeAllComparators();
+mock().removeAllComparatorsAndCopiers();
 {% endhighlight %}
 
 Comparators sometimes lead to surprises, so a couple of warnings on its usage:
@@ -251,7 +259,7 @@ mock().expectOneCall("Foo").withOutputParameterReturning("bar", &outputValue, si
 {% highlight c++ %}
 void Foo(int *bar)
 {
-    mock().actualCall("foo").withOutputParameter("bar", bar);
+    mock().actualCall("Foo").withOutputParameter("bar", bar);
 }
 {% endhighlight %}
 
@@ -287,6 +295,54 @@ mock().expectOneCall("Foo").withOutputParameterReturning("bar", &doubleOutputVal
 
 * When a char, int, etc. array is passed to withOutputParameter, you must use the generic withOutputParameterReturning and provide the actual size of the array or only one element will be copied.
 
+<a id="output_parameters_using_objects"> </a>
+
+### Output Parameters Using Objects
+
+By far the best way to handle output parameters is by using a custom type copier (v3.8). The general principle is similar to the custom comparators described above:
+
+{% highlight c++ %}
+MyType outputValue = 4;
+mock().expectOneCall("Foo").withOutputParameterOfTypeReturning("MyType", "bar",  &outputValue);
+{% endhighlight %}
+
+The corresponding actual call is:
+
+{% highlight c++ %}
+void Foo(int *bar)
+{
+    mock().actualCall("Foo").withOutputParameterOfType("MyType", "bar",  bar);
+}
+{% endhighlight %}
+
+When using withOutputParameterOfTypeReturning, the mocking framework needs to know how to copy the type and therefore a Copier has to be installed before using parameters of this type. This is done using installCopier, as below:
+
+{% highlight c++ %}
+MyTypeCopier copier;
+mock().installCopier("myType", copier);
+{% endhighlight %}
+
+MyTypeCopier is a custom copier, which implements the MockNamedValueCopier interface. For example:
+
+{% highlight c++ %}
+class MyTypeCopier : public MockNamedValueCopier
+{
+public:
+    virtual void copy(void* out, const void* in)
+    {
+        *(MyType*)out = *(const MyType*)in;
+    }
+};
+{% endhighlight %}
+
+To remove the copier, you need to call removeAllComparatorsAndCopiers, like:
+
+{% highlight c++ %}
+mock().removeAllComparatorsAndCopiers();
+{% endhighlight %}
+
+*Warning 1* and *Warning 2* above apply to copiers as well.
+
 <a id="return_values"> </a>
 
 ### Return Values
@@ -447,29 +503,9 @@ mock("filesystem").ignoreOtherCalls();
 
 <a id="mock_plugin"> </a>
 
-### MockPlugin
-
-CppUTest plugins can be installed in the main and 'extent' the unit test framework. It is a place where you can put work that needs to be done in all unit tests. There is a MockPlugin to make the work with mocks easier. It does the following work:
-
-* checkExpectations at the end of every test (on global scope, which goes recursive over all scopes)
-* clear all expectations at the end of every test
-* install all comparators that were configured in the plugin at the beginning of every test
-* remove all comparators at the end of every test
+### MockSupportPlugin
 
-Installing the MockPlugin means you'll have to add to main something like:
-
-{% highlight c++ %}
-#include "CppUTest/TestRegistry.h"
-#include "CppUTestExt/MockSupportPlugin.h"
-
-MyDummyComparator dummyComparator;
-MockSupportPlugin mockPlugin;
-
-mockPlugin.installComparator("MyDummyType", dummyComparator);
-TestRegistry::getCurrentRegistry()->installPlugin(&mockPlugin);
-{% endhighlight %}
-
-This code creates a comparator for MyDummy and installs it at the plugin. This means the comparator is available for all test cases. It creates the plugin and installs it at the current test registry. After installing the plugin, you don't have to worry too much anymore about calling checkExpectations or cleaning your MockSupport.
+There is a MockSupportPlugin to make the work with mocks easier. Complete Documentation for MockSupportPlugin can be found on the [Plugins Manual](plugins_manual.html) page.
 
 <a id="c_interface"> </a>
 
@@ -481,7 +517,7 @@ Sometimes it is useful to access the mocking framework from a .c file rather tha
 #include "CppUTestExt/MockSupport_c.h"
 
 mock_c()->expectOneCall("foo")->withIntParameters("integer", 10)->andReturnDoubleValue(1.11);
-mock_c()->actualCall("foo")->withIntParameters("integer", 10)->returnValue().value.doubleValue;
+return mock_c()->actualCall("foo")->withIntParameters("integer", 10)->returnValue().value.doubleValue;
 
 mock_c()->installComparator("type", equalMethod, toStringMethod);
 mock_scope_c("scope")->expectOneCall("bar")->withParameterOfType("type", "name", object);
@@ -495,3 +531,29 @@ mock_c()->clear();
 {% endhighlight %}
 
 The C interface uses a similar builder structure as the C++ interface. It is far less common in C, but it works the same.
+
+It is now also possible to specify the actual return value in the same way as with C++ (v3.8):
+
+{% highlight c++ %}
+return mock_c()->actualCall("foo")->withIntParameters("integer", 10)->doubleReturnValue();
+return mock_c()->doubleReturnValue();
+{% endhighlight %}
+
+and to specify a default return value, in case mocking is currently disabled when the actual call occurs (v3.8):
+
+{% highlight c++ %}
+return mock_c()->actualCall("foo")->withIntParameters("integer", 10)->returnDoubleValueOrDefault(2.25);
+return mock_c()->returnDoubleValueOrDefault(2.25);
+{% endhighlight %}
+
+<a id="miscellaneous"></a>
+
+### Miscellaneous
+
+If you want your test to be more explicit about that a certain mocked function call should not occur, you can write (v3.8):
+
+{% highlight c++ %}
+mock().expectNoCall("productionCode");
+{% endhighlight %}
+
+Doing so is functionally equivalent to stating no expectations at all.