mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
188c21319d
This commit adds a README.md containing guidelines on how to refactor the FreeRTOS unit tests for upstreaming. A portTestMacro.h header was also added which contains port implementation specific macros used by the test cases.
74 lines
3.6 KiB
Markdown
74 lines
3.6 KiB
Markdown
# FreeRTOS Tests Guidelines
|
|
|
|
The FreeRTOS tests are currently being refactored/reorganized with the goal of being upstreamed. This document describes the set of guidelines to which the tests are refactored/reorganized according to.
|
|
|
|
## Unity Port
|
|
|
|
These test cases assume that the FreeRTOS port has also ported the [Unity Test Framework](https://github.com/ThrowTheSwitch/Unity). Because each FreeRTOS test case will require the scheduler to be started, the way that each test case is invoked will differ form regular Unity ports.
|
|
|
|
Regular Unity ports will assume that the `main()` function invokes each test using the `RUN_TEST()` macro. However, these test cases assume the following about the Unity port:
|
|
|
|
- Each test case is invoked from a `UnityTask` instead of `main()`. Thus each test case is run from the context of the `UnityTask`.
|
|
- The `UnityTask` is created using `xTaskCreate...()` (and pinned to core 0 if SMP) from the port's startup (i.e., `main()`)
|
|
- The port's startup (i.e., `main()`) should also start the scheduler using `vTaskStartScheduler()`
|
|
- Note that this is similar to the startup of most FreeRTOS Demos.
|
|
- Each test case is defined using the `TEST_CASE(name, ...)` macro. The `VA_ARGS` of the macro allows each port to specify a set of extra arguments (such as test case labels/tags) to be used into their CI pipelines.
|
|
- A `portTestMacro.h` must be provided by each port. This header will contain
|
|
- Some constants used by test cases such as default task stack sizes (e.g., `configTEST_DEFAULT_STACK_SIZE`)
|
|
- Some port implementation specific functions/macros required by test cases such as getting current system time (e.g., `portTEST_GET_TIME()`).
|
|
|
|
## Test Organization
|
|
|
|
- Test cases are grouped into sub-directories roughly matching the header files of FreeRTOS (e.g., task, queue, semaphore, event groups etc).
|
|
- Each source file should ideally test a particular behavior (e.g., priority scheduling, queue send, scheduler suspend). This should usually result in one test case per behavior, thus one test case per source file
|
|
- Some test case behaviors may depend on configuration (e.g., priority scheduling in single core vs SMP). In such cases
|
|
- If the affect is small, use an `#if (config... == 1)` to wrap the affected areas
|
|
- If the affect is large, write a separate test case in a separate source file and wrap the entire test case with `#if (config... == 1)`.
|
|
|
|
## Test Case Template
|
|
|
|
Each test case should have the following:
|
|
|
|
- Test case description describing
|
|
- Purpose of the test case
|
|
- Test case procedure
|
|
- Excepted outcome/behavior of the test case
|
|
- The test case code wrapped in its required `config...` macros
|
|
- The expected outcomes should be tested using the `TEST_ASSERT_...()` macros provided by unity
|
|
|
|
```c
|
|
// In test_priority_scheduling.c
|
|
|
|
/*
|
|
Test Priority Scheduling (Single Core)
|
|
|
|
Purpose:
|
|
- Test that the single-core scheduler always schedules the highest priority ready task
|
|
Procedure:
|
|
- Raise the unityTask priority to (configMAX_PRIORITIES - 1)
|
|
- unityTask creates the following lower priority tasks
|
|
- task_A (configMAX_PRIORITIES - 2)
|
|
- task_B (configMAX_PRIORITIES - 3)
|
|
- UnityTask blocks for a short period of time to allow task_A to run
|
|
- Clean up and restore unityTask's original priority
|
|
Expected:
|
|
- task_A should run after unityTask blocks
|
|
- task_B should never have run
|
|
*/
|
|
#if ( configNUM_CORES == 1 )
|
|
|
|
static BaseType_t test_static_var = 0;
|
|
|
|
static void test_static_func(void)
|
|
{
|
|
...
|
|
}
|
|
|
|
TEST_CASE("Tasks: Priority scheduling single core", "[freertos]")
|
|
{
|
|
...
|
|
}
|
|
|
|
#endif /* configNUM_CORES == 1 */
|
|
```
|