mirror of
https://github.com/RT-Thread/rt-thread.git
synced 2026-05-22 10:31:47 +08:00
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>
This commit is contained in:
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user