2017-08-24 15:21:36 +02:00
|
|
|
<a id="top"></a>
|
2022-11-22 16:11:16 +01:00
|
|
|
![Catch2 logo](data/artwork/catch2-logo-small-with-background.png)
|
2013-03-21 20:21:41 +01:00
|
|
|
|
2017-11-07 19:50:55 +01:00
|
|
|
[![Github Releases](https://img.shields.io/github/release/catchorg/catch2.svg)](https://github.com/catchorg/catch2/releases)
|
2021-08-07 16:49:27 +02:00
|
|
|
[![Linux build status](https://github.com/catchorg/Catch2/actions/workflows/linux-simple-builds.yml/badge.svg)](https://github.com/catchorg/Catch2/actions/workflows/linux-simple-builds.yml)
|
|
|
|
[![Linux build status](https://github.com/catchorg/Catch2/actions/workflows/linux-other-builds.yml/badge.svg)](https://github.com/catchorg/Catch2/actions/workflows/linux-other-builds.yml)
|
|
|
|
[![MacOS build status](https://github.com/catchorg/Catch2/actions/workflows/mac-builds.yml/badge.svg)](https://github.com/catchorg/Catch2/actions/workflows/mac-builds.yml)
|
2020-10-21 19:59:59 +02:00
|
|
|
[![Build Status](https://ci.appveyor.com/api/projects/status/github/catchorg/Catch2?svg=true&branch=devel)](https://ci.appveyor.com/project/catchorg/catch2)
|
|
|
|
[![Code Coverage](https://codecov.io/gh/catchorg/Catch2/branch/devel/graph/badge.svg)](https://codecov.io/gh/catchorg/Catch2)
|
2022-06-06 00:20:55 +02:00
|
|
|
[![Try online](https://img.shields.io/badge/try-online-blue.svg)](https://godbolt.org/z/EdoY15q9G)
|
2018-07-01 20:48:21 +02:00
|
|
|
[![Join the chat in Discord: https://discord.gg/4CWS9zD](https://img.shields.io/badge/Discord-Chat!-brightgreen.svg)](https://discord.gg/4CWS9zD)
|
|
|
|
|
2023-06-27 11:44:19 +02:00
|
|
|
<!-- SPHINX-START -->
|
2013-08-05 14:50:14 +02:00
|
|
|
|
2022-10-17 21:45:32 +02:00
|
|
|
## What is Catch2?
|
2021-11-16 16:22:46 +01:00
|
|
|
|
|
|
|
Catch2 is mainly a unit testing framework for C++, but it also
|
|
|
|
provides basic micro-benchmarking features, and simple BDD macros.
|
|
|
|
|
|
|
|
Catch2's main advantage is that using it is both simple and natural.
|
2022-10-17 21:45:32 +02:00
|
|
|
Test names do not have to be valid identifiers, assertions look like
|
|
|
|
normal C++ boolean expressions, and sections provide a nice and local way
|
|
|
|
to share set-up and tear-down code in tests.
|
2021-11-16 16:22:46 +01:00
|
|
|
|
2022-10-17 21:45:32 +02:00
|
|
|
**Example unit test**
|
|
|
|
```cpp
|
|
|
|
#include <catch2/catch_test_macros.hpp>
|
2021-11-16 16:22:46 +01:00
|
|
|
|
2022-10-17 21:45:32 +02:00
|
|
|
#include <cstdint>
|
2017-11-03 14:18:26 +01:00
|
|
|
|
2022-10-17 21:45:32 +02:00
|
|
|
uint32_t factorial( uint32_t number ) {
|
|
|
|
return number <= 1 ? number : factorial(number-1) * number;
|
|
|
|
}
|
2017-11-03 14:18:26 +01:00
|
|
|
|
2022-10-17 21:45:32 +02:00
|
|
|
TEST_CASE( "Factorials are computed", "[factorial]" ) {
|
|
|
|
REQUIRE( factorial( 1) == 1 );
|
|
|
|
REQUIRE( factorial( 2) == 2 );
|
|
|
|
REQUIRE( factorial( 3) == 6 );
|
|
|
|
REQUIRE( factorial(10) == 3'628'800 );
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
**Example microbenchmark**
|
|
|
|
```cpp
|
2022-10-19 21:41:58 +02:00
|
|
|
#include <catch2/catch_test_macros.hpp>
|
2022-10-17 21:45:32 +02:00
|
|
|
#include <catch2/benchmark/catch_benchmark.hpp>
|
|
|
|
|
|
|
|
#include <cstdint>
|
|
|
|
|
|
|
|
uint64_t fibonacci(uint64_t number) {
|
2022-12-18 21:33:33 +01:00
|
|
|
return number < 2 ? number : fibonacci(number - 1) + fibonacci(number - 2);
|
2022-10-17 21:45:32 +02:00
|
|
|
}
|
|
|
|
|
|
|
|
TEST_CASE("Benchmark Fibonacci", "[!benchmark]") {
|
2022-11-23 15:48:17 +01:00
|
|
|
REQUIRE(fibonacci(5) == 5);
|
2022-10-17 21:45:32 +02:00
|
|
|
|
2022-11-23 15:48:17 +01:00
|
|
|
REQUIRE(fibonacci(20) == 6'765);
|
|
|
|
BENCHMARK("fibonacci 20") {
|
|
|
|
return fibonacci(20);
|
2022-10-17 21:45:32 +02:00
|
|
|
};
|
|
|
|
|
2022-11-23 15:48:17 +01:00
|
|
|
REQUIRE(fibonacci(25) == 75'025);
|
|
|
|
BENCHMARK("fibonacci 25") {
|
|
|
|
return fibonacci(25);
|
2022-10-17 21:45:32 +02:00
|
|
|
};
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2022-12-18 21:42:40 +01:00
|
|
|
_Note that benchmarks are not run by default, so you need to run it explicitly
|
|
|
|
with the `[!benchmark]` tag._
|
|
|
|
|
|
|
|
|
2022-10-17 21:45:32 +02:00
|
|
|
## Catch2 v3 has been released!
|
|
|
|
|
|
|
|
You are on the `devel` branch, where the v3 version is being developed.
|
|
|
|
v3 brings a bunch of significant changes, the big one being that Catch2
|
|
|
|
is no longer a single-header library. Catch2 now behaves as a normal
|
|
|
|
library, with multiple headers and separately compiled implementation.
|
|
|
|
|
|
|
|
The documentation is slowly being updated to take these changes into
|
|
|
|
account, but this work is currently still ongoing.
|
2020-10-30 15:31:41 +01:00
|
|
|
|
2020-10-31 09:08:58 +01:00
|
|
|
For migrating from the v2 releases to v3, you should look at [our
|
|
|
|
documentation](docs/migrate-v2-to-v3.md#top). It provides a simple
|
|
|
|
guidelines on getting started, and collects most common migration
|
|
|
|
problems.
|
|
|
|
|
2022-10-17 21:45:32 +02:00
|
|
|
For the previous major version of Catch2 [look into the `v2.x` branch
|
|
|
|
here on GitHub](https://github.com/catchorg/Catch2/tree/v2.x).
|
|
|
|
|
2020-10-30 15:31:41 +01:00
|
|
|
|
2013-06-03 21:03:39 +02:00
|
|
|
## How to use it
|
|
|
|
This documentation comprises these three parts:
|
|
|
|
|
2017-08-24 15:33:38 +02:00
|
|
|
* [Why do we need yet another C++ Test Framework?](docs/why-catch.md#top)
|
|
|
|
* [Tutorial](docs/tutorial.md#top) - getting started
|
|
|
|
* [Reference section](docs/Readme.md#top) - all the details
|
2013-06-03 21:03:39 +02:00
|
|
|
|
2020-10-30 15:31:41 +01:00
|
|
|
|
2013-06-03 21:03:39 +02:00
|
|
|
## More
|
2017-11-03 14:05:09 +01:00
|
|
|
* Issues and bugs can be raised on the [Issue tracker on GitHub](https://github.com/catchorg/Catch2/issues)
|
2021-11-16 14:36:29 +01:00
|
|
|
* For discussion or questions please use [our Discord](https://discord.gg/4CWS9zD)
|
2021-11-16 16:22:46 +01:00
|
|
|
* See who else is using Catch2 in [Open Source Software](docs/opensource-users.md#top)
|
|
|
|
or [commercially](docs/commercial-users.md#top).
|
2023-06-27 11:44:19 +02:00
|
|
|
|
|
|
|
<!-- SPHINX-END -->
|