@page Guides
@subpage TestingGuide
@page TestingGuide Testing Guide

Introduction
------------

Testing is important to ensure the program does what is intended and also
prevents bit rot. It also allows us to code more fearlessly as we can make
changes and feel confident that we have not broken things if all the tests
continue to pass.

This assumes good test coverage. So it is important to have good coverage
and to maintain this as it can be difficult to do afterwards. The best time
to add a test is when the code to be tested is written as assumptions can
be tested and makes the new functionality something that can be immediately
build on top of.

Another good time to add tests is when an issue is found or a bug fixed
as the problem is evident and it could re-occur otherwise.

There are different types of testing that can be made.

 - Unit tests
 - Integration tests
 - System tests
 - Fuzz tests
 - Penetration tests
 - Coverage tests
 - Performance test
 - and more

The minimal type of testing needed as code is written should be unit testing.

It is best if the tests are run automatically with each build, either as
part of the build system or as part of a continous integration system.

Unit Testing
------------

Here is an example of how to add a new unit test inside of the source code
along side the implementation.

This should be inside the corresponding CPP file.

```{.cpp}
// Implementation

class Example
{
public:
   int XPlusOne() { return x + 1; }
   int x = 0;
};


// Unit Tests
#if ENABLE_UNIT_TESTS

DECLARE_UNIT_TEST(UnitTestExampleInit)
{
  Example a;

  CHECK(a.x == 0);
  CHECK(a.XPlusOne() == 1);
}

DECLARE_UNIT_TEST(UnitTestExampleSet)
{
  Example a;

  a.x = 1;
  CHECK(a.x == 1);
  CHECK(a.XPlusOne() == 2);
}

#endif // ENABLE_UNIT_TESTS
```

This creates two tests, "UnitTestExampleInit" and "UnitTestExampleSet".
They creates an object of the class to be unit tested and validate the initial
state and the returned result of the method in the class under different
conditions.

Macros
------

 - DECLARE_UNIT_TEST - Creates a new test
 - CHECK             - Asserts that the condition is true