Skip to main content

A code generator and test runner for C++

Project description

Meliorate

Meliorate is a code generator and test runner for C++.

It aims to:

  • Simplify the writing and execution of tests.
  • Minimise the amount of strange code (macro magic) often associated with C++ unit test libraries.

Meliorate uses Clang to identify test functions (functions beginning with the word test) and generates all code necessary to run test functions automatically.

Prerequisits

Requires:

  • Python3.7+
  • Clang (dev only)

Getting started

Meliorate comes in two parts:

  • meliorate.h which includes the meliorate_run function for running tests and other useful parameters for customising test execution.
  • meliorateapp which is the code generator.

meliorate.h should be included into you project by adding a compiler include flag (-I) that points to the include directory (and not the include/meliorate directory).

The meliorateapp can be installed from PyPi.

pip install meliorate

Using Meliorate

Write some test functions:

#include "meliorate/meliorate.h"

void test_that_something_is_true()
{
    // code goes here.
}

// Not extracted as a test function because the function name
// does not begin with "test".
int not_a_test_function()
{
    return 0;
}

void test_that_error_is_thrown()
{
    throw std::runtime_error("Something went wrong.");
}


void test_that_the_result_is_42()
{
    // code goes here.
}

// Not extracted as a test function because the function is static.
static void test_that_something_is_false()
{
    // code goes here.
}

Add the meliorate_run function to main:

#include "meliorate/meliorate.h"

int main()
{
    meliorate_stop_on_error = false;
    return meliorate_run<std::exception>();
}

Meliorate assumes your assertion library will use exceptions from the standard library by default (hence why meliorate_run is parameterized with std::exception). To use a custom assertion library, see the Customising Assertions section for more information.

Run the meliorateapp on the test directory:

meliorateapp <path/to/test/directory>

Check that meliorate_gen.cpp is created in the test directory.

Finally, compile and run you test program as normal, remembering to add meliorate_gen.cpp to your build process.

The output will look something like:

[RUN     ] test_that_something_is_true
[  PASSED]
[RUN     ] test_that_error_is_thrown
Something went wrong.
[  FAILED]
[RUN     ] test_that_the_result_is_42
[  PASSED]
1 tests FAILED out of 3

You can force test execution to stop when an error occurs by setting meliorate_stop_on_error variable to true prior to calling the meliorate_run function.

Customising Assertions

Meliorate does not provide any assertions, but by default assumes that the assertion library will use exceptions from the standard library. Should you wish to use another library, such as snowhouse, follow the instructions below:

Provide a specialisation for the meliorate_handle_exception function. This function handles the printing of the exception when an error occurs. By default the function looks like:

template <typename T>
void meliorate_handle_exception(T const& exception)
{
    std::cerr << exception.what() << std::endl;
}

Provide the specialisation like so:

template <typename T>
void meliorate_handle_exception(snowhouse::AssertionException const& exception)
{
    std::cerr << ex.GetMessage() << std::endl;
}

Then set the template parameter for the meliorate_run function:

#include "meliorate/meliorate.h"

int main()
{
    meliorate_stop_on_error = false;
    return meliorate_run<snowhouse::AssertionException>();
}

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

meliorateapp-0.1.0.tar.gz (9.5 kB view details)

Uploaded Source

Built Distribution

meliorateapp-0.1.0-py3-none-any.whl (14.8 kB view details)

Uploaded Python 3

File details

Details for the file meliorateapp-0.1.0.tar.gz.

File metadata

  • Download URL: meliorateapp-0.1.0.tar.gz
  • Upload date:
  • Size: 9.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.0.9 CPython/2.7.16 Darwin/19.6.0

File hashes

Hashes for meliorateapp-0.1.0.tar.gz
Algorithm Hash digest
SHA256 3d95d73f70dbdf6a3c0e47d5bee266539eeff3e14147ab73a0777921202c98ac
MD5 cc2032304bab001ab0057aaee192d7df
BLAKE2b-256 5128a50c54155af6b5ad87746d224cba020eb9177bc55ee8c915aae48afe4319

See more details on using hashes here.

File details

Details for the file meliorateapp-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: meliorateapp-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 14.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.0.9 CPython/2.7.16 Darwin/19.6.0

File hashes

Hashes for meliorateapp-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 d9cf16430546f91d6617ea1cf24c71f43d22aff9b69508cfa95da13b3c5702b3
MD5 7f11227ed98712e56cea30a3f3a811ed
BLAKE2b-256 f6a22d1b4beda6c574fdff880809ae428fc5c5b2631509f4c8c42522b315c84a

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page