浏览代码

doxygen: update naming rule for utest-case

More details see PR #10681.

As utest cases are currently moving out of `examples/utest/testcases`
into their own module directories, the naming rule needs to change
accordingly.

Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
Chen Wang 3 天之前
父节点
当前提交
e2224f525b
共有 1 个文件被更改,包括 31 次插入4 次删除
  1. 31 4
      documentation/6.components/utest/utest.md

+ 31 - 4
documentation/6.components/utest/utest.md

@@ -62,18 +62,45 @@ UTEST_TC_EXPORT(testcase, name, init, cleanup, timeout)
 | Parameters | Description |
 | :-----   | :------ |
 | testcase | Test case main-bearing function (**specifies** using a function called *static void testcase(void)* |
-| name     | Test case name (uniqueness). Specifies the naming format for connecting relative names of test cases relative to `testcases directory` with `.` |
+| name     | Test case name (uniqueness). Detailed requirements see below **Test case naming requirements:** |
 | init     | the initialization function before Test case startup |
 | cleanup  | Cleanup function after the end of the test case |
 | timeout  | Test case expected test time (in seconds) |
 
 **Test case naming requirements:**
 
-Test cases need to be named in the prescribed format. Specifies the naming format for the connection of the current test case relative to the `testcases directory ` linked with  `.` . The name contains the file name of the current test case file (the file name except the suffix name).
+To ensure unique unit-testcase names throughout the RT-Thread source code repository, the full name consists of two parts:
+
+**Module-Prefix.Test-Function**
+
+- **Module-Prefix**: Use the path of the *module's utest directory* relative to the source code repository root (excluding utest), connected by a dot ("."). For more information on *module's utest directory*, see section **How-to add utest cases into RT-Thread for your module**.
+
+- **Test-Function**: Define your own name, ensuring it's unique within the same **Module-Prefix** (it doesn't have to match the test case file name).
 
 **Test case naming example:**
 
-Assuming that there is a `testcases\components\filesystem\dfs\dfs_api_tc.c` test case file in the test case `testcases` directory, the test case name in the `dfs_api_tc.c` is named `components.filesystem.dfs.dfs_api_tc`.
+Assuming that there is a *module's utest directory*: `components/dfs/utest`, which contains utest source files for module "DFS". We can define the testcase in file `components/dfs/utest/tc_dfs_api.c` as below:
+
+```c
+static void testcase(void)
+{
+    /* Skip filesystem mount test for now due to mutex issues */
+    UTEST_UNIT_RUN(test_mkfs);
+    // ......
+}
+
+UTEST_TC_EXPORT(testcase, "components.dfs.fs_dfs_api_tc", utest_tc_init, utest_tc_cleanup, 10);
+```
+
+Here, the global unique unit-testcase name is "components.dfs.fs_dfs_api_tc". Of this name, **Module-Prefix** is "components.dfs", which corresponds to the path name `components/dfs`; **Test-Function** is `fs_dfs_api_tc`, which uniquely identifies a suite of cases which will be run in the function `testcase()`, and note that the `fs_dfs_api_tc` need not be the same as the file name of `tc_dfs_api.c`.
+
+Particularly, for modules in the `src` directory, since the name `src` is ambiguous, it is recommended to replace it with `core` to contrast it with `components`. This indicates that the code in `src` is the kernel's *core* code module relative to `components`.
+
+For example: The utest case in `src/klibc/utest/TC_rt_memcmp.c` can be written as:
+
+```c
+UTEST_TC_EXPORT(utest_do_tc, "core.klibc.rt_memcmp", RT_NULL, RT_NULL, 1000);
+```
 
 ## Test Case LOG Output Interface
 
@@ -273,7 +300,7 @@ From the above flow chart you can get the following:
 - A test case implementation can only export a test body function (testcase function) using `UTEST_TC_EXPORT`
 - Write a `README.md` document for the your test case to guide the user through configuring the test environment.
 
-# How-to add utest cases into RT-Thread for your module.
+# How-to add utest cases into RT-Thread for your module
 
 The source code of utest cases is recommended to be placed in each module for maintenance, but the entry of Kconfig should all be placed(rsourced) in `Kconfig.utestcases` for unified maintenance. In this way, when executing menuconfig, people can enter and configure from one place, avoiding searching for utest configuration switches scattering in the menuconfig interface.