1### CHRE Unit Test Framework 2 3#### Background 4 5The framework aims to provide an environment to test CHRE (and its users) code 6on-device, using [Pigweed's][PW_URL] Unit Test [Framework][PW_UT_URL]. Test 7instantiations are syntactically identical to [Googletest][GT_URL], so 8modifications to on-host unit tests to run on-device are easier. 9 10CHRE recommends running the same host-side gtests on-device using this 11framework, to catch subtle bugs. For example, the target CPU may raise an 12exception on unaligned access, when the same code would run without any 13problems on a local x86-based machine. 14 15###### Note 16 17One key difference is to run the tests via a call to `chre::runAllTests` in 18_chre/test/common/unit_test.h_, which basically wraps the gtest `RUN_ALL_TESTS` 19macro, and implements CHRE specific event handlers for Pigweed's UT Framework. 20 21#### Running Tests 22 23Under the current incarnation of the CHRE Unit Test Framework, the following 24steps need to be taken to run the on-device tests: 25* Set to true and export an environment variable called `CHRE_ON_DEVICE_TESTS_ENABLED` 26from your Makefile invocation before CHRE is built. 27 * Ensure that this flag is not always set to avoid codesize bloat. 28* Append your test source file to `COMMON_SRCS` either in _test/test.mk_ or in 29your own Makefile. 30* Call `chre::runAllTests` from somewhere in your code. 31 32##### Sample code 33 34In _math_test.cc_ 35```cpp 36#include <gtest/gtest.h> 37 38TEST(MyMath, Add) { 39 int x = 1, y = 2; 40 int result = myAdd(x, y); 41 EXPECT_EQ(result, 3); 42} 43``` 44 45In _some_source.cc_ 46```cpp 47#include "chre/test/common/unit_test.h" 48 49void utEntryFunc() { 50 chre::runAllTests(); 51} 52``` 53 54#### Caveats 55 56Some advanced features of gtest (SCOPED_TRACE, etc.) are unsupported by Pigweed. 57 58#### Compatibility 59 60The framework has been tested with Pigweed's git revision ee460238b8a7ec0a6b4f61fe7e67a12231db6d3e 61 62[PW_URL]: https://pigweed.dev 63[PW_UT_URL]: https://pigweed.googlesource.com/pigweed/pigweed/+/refs/heads/master/pw_unit_test 64[GT_URL]: https://github.com/google/googletest 65