1.. _showcase-sense-tutorial-hosttests: 2 3================= 45. Run host tests 5================= 6.. _GoogleTest: https://google.github.io/googletest/ 7 8:ref:`module-pw_unit_test` provides an extensive `GoogleTest`_-compatible 9unit testing framework. Before building and running the app, let's first 10verify that the app's logic is correct by exercising the app's unit 11tests: 12 13#. Open ``//modules/blinky/blinky_test.cc``. 14 15 Remember that ``//`` represents the root directory of your Sense repository. 16 E.g. if your Sense repo was located at ``/home/example/sense/`` then 17 ``//modules/blinky/blinky_test.cc`` would be located at 18 ``/home/examples/sense/modules/blinky/blinky_test.cc``. 19 20#. Make the ``Toggle`` test fail by changing one of the expected values. 21 Example: 22 23 .. code-block:: c++ 24 25 TEST_F(BlinkyTest, Toggle) { 26 // ... 27 auto event = FirstActive(); 28 ASSERT_NE(event, monochrome_led_.events().end()); 29 EXPECT_EQ(event->state, State::kInactive); // add this line 30 // EXPECT_EQ(event->state, State::kActive); // comment out this line 31 EXPECT_GE(ToMs(event->timestamp - start), kIntervalMs * 0); 32 start = event->timestamp; 33 // ... 34 } 35 36 .. caution:: Remember to save your changes! 37 38#. Run the tests: 39 40 .. tab-set:: 41 42 .. tab-item:: VS Code 43 :sync: vsc 44 45 Make sure that your platform is set to **host_simulator**, as demonstrated 46 in :ref:`showcase-sense-tutorial-intel-nav`. If VS Code was displaying 47 red squiggly line warnings in ``blinky_test.cc``, those should go away. 48 49 In **Bazel Targets** expand **//modules/blinky**, then right-click 50 **:blinky_test (cc_test)**, then select **Test target**. 51 52 .. figure:: https://storage.googleapis.com/pigweed-media/sense/20240802/test_target_v2.png 53 :alt: Selecting Test target 54 55 Starting ``blinky_test`` 56 57 A task launches a terminal. You should see ``blinky_test`` fail: 58 59 .. code-block:: console 60 :emphasize-lines: 16 61 62 INF LED blinking: ON 63 INF [*] 64 INF [ ] 65 INF Stopped blinking 66 [ OK ] BlinkyTest.BlinkSlow 67 [==========] Done running all tests. 68 [ PASSED ] 3 test(s). 69 [ FAILED ] 1 test(s). 70 ================================================================================ 71 INFO: Found 1 test target... 72 Target //modules/blinky:blinky_test up-to-date: 73 bazel-bin/modules/blinky/blinky_test 74 INFO: Elapsed time: 2.060s, Critical Path: 1.75s 75 INFO: 27 processes: 15 internal, 12 linux-sandbox. 76 INFO: Build completed, 1 test FAILED, 27 total actions 77 //modules/blinky:blinky_test FAILED in 0.0s 78 /home/kayce/.cache/bazel/_bazel_kayce/e6adb4cdc44e1f72d34a105431e60eae/execroot/_main/bazel-out/k8-fastbuild/testlogs/modules/blinky/blinky_test/test.log 79 80 Executed 1 out of 1 test: 1 fails locally. 81 82 Press any key to close the terminal that was launched. 83 84 .. tip:: 85 86 When you want to run all unit tests, open a VS Code Terminal 87 and execute ``bazelisk test //...``. You don't need to manually 88 set up ``bazelisk``, the Pigweed extension for VS Code sets it 89 up for you. 90 91 .. tab-item:: CLI 92 :sync: cli 93 94 #. Run the tests with the following command: 95 96 Run the following command. You should see output similar to what's 97 shown after the command. The key line is 98 ``Executed 1 out of 1 test: 1 fails locally.`` 99 100 .. code-block:: console 101 102 bazelisk test //modules/blinky:blinky_test 103 104 You should see output similar to this: 105 106 .. code-block:: text 107 108 INF LED blinking: ON 109 INF [*] 110 INF LED blinking: OFF 111 INF [ ] 112 INF LED blinking: ON 113 INF [*] 114 INF [ ] 115 INF Stopped blinking 116 [ OK ] BlinkyTest.BlinkMany 117 [ RUN ] BlinkyTest.BlinkSlow 118 INF [ ] 119 INF PWM: - 120 INF [ ] 121 INF [ ] 122 INF PWM: + 123 INF PWM: + 124 INF PWM: + 125 INF Blinking 1 times at a 320ms interval 126 INF LED blinking: OFF 127 INF [ ] 128 INF LED blinking: ON 129 INF [*] 130 INF [ ] 131 INF Stopped blinking 132 [ OK ] BlinkyTest.BlinkSlow 133 [==========] Done running all tests. 134 [ PASSED ] 3 test(s). 135 [ FAILED ] 1 test(s). 136 ================================================================================ 137 INFO: Found 1 test target... 138 Target //modules/blinky:blinky_test up-to-date: 139 bazel-bin/modules/blinky/blinky_test 140 INFO: Elapsed time: 2.032s, Critical Path: 1.69s 141 INFO: 9 processes: 1 internal, 8 linux-sandbox. 142 INFO: Build completed, 1 test FAILED, 9 total actions 143 //modules/blinky:blinky_test FAILED in 0.0s 144 /home/kayce/.cache/bazel/_bazel_kayce/e6adb4cdc44e1f72d34a105431e60eae/execroot/_main/bazel-out/k8-fastbuild/testlogs/modules/blinky/blinky_test/test.log 145 146 Executed 1 out of 1 test: 1 fails locally. 147 148 .. tip:: 149 150 To run all host tests, run this command: 151 152 .. code-block:: console 153 154 bazelisk test //... 155 156#. Revert the test to its original state. Remember to save your change. 157 158#. Run the tests again and make sure they pass this time. 159 160 You should see ``blinky_test`` pass this second time: 161 162 .. code-block:: console 163 :emphasize-lines: 8 164 165 INFO: Analyzed target //modules/blinky:blinky_test (0 packages loaded, 0 targets configured). 166 INFO: Found 1 test target... 167 Target //modules/blinky:blinky_test up-to-date: 168 bazel-bin/modules/blinky/blinky_test 169 INFO: Elapsed time: 1.861s, Critical Path: 1.65s 170 INFO: 4 processes: 4 linux-sandbox. 171 INFO: Build completed successfully, 4 total actions 172 //modules/blinky:blinky_test PASSED in 0.0s 173 174 Executed 1 out of 1 test: 1 test passes. 175 176.. note:: 177 178 If you see warnings that begin with ``There were tests whose 179 specified size is too big``, you can ignore them. If you encounter this warning 180 in your own project, it means you need to adjust the timeout of the tests. 181 182.. _showcase-sense-tutorial-hosttests-summary: 183 184------- 185Summary 186------- 187We know that unit tests are a little boring, but they're an 188important part of Pigweed's :ref:`mission <docs-mission>`. 189When you're on a large embedded development team creating a new product, it's 190much easier to iterate quickly when you have confidence that your code 191changes do not introduce bugs in other parts of the codebase. The best way 192to build that confidence is to rigorously test every part of your codebase 193and to make sure all these tests pass before allowing any new code to merge. 194 195Pigweed spends a lot of time making it easier for teams to test their 196codebases, such as making it easy to run unit tests on your development 197host rather than on physical hardware. This is especially useful when 198your physical hardware doesn't exist yet because your hardware team 199hasn't finished designing it! 200 201.. _ASAN: https://clang.llvm.org/docs/AddressSanitizer.html 202.. _TSAN: https://clang.llvm.org/docs/ThreadSanitizer.html 203.. _MSAN: https://clang.llvm.org/docs/MemorySanitizer.html 204 205Another reason why it's important to make code that can be tested on your host: 206security and robustness. This enables you to run modern code analysis 207tooling like `ASAN`_, `TSAN`_, `MSAN`_, :ref:`fuzzers <module-pw_fuzzer>`, and 208more. These tools are unlikely to run correctly in on-device embedded contexts. 209Fun fact: We caught real bugs in Sense with this tooling during 210development! 211 212Now it's time for the fun stuff. Head over to 213:ref:`showcase-sense-tutorial-sim` to try out the bringup 214app, ``blinky``. 215
