All the code in this chapter uses standard C++, which builds on any modern C++ 17 or later compiler and standard library. Future chapters will require C++ 20 but for now, only C++ 17 is needed. The number refers to the year that the standard was approved and finalized, so C++ 17 was released in 2017 and C++ 20 was released in 2020. Each release adds new features and capabilities to the language.

The code we’ll be working with starts with an empty console project with a single source file called main.cpp.

If your development environment gives you a “Hello, world!” project when starting a new command line or console project, you can delete the contents of the main.cpp file because this chapter will start from the very beginning with an empty file.

You can find all the code for this chapter at the following GitHub repository: https://github.com/PacktPublishing/Test-Driven-Development-with-CPP.

Before we start learning about test-driven development, what it is, and what the process involves, let’s step back and think about what we want. Without knowing all the details about what a test is, let’s ask ourselves what our tests should look like.

I like to relate programming concepts to everyday experiences whenever possible. Maybe you have an idea to solve a problem that you have noticed and want to see whether your idea will work. If you wanted to test this idea before announcing it to the world, how would you do it?

You probably won’t be able to test everything to do with your idea at once. What would that even mean? There are probably small parts of your idea that you can think about initially. These should be easier to test and should help to clarify your idea and get you to think of other things to test.

So, let’s focus on simply testing small parts of the idea, whatever it is. You’d want to get everything set up and then start some actions or steps that should tell you whether each part works or not. Some of your tests might work well and some might cause you to rethink your idea. This is definitely better than jumping into the full idea without knowing whether it will work or not.

To put this into a real context, let’s say you have an idea to build a better broom. That’s a vague idea that’s hard to envision. However, let’s say that while sweeping the floor recently, you noticed your arms getting sore and thought that there had to be a better way. Thinking about the actual problem is a good way to turn a vague idea into something with a more solid meaning.

Now, you might start thinking about testing broom handles of different shapes, different grips, or different sweeping motions. These are the smaller parts of the idea that can be tested. You can take each grip or motion and turn it into a set of steps or actions that will test that part until you find one that works best.

Well, in programming, a set of steps can be a function. It doesn’t matter what that function does right now. We can think of each test as represented by a function. If you can call a function and it gives you the expected result, then you can say that the test passed. We’ll build on this idea throughout this book.

Now that we’ve decided to use a function for a test, what should it look like? After all, there are lots of ways to write a function.

It should be as simple to write a test as it is to declare and write a function, and we should be able to simplify things even further. A normal function can have whatever return type you want, a name, a set of parameters, and a body of code.

A function is also something that you write so that it can be called by other code. This code should know what the function does, what it returns, and what arguments need to be passed. We’ll keep things simple for our test functions and only worry about the name for now.

We want each test function to have its own name. Otherwise, how would we be able to keep track of all the various tests we’ll eventually be writing? As for the return type, we haven’t identified an actual need yet, so we’ll use void.

You’ll learn more about this process in Chapter 3, The TDD Process. When using TDD, don’t get ahead of yourself. Only do what you need to do at the time. As with the void return type, we’ll also not have any parameters.

It might seem too simple but this is a good start. So far, a test is nothing more than a function, which returns nothing and takes no parameters. It has a name to identify it and will include whatever code is needed to run the test.

Because we’re going to start using TDD to help design a simple testing library, our first test should ensure that we can create a test. This is a simple start, which defines a test function and calls it from main. All of this is in a single file called main.cpp:

#include <iostream>
void testCanBeCreated ()
{
    std::cout << "testCanBeCreated" << std::endl;
}
int main ()
{
    testCanBeCreated();
    return 0;
}

You might be thinking that this is not a test, it’s just a function that prints its own name, and you’d be right. We’re going to build it up from the very beginning in an agile manner using only what we have available. Right now, we don’t have a test library to use yet.

Still, this is starting to resemble what we eventually want. We want a test to be just like writing a function. If you build and run the project now, the output is as expected:

