Skip to content

Commit

Permalink
Merge pull request #1687 from thetic/dox
Browse files Browse the repository at this point in the history
README polish
  • Loading branch information
basvodde committed Dec 7, 2022
2 parents f6b24c9 + 989cd87 commit ef24835
Showing 1 changed file with 64 additions and 68 deletions.
132 changes: 64 additions & 68 deletions README.md
@@ -1,56 +1,54 @@
CppUTest
========
# CppUTest

[![Github Actions](https://github.com/cpputest/cpputest/actions/workflows/basic.yml/badge.svg)](https://github.com/cpputest/cpputest/actions/workflows/basic.yml)
[![GitHub Actions](https://github.com/cpputest/cpputest/actions/workflows/basic.yml/badge.svg)](https://github.com/cpputest/cpputest/actions/workflows/basic.yml)
[![AppveyorBuild status](https://ci.appveyor.com/api/projects/status/irh38i4wblsb5tew?svg=true)](https://ci.appveyor.com/project/basvodde/cpputest)
[![CircleCI status](https://circleci.com/gh/cpputest/cpputest.svg?style=svg)](https://app.circleci.com/pipelines/github/cpputest)
[![Coverage Status](https://coveralls.io/repos/cpputest/cpputest/badge.svg?branch=master&service=github)](https://coveralls.io/github/cpputest/cpputest?branch=master)
[![ConanCenter package](https://repology.org/badge/version-for-repo/conancenter/cpputest.svg)](https://conan.io/center/cpputest)

Obsolete:
[![Travis Build Status (deprecated)](https://app.travis-ci.com/cpputest/cpputest.svg?branch=master)](https://app.travis-ci.com/github/cpputest/cpputest)


CppUTest unit testing and mocking framework for C/C++

[More information on the project page](https://cpputest.github.io)


Slack channel:
[Join if link not expired](https://join.slack.com/t/cpputest/shared_invite/zt-epq97u9h-6yBQHHl2cvUADjEENtdASw)

## Getting Started

You'll need to do the following to get started:

Building from source (unix-based, cygwin, MacOSX):
Building from source (Unix-based, Cygwin, MacOS):

* git clone git://github.com/cpputest/cpputest.git
* cd cpputest_build
* autoreconf .. -i
* ../configure
* make
```bash
git clone git://github.com/cpputest/cpputest.git
cd cpputest_build
autoreconf .. -i
../configure
make
```

You can use `make install` if you want to install CppUTest system-wide
You can use `make install` if you want to install CppUTest system-wide.

You can also use CMake, which also works for Windows Visual Studio.

* Download latest version
* cmake CMakeLists.txt
* make
```bash
git clone git://github.com/cpputest/cpputest.git
cmake -B cpputest_build
cmake --build cpputest_build
```

Then to get started, you'll need to do the following:

* Add the include path to the Makefile. Something like:
* CPPFLAGS += -I$(CPPUTEST_HOME)/include
* `CPPFLAGS += -I$(CPPUTEST_HOME)/include`
* Add the memory leak macros to your Makefile (needed for additional debug info!). Something like:
* CXXFLAGS += -include $(CPPUTEST_HOME)/include/CppUTest/MemoryLeakDetectorNewMacros.h
* CFLAGS += -include $(CPPUTEST_HOME)/include/CppUTest/MemoryLeakDetectorMallocMacros.h
* `CXXFLAGS += -include $(CPPUTEST_HOME)/include/CppUTest/MemoryLeakDetectorNewMacros.h`
* `CFLAGS += -include $(CPPUTEST_HOME)/include/CppUTest/MemoryLeakDetectorMallocMacros.h`
* Add the library linking to your Makefile. Something like:
* LD_LIBRARIES = -L$(CPPUTEST_HOME)/lib -lCppUTest -lCppUTestExt
* `LD_LIBRARIES = -L$(CPPUTEST_HOME)/lib -lCppUTest -lCppUTestExt`

After this, you can write your first test:

```C++
```cpp
TEST_GROUP(FirstTestGroup)
{
};
Expand All @@ -63,51 +61,50 @@ TEST(FirstTestGroup, FirstTest)
## Command line switches
* -h help, shows the latest help, including the parameters we've implemented after updating this README page.
* -v verbose, print each test name as it runs
* -r# repeat the tests some number of times, default is one, default if # is not specified is 2. This is handy if you are experiencing memory leaks related to statics and caches.
* -s# random shuffle the test execution order. # is an integer used for seeding the random number generator. # is optional, and if omitted, the seed value is chosen automatically, which results in a different order every time. The seed value is printed to console to make it possible to reproduce a previously generated execution order. Handy for detecting problems related to dependencies between tests.
* -g group only run test whose group contains the substring group
* -n name only run test whose name contains the substring name
* -f crash on fail, run the tests as normal but, when a test fails, crash rather than report the failure in the normal way
* `-h` help, shows the latest help, including the parameters we've implemented after updating this README page.
* `-v` verbose, print each test name as it runs
* `-r#` repeat the tests some number of times, default is one, default if # is not specified is 2. This is handy if you are experiencing memory leaks related to statics and caches.
* `-s#` random shuffle the test execution order. # is an integer used for seeding the random number generator. # is optional, and if omitted, the seed value is chosen automatically, which results in a different order every time. The seed value is printed to console to make it possible to reproduce a previously generated execution order. Handy for detecting problems related to dependencies between tests.
* `-g` group only run test whose group contains the substring group
* `-n` name only run test whose name contains the substring name
* `-f` crash on fail, run the tests as normal but, when a test fails, crash rather than report the failure in the normal way
## Test Macros
* TEST(group, name) - define a test
* IGNORE_TEST(group, name) - turn off the execution of a test
* TEST_GROUP(group) - Declare a test group to which certain tests belong. This will also create the link needed from another library.
* TEST_GROUP_BASE(group, base) - Same as TEST_GROUP, just use a different base class than Utest
* TEST_SETUP() - Declare a void setup method in a TEST_GROUP - this is the same as declaring void setup()
* TEST_TEARDOWN() - Declare a void setup method in a TEST_GROUP
* IMPORT_TEST_GROUP(group) - Export the name of a test group so it can be linked in from a library. Needs to be done in main.
* `TEST(group, name)` - define a test
* `IGNORE_TEST(group, name)` - turn off the execution of a test
* `TEST_GROUP(group)` - Declare a test group to which certain tests belong. This will also create the link needed from another library.
* `TEST_GROUP_BASE(group, base)` - Same as `TEST_GROUP`, just use a different base class than Utest
* `TEST_SETUP()` - Declare a void setup method in a `TEST_GROUP` - this is the same as declaring void `setup()`
* `TEST_TEARDOWN()` - Declare a void setup method in a `TEST_GROUP`
* `IMPORT_TEST_GROUP(group)` - Export the name of a test group so it can be linked in from a library. Needs to be done in `main`.
## Set up and tear down support
* Each TEST_GROUP may contain a setup and/or a teardown method.
* setup() is called prior to each TEST body and teardown() is called after the test body.
* Each `TEST_GROUP` may contain a `setup` and/or a `teardown` method.
* `setup()` is called prior to each `TEST` body and `teardown()` is called after the test body.
## Assertion Macros
The failure of one of these macros causes the current test to immediately exit
* CHECK(boolean condition) - checks any boolean result
* CHECK_TRUE(boolean condition) - checks for true
* CHECK_FALSE(boolean condition) - checks for false
* 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.
* 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 const void *
* DOUBLES_EQUAL(expected, actual, tolerance) - Compares two doubles within some tolerance
* ENUMS_EQUAL_INT(excepted, actual) - Compares two enums which their underlying type is int
* ENUMS_EQUAL_TYPE(underlying_type, excepted, actual) - Compares two enums which they have the same underlying type
* FAIL(text) - always fails
* TEST_EXIT - Exit the test without failure - useful for contract testing (implementing an assert fake)
* `CHECK(boolean condition)` - checks any boolean result
* `CHECK_TRUE(boolean condition)` - checks for true
* `CHECK_FALSE(boolean condition)` - checks for false
* `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.
* `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 `const void *`
* `DOUBLES_EQUAL(expected, actual, tolerance)` - Compares two doubles within some tolerance
* `ENUMS_EQUAL_INT(excepted, actual)` - Compares two enums which their underlying type is `int`
* `ENUMS_EQUAL_TYPE(underlying_type, excepted, actual)` - Compares two enums which they have the same underlying type
* `FAIL(text)` - always fails
* `TEST_EXIT` - Exit the test without failure - useful for contract testing (implementing an assert fake)
Customize `CHECK_EQUAL` to work with your types that support `operator==()`
Customize CHECK_EQUAL to work with your types that support operator==()
* Create the function: `SimpleString StringFrom(const yourType&)`
- Create the function: `SimpleString StringFrom(const yourType&)`
The Extensions directory has a few of these.
Expand All @@ -120,7 +117,7 @@ The Extensions directory has a few of these.
Example of a main with a TestPlugin:
```C++
```cpp
int main(int ac, char** av)
{
LogPlugin logPlugin;
Expand All @@ -136,19 +133,19 @@ Memory leak detection
* A platform specific memory leak detection mechanism is provided.
* If a test fails and has allocated memory prior to the fail and that memory is not cleaned up by TearDown, a memory leak is reported.
It is best to only chase memory leaks when other errors have been eliminated.
* Some code uses lazy initialization and appears to leak when it really does not (for example: gcc stringstream used to in an earlier release). One cause is that some standard library calls allocate something and do not free it until after main (or never).
To find out if a memory leak is due to lazy initialization set the -r switch to run tests twice. The signature of this situation is that the first run shows leaks and the second run shows no leaks. When both runs show leaks, you have a leak to find.
* Some code uses lazy initialization and appears to leak when it really does not (for example: gcc stringstream used to in an earlier release). One cause is that some standard library calls allocate something and do not free it until after `main` (or never).
To find out if a memory leak is due to lazy initialization set the `-r` switch to run tests twice. The signature of this situation is that the first run shows leaks and the second run shows no leaks. When both runs show leaks, you have a leak to find.

## How is memory leak detection implemented?

* Before setup() a memory usage checkpoint is recorded
* After teardown() another checkpoint is taken and compared to the original checkpoint
* Before `setup()` a memory usage checkpoint is recorded
* After `teardown()` another checkpoint is taken and compared to the original checkpoint
* In Visual Studio the MS debug heap capabilities are used
* For GCC a simple new/delete count is used in overridden operators new, new[], delete and delete[]
* For GCC a simple new/delete count is used in overridden operators `new`, `new[]`, `delete` and `delete[]`

If you use some leaky code that you can't or won't fix you can tell a TEST to ignore a certain number of leaks as in this example:

```C++
```cpp
TEST(MemoryLeakWarningTest, Ignore1)
{
EXPECT_N_LEAKS(1);
Expand All @@ -158,7 +155,7 @@ TEST(MemoryLeakWarningTest, Ignore1)
## Example Main
```C++
```cpp
#include "CppUTest/CommandLineTestRunner.h"
int main(int ac, char** av)
Expand All @@ -169,7 +166,7 @@ int main(int ac, char** av)

## Example Test

```C++
```cpp
#include "CppUTest/TestHarness.h"
#include "ClassName.h"

Expand Down Expand Up @@ -200,7 +197,7 @@ TEST(ClassName, Create)
```
There are some scripts that are helpful in creating your initial h, cpp, and
Test files. See scripts/README.TXT
Test files. See scripts/README.TXT
## Conan
Expand Down Expand Up @@ -229,10 +226,9 @@ target_link_libraries(example_test PRIVATE
CppUTest::CppUTestExt)
```


## Integration as external CMake project

Sometimes you want to use CppUTest in your project without installing it to your system or for having control over the version you are using. This little snippet get the wanted version from Github and builds it as a library.
Sometimes you want to use CppUTest in your project without installing it to your system or for having control over the version you are using. This little snippet get the wanted version from GitHub and builds it as a library.

```cmake
# CppUTest
Expand Down

0 comments on commit ef24835

Please sign in to comment.