Debian Codegraph @

prov/efa/test/README.md

raw
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