testCanBeCreated
Program ended with exit code: 0

This shows the output from running the program. It displays the name of the function. The text in the second line actually comes from my development tools and shows the program exit code. The exit code is the value returned from main.

This is a start but it can be improved. The next section will look at what information a test needs, such as its name.

The current test function doesn’t really know its name. We want the test to have a name so that it can be identified but does that name really need to be the name of the function? It would be better if the name was available as data so it could be displayed without hardcoding the name inside the test body.

Equally, the current test function doesn’t have any idea of success or failure. We purposefully ignored the test result until now, but let’s think about it. Is it enough for a test function to return the status? Maybe it needs a bool return type where true would mean success and false would mean the test failed.

That might be a bit too simplistic. Sure, it would be enough for now, but if a test fails, it might be good to know why. A bool return type won’t be enough later. Instead of designing the entire solution, we just need to figure out what to do that will meet the expected needs.

Since we already know that we need some data to hold the test name, what if we now add simple bool result data in the same place? This would let us keep the test function return type as void, and it leaves room for a more advanced solution later.

Let’s change the test function into a functor as follows so that we can add member data for the name and result. This new design moves away from using a simple function for a test. We need a class to hold the data for the name and result. A functor is a class that can be called like a function using operator(), as this code shows:

#include <iostream>
#include <string_view>
class Test
{
public:
    Test (std::string_view name)
    : mName(name), mResult(true)
    {}
    void operator () ()
    {
        std::cout << mName << std::endl;
    }
private:
    std::string mName;
    bool mResult;
};
Test test("testCanBeCreated");
int main ()
{
    test();
    return 0;
}

The biggest problem with this is that we no longer have a simple way to write a test as if it was a simple function. By providing operator (), or function call operator, we created a functor that will let us call the class as if it was a function from within the main function. However, it’s more code to write. It solves the problem of the test name, gives us a simple solution for the result, which can be expanded later, and also solves another problem that wasn’t obvious before.

When we called the test function in main before, we had to call it by the function name. That’s how functions are called in code, right? This new design eliminates that coupling by creating an instance of the Test functor called test. Now, main doesn’t care about the test name. It only refers to the instance of the functor. The only place in which the name of the test now appears in the code is when the functor instance is created.

We can fix the problem of all the extra code needed to write a test by using a macro. Macros are not needed in C++ as they used to be and some people might even think that they should be removed from the language entirely. They do have a couple of good uses left and wrapping up code into a macro is one of them.

We’ll eventually put the macro definition into a separate header file, which will become the test library. What we want to do is wrap up all the functor code in the macro but leave the implementation of the actual test function body to be written as if everything was a normal function.

First, we’ll make a simple change to move the implementation of the test function body outside of the class definition, like this. The function call operator is the method that needs to be moved outside:

class Test
{
public:
    Test (std::string_view name)
    : mName(name), mResult(true)
    {}
    void operator () ();
private:
    std::string mName;
    bool mResult;
};
Test test("testCanBeCreated");
void Test::operator () ()
{
    std::cout << mName << std::endl;
}

Then, the class definition, instance declaration, and first line of the function call operator can be turned into a macro. Compare the following code with the previous code to see how the Test class is turned into the TEST macro. By itself, this macro would not compile because it leaves the function call operator in an unfinished state. That’s exactly what we want because it lets the code use the macro like a function signature declaration and finish it up by providing the code inside the curly braces:

#define TEST class Test \
{ \
public: \
    Test (std::string_view name) \
    : mName(name), mResult(true) \
    {} \
    void operator () (); \
private: \
    std::string mName; \
    bool mResult; \
}; \
Test test("testCanBeCreated"); \
void Test::operator () ()
TEST
{
    std::cout << mName << std::endl;
}

