The testing guide is now updated to include details about
using sub-testsuites. Some example code is given to demonstrate how
they can be used.
A note is also added to highlight the need for using vdev EAL args when
running cryptodev tests.
Signed-off-by: Ciara Power <ciara.po...@intel.com>
---
Depends-on: patch-101811 ("guides: add a guide for developing unit tests")
v3:
- Rebased on v5 of testing doc patch.
- Moved "Depends-on" tag to notes section of commit.
v2:
- Updated to depend on v4 of testing doc patch.
- Added examples for running with cryptodev vdev args.
- Small formatting fixes.
---
doc/guides/contributing/unit_test.rst | 93 ++++++++++++++++++++++++++-
1 file changed, 91 insertions(+), 2 deletions(-)
diff --git a/doc/guides/contributing/unit_test.rst
b/doc/guides/contributing/unit_test.rst
index b207b5aade..4be4acceab 100644
--- a/doc/guides/contributing/unit_test.rst
+++ b/doc/guides/contributing/unit_test.rst
@@ -185,13 +185,21 @@ for interacting with the test harness:
2. unit_test_suite_runner(struct unit_test_suite \*)
Returns a runner for a full test suite object, which contains
- a test suite name, setup, tear down, and vector of unit test
- cases.
+ a test suite name, setup, tear down, a pointer to a list of
+ sub-testsuites, and vector of unit test cases.
Each test suite has a setup and tear down function that runs at the
beginning and end of the test suite execution. Each unit test has
a similar function for test case setup and tear down.
+Each testsuite may use a nested list of sub-testsuites,
+which are iterated by the unit_test_suite_runner.
+This support allows for better granularity when designing test suites.
+The sub-testsuites list can also be used in parallel with the vector
+of testcases, in this case the testcases will be run,
+and then each sub-testsuite is executed. To see an example of a
+testsuite using sub-testsuites, see *app/test/test_cryptodev.c*.
+
Test cases are added to the `.unit_test_cases` element of the appropriate
unit test suite structure. An example of both a test suite and a case:
@@ -236,6 +244,70 @@ unit test suite structure. An example of both a test
suite and a case:
The above code block is a small example that can be used to create a
complete test suite with test case.
+Sub-testsuites can be added to the `.unit_test_suites` element of
+the unit test suite structure, for example:
+
+.. code-block:: c
+ :linenos:
+
+ static int testsuite_setup(void) { return TEST_SUCCESS; }
+ static void testsuite_teardown(void) { }
+
+ static int ut_setup(void) { return TEST_SUCCESS; }
+ static void ut_teardown(void) { }
+
+ static int test_case_first(void) { return TEST_SUCCESS; }
+
+ static struct unit_test_suite example_parent_testsuite = {
+ .suite_name = "EXAMPLE PARENT TEST SUITE",
+ .setup = testsuite_setup,
+ .teardown = testsuite_teardown,
+ .unit_test_cases = {TEST_CASES_END()}
+ };
+
+ static int sub_testsuite_setup(void) { return TEST_SUCCESS; }
+ static void sub_testsuite_teardown(void) { }
+
+ static struct unit_test_suite example_sub_testsuite = {
+ .suite_name = "EXAMPLE SUB TEST SUITE",
+ .setup = sub_testsuite_setup,
+ .teardown = sub_testsuite_teardown,
+ .unit_test_cases = {
+ TEST_CASE_ST(ut_setup, ut_teardown, test_case_first),
+
+ TEST_CASES_END(), /**< NULL terminate unit test array */
+ },
+ };
+
+ static struct unit_test_suite end_testsuite = {
+ .suite_name = NULL,
+ .setup = NULL,
+ .teardown = NULL,
+ .unit_test_suites = NULL
+ };
+
+ static int example_tests()
+ {
+ uint8_t ret, i = 0;
+ struct unit_test_suite *sub_suites[] = {
+ &example_sub_testsuite,
+ &end_testsuite /**< NULL test suite to indicate end of list */
+ };
+
+ example_parent_testsuite.unit_test_suites =
+ malloc(sizeof(struct unit_test_suite *) * RTE_DIM(sub_suites));
+
+ for (i = 0; i < RTE_DIM(sub_suites); i++)
+ example_parent_testsuite.unit_test_suites[i] = sub_suites[i];
+
+ ret = unit_test_suite_runner(&example_parent_testsuite);
+ free(example_parent_testsuite.unit_test_suites);
+
+ return ret;
+ }
+
+ REGISTER_TEST_COMMAND(example_autotest, example_tests);
+
Designing a test
----------------
@@ -325,3 +397,20 @@ In general, when a test is added to the `dpdk-test`
application, it
probably should be added to a meson test suite, but the choice is
left to maintainers and individual developers. Preference is to add
tests to the meson test suites.
+
+
+Running Cryptodev Tests
+-----------------------
+
+When running cryptodev tests, the user must create any required virtual
+device via EAL args, as this is not automatically done by the test::
+
+ $ ./build/app/test/dpdk-test --vdev crypto_aesni_mb
+ $ meson test -C build --suite driver-tests \
+ --test-args="--vdev crypto_aesni_mb"
+
+.. note::
+
+ The cryptodev_scheduler_autotest is the only exception to this.
+ This vdev will be created automatically by the test app,
+ as it requires a more complex setup than other vdevs.
--
2.25.1
