Project: userver (App Definition and Development / Streaming & Messaging)
File: testing.md

All userver test helpers live in `userver-utest` CMake target: ```cmake targetlinklibraries(your-test-target PRIVATE userver-utest) ``` To include gtest and userver-specific macros, do: ```cpp ``` The header provides alternative gtest-like macros that run tests in a coroutine environment: UTEST(testsuitename, test_name) UTESTMT(testsuitename, testname, thread_count) UTESTF(testsuitename, testname) UTESTFMT(testsuitename, testname, threadcount) UTESTP(testsuitename, testname) UTESTPMT(testsuitename, testname, threadcount) UTESTDEATH(testsuitename, testname) TYPEDUTEST(testsuitename, testname) TYPEDUTESTMT(testsuitename, testname, threadcount) TYPEDUTESTP(testsuitename, test_name) TYPEDUTESTPMT(testsuitename, testname, thread_count) TYPEDUTESTSUITE(testsuitename, types) #INSTANTIATEUTESTSUITEP(prefix, testsuite_name, ...) #REGISTERTYPEDUTESTSUITEP(testsuitename, ...) INSTANTIATETYPEDUTESTSUITEP(prefix, testsuitename, types) TYPEDUTESTSUITEP(testsuite_name) As usual, gmock is available in `<gmock/gmock.h>`. See also utest::PrintTestName for info on how to simplify writing parametrized tests and . To test code that uses coroutine environment (e.g. creates tasks or uses @ref scripts/docs/en/userver/synchronization.md "synchronization primitives"), use `UTEST` instead of `TEST` in the test header: @snippet core/src/engine/semaphore_test.cpp UTEST macro example 1 There are `U`-versions for all gtest macros that declare tests and test groups: `UTESTF`, `UTESTP`, `INSTANTIATEUTESTSUITE_P` etc. Test fixture's constructor, destructor, `SetUp` and `TearDown` are executed in the same coroutine environment as the test body. By default, a single-threaded `TaskProcessor` is used. It is usually enough, because userver engine enables concurrency even on 1 thread. However, some tests require actual parallelism, e.g. torture tests that search for potential data races. In such cases, use `_MT` macro versions: @snippet core/src/engine/semaphore_test.cpp UTEST macro example 2 The specified thread count is available in `U`-tests as `GetThreadCount()` method. For DEATH-tests (when testing aborts or assertion fails) use `UTEST_DEATH`. It configures gtest-DEATH-checks to work in multithreaded environment. Also it disables using of `evdefaultloop` and catching of `SIGCHLD` signal to work with gtest's `waitpid()` calls. Standard gtest exception assertions provide poor error messages. Their equivalents with proper diagnostics are available in `<userver/utest/utest.hpp>`: #UEXPECTTHROWMSG(statement, exceptiontype, messagesubstring) #UASSERTTHROWMSG(statement, exceptiontype, messagesubstring) #UEXPECTTHROW(statement, exceptiontype) #UASSERTTHROW(statement, exceptiontype) #UEXPECTNOTHROW(statement) #UASSERTNOTHROW(statement) Example usage: @snippet universal/src/utest/assertmacrostest.cpp Sample assert macros usage @anchor utest-mocked-time To mock time, use `utils::datetime::Now()` and `utils::datetime::SteadyNow()` from `<userver/utils/datetime.hpp>` instead of `std::chrono::systemclock::now()` and `std::chrono::steadyclock::now()`, respectively. Control the mocked time in tests using `<userver/utils/mock_now.hpp>` @snippet universal/src/utils/mocknowtest.cpp Mocked time sample @anchor utest-dynamic-config You can fill dynamic config with custom config values using `dynamic_config::StorageMock`. @snippet core/src/dynamicconfig/configtest.cpp Sample StorageMock usage If you don't want to specify all configs used by the tested code, you can use default dynamic config. To use default dynamic config values in tests, add `DEFAULTDYNAMICCONFIG_FILENAME` preprocessor definition to your test CMake target, specifying the path of a YAML file with `dynamic_config::DocsMap` contents. Default dynamic config values can be accessed using `<dynamicconfig/testhelpers.hpp>`: `dynamic_config::GetDefaultSnapshot()` `dynamic_config::GetDefaultSource()` `dynamic_config::MakeDefaultStorage(overrides)` @snippet core/src/dynamicconfig/configtest.cpp Sample StorageMock defaults All userver benchmark helpers live in `userver-ubench` CMake target: ```cmake targetlinklibraries(your-bench-target PRIVATE userver-ubench) ``` As usual, google-benchmark is available in `<benchmark/benchmark.h>`. See also official google-benchmark . Use `engine::RunStandalone` to run parts of your benchmark in a coroutine environment: @snippet core/src/engine/semaphore_benchmark.cpp RunStandalone sample See the . Default dynamic configs are available in in `<userver/dynamicconfig/testhelpers.hpp>`. @htmlonly <div class="bottom-nav"> @endhtmlonly @ref scripts/docs/en/userver/periodics.md | @ref scripts/docs/en/userver/functional_testing.md @htmlonly </div> @endhtmlonly