| 1 |
# EFA unit tests |
| 2 |
|
| 3 |
## How to run |
| 4 |
|
| 5 |
To run efa unit tests, you will need to have cmocka installed. |
| 6 |
* [Cmocka Mirror](https://cmocka.org/files/) |
| 7 |
* [Install Instructions](https://gitlab.com/cmocka/cmocka/-/blob/master/INSTALL.md) |
| 8 |
|
| 9 |
You will need to configure libfabric with `--enable-efa-unit-test=<path_to_cmocka_install>`. |
| 10 |
|
| 11 |
An example build and run command would look like: |
| 12 |
|
| 13 |
```bash |
| 14 |
./autogen.sh && ./configure --enable-efa-unit-test=/home/ec2-user/cmocka/install && make check; |
| 15 |
``` |
| 16 |
|
| 17 |
If `make check` fails, then directly executing the test executable also works |
| 18 |
``` |
| 19 |
./prov/efa/test/efa_unit_test |
| 20 |
``` |
| 21 |
|
| 22 |
## File Structure |
| 23 |
* `efa_unit_tests.*`: They are the entry point to test runs. Declare unit tests in the header file, and add them to the `main` function. |
| 24 |
* `efa_unit_test_mocks.*`: As the name suggests, define function mocks here. |
| 25 |
* `efa_unit_test_commont.c`: This file contains utilities shared by different tests. |
| 26 |
* `efa_unit_test_{component}.c`: Implement unit tests in the corresponding file. |
| 27 |
|
| 28 |
## What Should be Tested |
| 29 |
1. We are biased toward testing public, stable functions, e.g. we prefer testing `fi_*` to `efa_*` - the former more closely resembles real user behavior. |
| 30 |
1. We make a conscious trade-off to test larger rather than smaller units. A large test unit consists of more state variables, and testing it gives us more confidence in the overall system. |
| 31 |
1. We avoid testing `static` functions that are implementation details and subject to frequent changes. More importantly, `static` function tests have to be written in the same source files and difficult to manage in a central place. |
| 32 |
1. We are biased toward testing edge cases over "happy cases", especially if the code path under test cannot be covered by integration tests. |
| 33 |
|
| 34 |
## How to write |
| 35 |
1. Decide the component under test, i.e. determine which `efa_unit_test_{component}.c` the test belongs to. |
| 36 |
1. Write the test in the above test file. |
| 37 |
1. Declare the test in `efa_unit_tests.h`. |
| 38 |
1. Create or find an existing cmocka test group in `efa_unit_tests.c`, and the test to the group. |
| 39 |
1. If you need to use `struct efa_resource`, then accept `struct efa_resource **resource` as as input to the test function. The framework will automatically create the resources before the test and destroy them after the test. |
| 40 |
|
| 41 |
## Mocking |
| 42 |
* To mock a function, you need to make sure that the function is declared in a header file, and defined in a different file from where it is called. You will need to add `-Wl,--wrap=<function to mock>` |
| 43 |
to the Makefile.include as part of efatest_LIBS. Then, after declaring the function, |
| 44 |
you can replace it with `__wrap_<function to mock>`. If you need to use the original |
| 45 |
function, you can use `__real_<function to mock>` after declaring it. |
| 46 |
* Recreate the funciton signature with `__wrap_<function>(the_params)`, and the function to the **Makefile.include** `prov_efa_test_efa_unit_test_LDFLAGS` list |
| 47 |
* Check all parameters with `check_expected()`. This allows test code to optionally check the parameters of the mocked function with the family of `expect_value()` functions. |
| 48 |
* Mock the function return value using `will_return(__wrap_xxx, mocked_val)`. Inside the mocked function, access `mocked_val` using `mock()`. This gives the test code control of the return value of the mocked function. The `will_return()` function creates a stack for each mocked function and returns the top of the stack first. |
| 49 |
* Because cmocka does mocking via linker, calls to a function will be wrapped everywhere - you might break existing tests by introducing a new mock! To avoid this, there is a trick to automatically reset the mock after each test with the help of a global variable `g_efa_unit_test_mocks` and teardown hook `efa_unit_test_mocks_teardown` - check it out. |
| 50 |
* Keep mocks in `efa_unit_test_mocks.*` |
| 51 |
* To mock a function pointer, there is no need for the linker magic. Simply implement the mocked function in `efa_unit_test_mocks.*`, and pass a pointer to the function where mocking is needed. |
| 52 |
|
| 53 |
## Manipulating Mock Behavior |
| 54 |
|
| 55 |
You can use the cmocka API to change the behavior of your mock function. |
| 56 |
|
| 57 |
The will_return class of functions will place values onto a stack that can |
| 58 |
be popped within the function with the mock function. You can use this to |
| 59 |
manipulate the function behavior. For example, if you pop the value 'true' |
| 60 |
using |
| 61 |
```c |
| 62 |
will_return(mock_function, true) |
| 63 |
``` |
| 64 |
|
| 65 |
and add a check in your mock function like so: |
| 66 |
|
| 67 |
```c |
| 68 |
int use_real_function = mock_type(bool); |
| 69 |
if (use_real_function) |
| 70 |
return __real_mock_function(params); |
| 71 |
``` |
| 72 |
|
| 73 |
you can use the real function whenever you wish to instead of your custom |
| 74 |
behavior. |
| 75 |
|
| 76 |
See: https://api.cmocka.org/group__cmocka__mock.html for more details |