Because the macro is defined over multiple lines, each line except the last needs to end with a backslash. The macro is a little more compact because the empty lines have been removed. This is a personal choice and you can leave the empty lines if you want. An empty line still needs the backslash though, which defeats the purpose of having an empty line.

The code uses the TEST macro with the unfinished function call operator just like a function definition, but then it completes the code by providing the curly braces and method implementation needed.

We’re making progress! It might be hard to see it because everything is in a single file. Let’s fix that by creating a new file called Test.h and moving the macro definition to the new file, like this:

#ifndef TEST_H
#define TEST_H
#include <string_view>
#define TEST class Test \
{ \
public: \
    Test (std::string_view name) \
    : mName(name), mResult(true) \
    {} \
    void operator () (); \
private: \
    std::string mName; \
    bool mResult; \
}; \
Test test("testCanBeCreated"); \
void Test::operator () ()
#endif // TEST_H

Now, we can go back to simpler code in main.cpp, like this next block of code shows. All we need to do is include Test.h and we can use the macro:

#include "Test.h"
#include <iostream>
TEST
{
    std::cout << mName << std::endl;
}
int main ()
{
    test();
    return 0;
}

We now have something that’s beginning to look like the simple function we started with, but there’s a lot of code hidden inside the TEST macro to make it seem simple.

In the next section, we’ll fix the need for main to call test() directly. The name of the functor, test, is a detail that should not be known outside of the macro, and we definitely shouldn’t need to call a test directly to run it, no matter what it’s called.

Calling the test directly might not seem like a big problem right now because we only have one test. However, as more tests are added, the need to call each one from main will lead to problems. Do you really want to have to modify the main function every time you add or remove a test?

The C++ language doesn’t have a way to add extra custom information to a function or a class that could be used to identify all the tests. So, there is no way to look through all the code, find all the tests automatically, and run them.

One of the tenets of C++ is to avoid adding language features that you might not need, especially language features that affect your code without your awareness. Other languages might let you do other things, such as adding custom attributes, which you can use to identify tests. C++ defines standard attributes, which are intended to help the compiler optimize code execution or improve the compilation of your code. The standard C++ attributes are not something that we can use to identify tests and custom attributes would go against the tenet of unneeded features. I like this about C++, even if it means that we have to work a little harder to figure out which tests to run.

All we need to do is let each test identify itself. This is different from writing code that would try to find the tests. Finding the tests requires that they be marked in some way, such as using an attribute, so that they stand out and this isn’t possible in C++. Instead of finding them, we can use the constructor of each test functor so that they register themselves. The constructor for each test will add itself to the registry by pushing a pointer to itself onto a collection.

Once all the tests are registered through addition to a collection, we can go through the collection and run them all. We already simplified the tests so that they can all be run in the same way.

There’s just one complication that we need to be careful about. The test instances that are created in the TEST macro are global variables and can be spread out over many different source files. Right now, we have a single test declared in a single main.cpp source file. We’ll need to make sure that the collection that will eventually hold all the registered tests is set up and ready to hold the tests before we start trying to add tests to the collection. We’ll use a function to help coordinate the setup. This is the getTests function, shown in the following code. The way getTests works is not obvious and is described in more detail after the next code.

Now is also a good time to start thinking about a namespace to put the testing library into. We need a name for the namespace. I thought about what qualities stand out in this testing library. Especially when learning something like TDD, simplicity seems important, as is avoiding extra features that might not be needed. I came up with the word mere. I like the definition of mere: being nothing more nor better than. So, we’ll call the namespace MereTDD.

Here is the first part of the Test.h file with the new namespace and registration code added. We should also update the include guard to something more specific, such as MERETDD_TEST_H, like this:

#ifndef MERETDD_TEST_H
#define MERETDD_TEST_H
#include <string_view>
#include <vector>
namespace MereTDD
{
class TestInterface
{
public:
    virtual ~TestInterface () = default;
    virtual void run () = 0;
};
std::vector<TestInterface *> & getTests ()
{
    static std::vector<TestInterface *> tests;
    return tests;
}
} // namespace MereTDD

