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