doc: add document for testing with seastar

since Boost.Test does not provide builtin support for testing
test cases implemented with coroutine. we have our own test runner
and macros for declaring tests. for new developers these macros
and the macros like `BOOST_AUTO_TEST_CASE` could be confusing.

this document intend to clarify the declaration and organization
of tests in Seastar and Seastar applications using Seastar's testing
framework.

Signed-off-by: Kefu Chai <[email protected]>

Closes scylladb#2407

doc/testing.md

@@ -0,0 +1,51 @@
+# 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](https://www.boost.org/doc/libs/release/libs/test/doc/html/boost_test/utf_reference/test_org_reference.html).
+* [Coroutine](https://github.com/scylladb/seastar/blob/master/doc/tutorial.md#coroutines): Tests defined using `SEASTAR_TEST_CASE`. The test body returns a future, allowing implementation as a coroutine.
+* Coroutine with [`seastar::thread`](https://github.com/scylladb/seastar/blob/master/doc/tutorial.md#seastarthread): 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`](https://www.boost.org/doc/libs/release/libs/test/doc/html/boost_test/utf_reference/link_references/link_boost_test_module_macro.html) 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:
+
+```cmake
+seastar_add_test(meow_test
+  KIND SEASTAR
+  SOURCES meow.cc)
+```
+
+or simply:
+
+```cmake
+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:
+
+```cmake
+seastar_add_test(woof_test
+  KIND BOOST
+  SOURCE woof.cc)
+```
+