Inside the namespace, there is a new TestInterface class declared with a run method. I decided to move away from a functor and to this new design because when we need to actually run the test later, it looks more intuitive and understandable to have a method called run.

The collection of tests is stored in a vector of TestInterface pointers. This is a good place to use raw pointers because there is no ownership implied. The collection will not be responsible for deleting these pointers. The vector is declared as a static variable inside the getTests function. This is to make sure that the vector is properly initialized, even if it is first accessed from another .cpp source file compilation unit.

C++ language makes sure that global variables are initialized before main begins. That means we have code in the test instance constructors that get run before main begins. When we have multiple .cpp files later, making sure that the collection is initialized first becomes important. If the collection is a normal global variable that is accessed directly from another compilation unit, then it could be that the collection is not yet ready when the test tries to push itself onto the collection. Nevertheless, by going through the getTests function, we avoid the readiness issue because the compiler will make sure to initialize the static vector the first time that the function is called.

We need to scope references to classes and functions declared inside the namespace anytime they are used within the macro. Here is the last part of Test.h, with changes to the macro to use the namespace:

#define TEST \
class Test : public MereTDD::TestInterface \
{ \
public: \
    Test (std::string_view name) \
    : mName(name), mResult(true) \
    { \
        MereTDD::getTests().push_back(this); \
    } \
    void run () override; \
private: \
    std::string mName; \
    bool mResult; \
}; \
Test test("testCanBeCreated"); \
void Test::run ()
#endif // MERETDD_TEST_H

The Test constructor now registers itself by calling getTests and pushing back a pointer to itself to the vector it gets. It doesn’t matter which .cpp file is being compiled now. The collection of tests will be fully initialized once getTests returns the vector.

The TEST macro remains outside of the namespace because it doesn’t get compiled here. It only gets inserted into other code whenever the macro is used. That’s why inside the macro, it now needs to qualify TestInterface and the getTests call with the MereTDD namespace.

Inside main.cpp, the only change is how to call the test. We no longer refer to the test instance directly and now iterate through all the tests and call run for each one. This is the reason I decided to use a method called run instead of the function call operator:

int main ()
{
    for (auto * test: MereTDD::getTests())
    {
        test->run();
    }
    return 0;
}

We can simplify this even more. The code in main seems like it needs to know too much about how the tests are run. Let’s create a new function called runTests to hold the for loop. We might later need to enhance the for loop and this seems like it should be internal to the test library. Here is what main should look like now:

int main ()
{
    MereTDD::runTests();
    return 0;
}

We can enable this change by adding the runTests function to Test.h inside the namespace, like this:

namespace MereTDD
{
class TestInterface
{
public:
    virtual ~TestInterface () = default;
    virtual void run () = 0;
};
std::vector<TestInterface *> & getTests ()
{
    static std::vector<TestInterface *> tests;
    return tests;
}
void runTests ()
{
    for (auto * test: getTests())
    {
        test->run();
    }
}
} // namespace MereTDD

After all these changes, we have a simplified main function that just calls on the test library to run all the tests. It doesn’t know anything about which tests are run or how. Even though we still have a single test, we’re creating a solid design that will support multiple tests.

The next section explains how you will use tests by looking at the first test.

So far, we have a single test that outputs its name when run, and this test is declared inside of main.cpp. This is not how you’ll want to declare your tests going forward. I’ve mentioned having multiple .cpp files with multiple tests in each one. We’re not ready for that yet but we can at least move the single test that we have into its own .cpp file.

The whole point of declaring multiple tests in multiple .cpp files is to help organize your tests. Group them into something meaningful. We’ll get to multiple tests later. For now, what is the purpose of our single test?

