agent-enviroments/builder/libs/seastar/doc/testing.md

Testing

Seastar leverages Boost.Test and provides facilities for developers to implement tests in coroutines.

Test Declarations

There are three categories of boost-based tests in our system:

• Boost.Test Native: Tests defined using BOOST_AUTO_TEST_CASE and related macros from Boost.Test. For more information, see the Boost Test documentation.
• Coroutine: Tests defined using SEASTAR_TEST_CASE. The test body returns a future, allowing implementation as a coroutine.
• Coroutine with seastar::thread: Tests defined using SEASTAR_THREAD_TEST_CASE. The test body is launched in a Seastar thread, allowing the use of Seastar coroutines. These tests should return void.

Choosing the Appropriate Macro

• Use SEASTAR_TEST_CASE or SEASTAR_THREAD_TEST_CASE if you need to run tests in a Seastar reactor thread, typically for Seastar coroutines. SEASTAR_THREAD_TEST_CASE can be more convenient in some cases.
• For Seastar facilities that don't depend on coroutines, consider using BOOST_AUTO_TEST_CASE.

Tests' organization

• Tests defined with BOOST_AUTO_TEST_CASE are driven by Boost.Test's built-in test runner. They require defining BOOST_TEST_MODULE to include the runner in the executable. These tests support additional features like fixtures and data-driven testing.
• SEASTAR_TEST_CASE and SEASTAR_THREAD_TEST_CASE tests only support decorators and share a common test runner, allowing them to be co-located in the same test suite.
• Seastar tests cannot be co-located with "native" Boost tests.

Adding Tests in CMakeLists.txt

For Seastar tests:

seastar_add_test(meow_test
  KIND SEASTAR
  SOURCES meow.cc)

or simply:

seastar_add_test(meow_test
  SOURCES meow.cc)

The KIND parameter of seastar_add_test() function defaults to SEASTAR, using the Seastar test runner by defining the SEASTAR_TESTING_MAIN macro.

For "native" Boost tests:

seastar_add_test(woof_test
  KIND BOOST
  SOURCE woof.cc)