1# Testing the CHRE Framework
2
3[TOC]
4
5The CHRE framework can be tested at various levels to ensure that
6components/modules components are working correctly and API contracts are being
7met. Below are some examples of what the team currently does to verify new
8changes.
9
10## Unit tests
11
12### Tests run on a host machine
13
14Currently, unit tests exist for various core components and utilities capable
15of running on a Linux host machine. Since
16platform-specific components likely aren’t compilable/available on a host
17machine, only components that are OS independent can be tested via this path.
18
19In order to write new tests, add a test source file under the test directory in
20the appropriate subdirectory. e.g. `util/tests`. Then, add the file to the
21`GOOGLETEST_SRCS` variable in the appropriate .mk file for that subdir,
22`util/util.mk` for example.
23
24Unit tests can be built and executed using `run_tests.sh`.
25
26
27### On-device unit tests
28
29#### Background
30
31The framework aims to provide an environment to test CHRE (and its users) code
32on-device, using [Pigweed's][PW_URL] Unit Test [Framework][PW_UT_URL]. Test
33instantiations are syntactically identical to [Googletest][GT_URL], so
34modifications to on-host unit tests to run on-device are easier.
35
36CHRE recommends running the same host-side gtests on-device using this
37framework, to catch subtle bugs. For example, the target CPU may raise an
38exception on unaligned access, when the same code would run without any
39problems on a local x86-based machine.
40
41#### Use Cases
42
43Example use cases of the framework include:
44
45* In continuous integration frameworks with device farms
46* As a superior alternative to logging and/or flag based debugging to quickly test a feature
47* As a modular set of tests to test feature or peripheral functioning (eg: a system timer implementation) during device bringup.
48
49###### Note
50
51One key difference is to run the tests via a call to `chre::runAllTests` in
52_chre/test/common/unit_test.h_, which basically wraps the gtest `RUN_ALL_TESTS`
53macro, and implements CHRE specific event handlers for Pigweed's UT Framework.
54
55#### Running Tests
56
57Under the current incarnation of the CHRE Unit Test Framework, the following
58steps need to be taken to run the on-device tests:
59* Set to true and export an environment variable called `CHRE_ON_DEVICE_TESTS_ENABLED`
60from your Makefile invocation before CHRE is built.
61  * Ensure that this flag is not always set to avoid codesize bloat.
62* Append your test source file to `COMMON_SRCS` either in _test/test.mk_ or in
63your own Makefile.
64* Call `chre::runAllTests` from somewhere in your code.
65
66##### Sample code
67
68In _math_test.cc_
69```cpp
70#include <gtest/gtest.h>
71
72TEST(MyMath, Add) {
73  int x = 1, y = 2;
74  int result = myAdd(x, y);
75  EXPECT_EQ(result, 3);
76}
77```
78
79In _some_source.cc_
80```cpp
81#include "chre/test/common/unit_test.h"
82
83void utEntryFunc() {
84  chre::runAllTests();
85}
86```
87
88#### Caveats
89
90Some advanced features of gtest (SCOPED_TRACE, etc.) are unsupported by Pigweed.
91
92#### Compatibility
93
94The framework has been tested with Pigweed's git revision ee460238b8a7ec0a6b4f61fe7e67a12231db6d3e.
95
96## PAL implementation tests
97
98PAL implementation tests verify implementations of PAL interfaces adhere to the
99requirements of that interface, and are intended primarily to support
100development of PAL implementations, typically done by a chip vendor partner.
101Additional setup may be required to integrate with the PAL under test and supply
102necessary dependencies. The source code is in the files under `pal/tests/src`
103and follows the naming scheme `*_pal_impl_test.cc`.
104
105In order to run PAL tests, run: `run_pal_impl_tests.sh`. Note that there are
106also PAL unit tests in the same directory. The unit tests are added to the
107`GOOGLETEST_SRCS` target while PAL tests are added to the
108`GOOGLETEST_PAL_IMPL_SRCS` target.
109
110## FeatureWorld nanoapps
111
112Located under the `apps/` directory, FeatureWorld nanoapps interact with the set
113of CHRE APIs that they are named after, and can be useful during framework
114development for manual verification of a feature area. For example, SensorWorld
115attempts to samples from sensors and outputs to the log. It also offers a
116break-it mode that randomly changes which sensors are being sampled in an
117attempt to point out stress points in the framework or platform implementation.
118
119These apps are usually built into the CHRE framework binary as static nanoapps
120to facilitate easy development. See the Deploying Nanoapps section for more
121information on static nanoapps.
122
123## CHQTS
124
125The Context Hub Qualification Test Suite (CHQTS) tests perform end-to-end
126validation of a CHRE implementation, by using the Java APIs in Android to load
127and interact with test nanoapps which then exercise the CHRE API. While this
128code is nominally integrated in another test suite, the source code is available
129under `java/test/chqts/` for the Java side code and `apps/test/chqts/` for the
130CHQTS-only nanoapp code and `apps/test/common/` for the nanoapp code shared by
131CHQTS and other test suites.
132
133[PW_URL]: https://pigweed.dev
134[PW_UT_URL]: https://pigweed.googlesource.com/pigweed/pigweed/+/refs/heads/master/pw_unit_test
135[GT_URL]: https://github.com/google/googletest
136