catchorg / catchorg/Catch2

Coroutine support for asynchronous tests

Open
#3,077 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
21.5k
Forks
3.5k
Avg merge
3d 16h
Merged PRs (30d)
2

Description

**Description**

C++20 coroutines are increasingly used for asynchronous APIs, but writing tests for coroutine-based code typically requires blocking adapters (e.g. `sync_wait`) or custom wrappers. This adds friction and does not work in event-loop-driven environments where blocking inside a test body is not possible.

It would therefore be useful if Catch2 supported test cases defined as coroutines, for example:

```c++
TEST_CASE_ASYNC("my async test")
{
auto result = co_await async_operation();
CHECK(result == 42);
}
```

Because Catch2 supports C++14, this feature would only be available when compiling with C++20/coroutine support. It would have to be guarded behind a build config flag.

**Additional context**

We have implemented a proof of concept in a private fork where we added a very basic coroutine task type. All scheduling and event-loop integration happen in user code, which keeps the approach flexible while adding minimal complexity inside Catch2. This was enough to solve related issues such as #1755 (we also target Emscripten).

I've looked at other C++ testing frameworks, but none currently seem to support coroutines natively. However, popular frameworks in other languages (e.g. C#, Python, JavaScript) support async tests, so the concept itself isn't novel.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing Catch2's test registration and execution flow, then examine how a C++20 coroutine task could integrate with user-provided scheduling and event loops. Done means coroutine-defined tests work behind a C++20/coroutine build flag while existing C++14 support remains unaffected.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
testing-qa
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.