It is supposed to show that a test can be created. There may be other aspects of test creation that we’ll be interested in. So, it might make sense to create a .cpp file focused on test creation. Inside this .cpp file would be all the tests relating to different ways to create tests.

You can organize your tests however you want. If you have a project you are working on that has its own set of source files, it might make sense to group your tests around the source files. So, you would have a test .cpp file with many tests inside, which are all designed to test everything related to a .cpp file from your actual project. This would make sense if your project files were already organized well.

Or, you might take a more functional approach to organizing your tests. Since we only have a single header file called Test.h that we need to test, instead of also creating a single .cpp file to hold all the tests, let’s take a functional approach and split the tests based on their purpose.

Let’s add a new .cpp file to the project called Creation.cpp and move the single test that we have so far into the new file. At the same time, let’s think for a moment about how we will use the test library later on.

What we’re building is not really a library that gets compiled and linked into another project. It’s just a single header file called Test.h, which other projects can include. It’s still a library, just one that gets compiled alongside the other project.

We can even start treating the tests we have now this way. In the project structure, we have Test.h and main.cpp so far. The main.cpp file is similar to that of the test project that is intended to test the Test.h include file. Let’s reorganize the project structure so that both main.cpp and the new Creation.cpp files are in a folder called tests. These will form the basis for a testing executable that exercises all the tests needed to test Test.h. In other words, we’re turning the console project that we have into a test project designed to test the test library. The test library is not a separate project because it’s just a single header file that will be included as part of other projects.

Later on, in other projects of your own, you can do the same thing. You’ll have your primary project with all its source files. You’ll also have another test project in a subfolder called tests with its own main.cpp and all the test files. Your test project will include Test.h from the test library but it won’t be trying to test the test library as we’re doing here. It will instead be focused on testing your own project in the primary project folder. You’ll see how all this works once we get the test library to a suitable state so that it can be used to create a different project. We’ll be creating a logging library in Part 2, Logging Library. The logging library will have a subfolder called tests, as I just described.

Turning back to what we have now, let’s reorganize the overall project structure for the test library. You can create the tests folder and move main.cpp into it. Make sure to place the new Creation.cpp file into the tests folder. The project structure should look like this:

MereTDD project root folder
    Test.h
    tests folder
        main.cpp
        Creation.cpp

The main.cpp file can be simplified like this by removing the test and leaving only main:

#include "../Test.h"
int main ()
{
    MereTDD::runTests();
    return 0;
}

Now, the new Creation.cpp file only contains the single test we have so far, like so:

#include "../Test.h"
#include <iostream>
TEST
{
    std::cout << mName << std::endl;
}

However, building the project like so now gives a linker error, because we are including Test.h in both the main.cpp and the Creation.cpp compilation units. As a result, we have two methods that result in duplicate symbols. In order to remove the duplicate symbols, we need to declare both getTests and runTests to be inline, like this:

inline std::vector<TestInterface *> & getTests ()
{
    static std::vector<TestInterface *> tests;
    return tests;
}
inline void runTests ()
{
    for (auto * test: getTests())
    {
        test->run();
    }
}

Now, everything builds and runs again and we get the same result as before. The output displays the name of the single test we have so far:

testCanBeCreated
Program ended with exit code: 0

The output remains unchanged from before. We haven’t added any more tests or changed what the current test does. We have changed how the tests are registered and run, and we have reorganized the project structure.

This chapter has introduced the test library, which consists of a single header file called Test.h. It has also shown us how to create a test project, which is a console application that will be used to test the test library.

We have seen how this has evolved from a simple function into a test library that knows how to register and run tests. It’s not ready yet. We still have a way to go before the test library can be used in a TDD process to help you design and test your own projects.

By seeing how the test library evolves, you’ll come to understand how to use it in your own projects. In the next chapter, you’ll understand the challenges of adding multiple tests. There’s a reason why we only have a single test so far. Enabling multiple tests and reporting the results of the tests is what the next chapter will cover.