short_example

This example walks through the basics of ntest.

To use ntest, copy ntest.cpp and ntest.hpp somewhere into your project, and create a translation unit for your tester program. In this example, our filesystem looks like:

ntest/
│  ntest.cpp
|  ntest.hpp
|  ...
|
└───short_example/
    │  short_example.cpp

short_example.cpp is our tester program:

#include <iostream>

#include "../ntest.hpp"

int main()
{
  {
    // do some initialization...
    auto const init_result = ntest::init();
    std::cout
      << init_result.num_files_removed << " residual files removed, "
      << init_result.num_files_failed_to_remove << " failed to be removed\n";
  }

  ntest::assert_int32(1, 1); // pass!
  ntest::assert_int32(0, 1); // fail!

  ntest::assert_cstr("Hello world!", "Hello world!"); // pass!
  ntest::assert_cstr("Hello world!", "Something else"); // fail!

  {
    std::vector<int> a { 0, 1, 2, 3 };
    std::vector<int> b { 0, 1, 9, 3 };
    ntest::assert_stdvec(a, b); // fail!
    ntest::assert_stdvec(a, a); // pass!
  }

  // runs for each assertion when the markdown report is being generated
  auto const assertion_callback = [](ntest::assertion const &a, bool passed) {
    if (!passed)
      std::cout << "failed: " << a.loc.file_name() << ':' << a.loc.line() << '\n';
  };

  {
    // generate a markdown report which details all assertions
    auto const gen_res = ntest::generate_report("short_example_report", assertion_callback);
    std::cout << gen_res.num_passes << " passed, " << gen_res.num_fails << " failed\n";
  }
}

After compiling and running the tester program, the output is:

X residual files removed, 0 failed to be removed
failed: short_example.cpp:16
failed: short_example.cpp:19
failed: short_example.cpp:24
3 passed, 3 failed

Where X is simply the number of residual .expected and .actual files removed by ntest::init(). Speaking of .expected and .actual files, 2 of each were generated by the tester program, along with a markdown report:

ntest/
│  ntest.cpp
|  ntest.hpp
|  ...
|
└───simple-example/
    │  short_example.cpp
    |  NEW: short_example_report.md
    |  NEW: short_example.cpp_19.expected
    |  NEW: short_example.cpp_19.actual
    |  NEW: short_example.cpp_24.expected
    |  NEW: short_example.cpp_24.actual

• short_example_report.md is a markdown report of our assertions
• *.{expected,actual} are text files containing the serialized expected and actual value of a failed assertion - diff these to see how the values differ

In this example, the assertion:

std::vector<int> a { 0, 1, 2, 3 };
std::vector<int> b { 0, 1, 9, 3 };
ntest::assert_stdvec(a, b); // fail!

Generated the files:

• short_example.cpp_24.expected
• short_example.cpp_24.actual

Whose diff is:

0
1
-2
+9
3

And the generated markdown report informs us of this failing assertion, as well as all other assertions we made.

Note that this example was run on a Linux system, some details may vary on different operating systems (namely Windows), such as source locations and function names. The main principles remain the same.