Armando Montanez | 0054a9b | 2020-03-13 13:06:24 -0700 | [diff] [blame] | 1 | .. _chapter-pw-unit-test: |
Alexei Frolov | ea39552 | 2020-03-13 13:35:07 -0700 | [diff] [blame] | 2 | .. default-domain:: cpp |
| 3 | |
| 4 | .. highlight:: sh |
| 5 | |
Alexei Frolov | ea39552 | 2020-03-13 13:35:07 -0700 | [diff] [blame] | 6 | ------------ |
| 7 | pw_unit_test |
| 8 | ------------ |
| 9 | ``pw_unit_test`` unit testing library with a `Google Test`_-compatible API, |
| 10 | built on top of embedded-friendly primitives. |
| 11 | |
| 12 | ``pw_unit_test`` is a portable library which can run on almost any system from |
| 13 | from bare metal to a full-fledged desktop OS. It does this by offloading the |
| 14 | responsibility of test reporting and output to the underlying system, |
| 15 | communicating its results through a common interface. Unit tests can be written |
| 16 | once and run under many different environments, empowering developers to write |
| 17 | robust, high quality code. |
| 18 | |
| 19 | ``pw_unit_test`` is still under development and lacks many features expected in |
| 20 | a complete testing framework; nevertheless, it is already used heavily within |
| 21 | Pigweed. |
| 22 | |
| 23 | .. note:: |
| 24 | |
| 25 | This documentation is currently incomplete. |
| 26 | |
| 27 | Writing unit tests |
| 28 | ================== |
| 29 | |
| 30 | ``pw_unit_test``'s interface is largely compatible with `Google Test`_. Refer to |
| 31 | the Google Test documentation for examples of to define unit test cases. |
| 32 | |
| 33 | .. note:: |
| 34 | |
| 35 | A lot of Google Test's more advanced features are not yet implemented. To |
| 36 | request a feature addition, please |
Armando Montanez | 3d92e81 | 2020-03-19 12:13:36 -0700 | [diff] [blame] | 37 | `let us know <mailto:pigweed@googlegroups.com>`_. |
Alexei Frolov | ea39552 | 2020-03-13 13:35:07 -0700 | [diff] [blame] | 38 | |
| 39 | Using the test framework |
| 40 | ======================== |
| 41 | |
| 42 | The EventHandler interface |
| 43 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 44 | The ``EventHandler`` class in ``public/pw_unit_test/event_handler.h`` defines |
| 45 | the interface through which ``pw_unit_test`` communicates the results of its |
| 46 | test runs. A platform using ``pw_unit_test`` must register an event handler with |
| 47 | the unit testing framework to receive test output. |
| 48 | |
| 49 | As the framework runs tests, it calls the event handler's callback functions to |
| 50 | notify the system of various test events. The system can then choose to perform |
| 51 | any necessary handling or aggregation of these events, and report them back to |
| 52 | the developer. |
| 53 | |
| 54 | Predefined event handlers |
| 55 | ------------------------- |
| 56 | Pigweed provides some standard event handlers upstream to simplify the process |
| 57 | of getting started using ``pw_unit_test``. |
| 58 | |
| 59 | * ``SimplePrintingEventHandler``: An event handler that writes Google Test-style |
| 60 | output to a specified sink. |
| 61 | |
| 62 | .. code:: |
| 63 | |
| 64 | [==========] Running all tests. |
| 65 | [ RUN ] Status.Default |
| 66 | [ OK ] Status.Default |
| 67 | [ RUN ] Status.ConstructWithStatusCode |
| 68 | [ OK ] Status.ConstructWithStatusCode |
| 69 | [ RUN ] Status.AssignFromStatusCode |
| 70 | [ OK ] Status.AssignFromStatusCode |
| 71 | [ RUN ] Status.CompareToStatusCode |
| 72 | [ OK ] Status.CompareToStatusCode |
| 73 | [ RUN ] Status.Ok_OkIsTrue |
| 74 | [ OK ] Status.Ok_OkIsTrue |
| 75 | [ RUN ] Status.NotOk_OkIsFalse |
| 76 | [ OK ] Status.NotOk_OkIsFalse |
| 77 | [ RUN ] Status.KnownString |
| 78 | [ OK ] Status.KnownString |
| 79 | [ RUN ] Status.UnknownString |
| 80 | [ OK ] Status.UnknownString |
| 81 | [==========] Done running all tests. |
| 82 | [ PASSED ] 8 test(s). |
| 83 | |
| 84 | |
| 85 | * ``LoggingEventHandler``: An event handler which uses the ``pw_log`` module to |
| 86 | output test results, to integrate with the system's existing logging setup. |
| 87 | |
| 88 | .. _running-tests: |
| 89 | |
| 90 | Running tests |
| 91 | ^^^^^^^^^^^^^ |
| 92 | To run unit tests, link the tests into a single binary with the unit testing |
| 93 | framework, register an event handler, and call the ``RUN_ALL_TESTS`` macro. |
| 94 | |
| 95 | .. code:: cpp |
| 96 | |
| 97 | #include "pw_unit_test/framework.h" |
| 98 | #include "pw_unit_test/simple_printing_event_handler.h" |
| 99 | |
| 100 | void WriteString(const std::string_view& string, bool newline) { |
| 101 | printf("%s", string.data()); |
| 102 | if (newline) { |
| 103 | printf("\n"); |
| 104 | } |
| 105 | } |
| 106 | |
| 107 | int main() { |
| 108 | pw::unit_test::SimplePrintingEventHandler handler(WriteString); |
| 109 | pw::unit_test::RegisterEventHandler(&handler); |
| 110 | return RUN_ALL_TESTS(); |
| 111 | } |
| 112 | |
| 113 | Build system integration |
| 114 | ^^^^^^^^^^^^^^^^^^^^^^^^ |
| 115 | ``pw_unit_test`` integrates directly into Pigweed's GN build system. To define |
| 116 | simple unit tests, set the ``pw_unit_test_main`` build variable to a target |
| 117 | which configures the test framework as described in the :ref:`running-tests` |
| 118 | section, and use the ``pw_test`` template to register your test code. |
| 119 | |
| 120 | .. code:: |
| 121 | |
| 122 | import("$dir_pw_unit_test/test.gni") |
| 123 | |
| 124 | pw_test("foo_test") { |
| 125 | sources = [ "foo_test.cc" ] |
| 126 | } |
| 127 | |
Armando Montanez | 0054a9b | 2020-03-13 13:06:24 -0700 | [diff] [blame] | 128 | ``pw_unit_test`` module provides a few optional libraries to simplify setup: |
| 129 | |
| 130 | - ``simple_printing_event_handler```: When running tests, output test results |
| 131 | as plain text over ``pw_sys_io``. |
| 132 | - ``simple_printing_main``: Implements a ``main()`` function that simply runs |
| 133 | tests using the ``simple_printing_event_handler``. |
| 134 | - ``logging_event_handler``: When running tests, log test results as |
| 135 | plain text using pw_log (ensure your target has set a ``pw_log`` backend). |
| 136 | - ``logging_main``: Implements a ``main()`` function that simply runs tests |
| 137 | using the ``logging_event_handler``. |
| 138 | |
| 139 | |
Alexei Frolov | ea39552 | 2020-03-13 13:35:07 -0700 | [diff] [blame] | 140 | .. _Google Test: https://github.com/google/googletest/blob/master/googletest/docs/primer.md |