Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
O
OpenXG-RAN
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
0
Merge Requests
0
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Analytics
Analytics
CI / CD
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
zzha zzha
OpenXG-RAN
Commits
251a1c6e
Commit
251a1c6e
authored
Aug 01, 2023
by
Robert Schmidt
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Add unit testing documentation
parent
70b66a86
Changes
2
Hide whitespace changes
Inline
Side-by-side
Showing
2 changed files
with
110 additions
and
1 deletion
+110
-1
doc/README.md
doc/README.md
+2
-1
doc/UnitTests.md
doc/UnitTests.md
+108
-0
No files found.
doc/README.md
View file @
251a1c6e
...
...
@@ -99,6 +99,7 @@ The other SDRs (AW2S, LimeSDR, ...) have no READMEs.
-
OAI comes with an integrated
[
telnet server
](
../common/utils/telnetsrv/DOC/telnethelp.md
)
to monitor and control
-
OAI comes with an integrated
[
web server
](
../common/utils/websrv/DOC/websrv.md
)
#
CI
#
Testing
-
[
UnitTests.md
](
./UnitTests.md
)
explains the unit testing setup
-
[
TESTBenches.md
](
./TESTBenches.md
)
lists the CI setup and links to pipelines
doc/UnitTests.md
0 → 100644
View file @
251a1c6e
# Unit Testing in OAI
OpenAirInterface uses
[
ctest
](
https://cmake.org/cmake/help/latest/manual/ctest.1.html
)
for unit
testing. The cmake documentation has a
[
tutorial
](
https://cmake.org/cmake/help/book/mastering-cmake/chapter/Testing%20With%20CMake%20and%20CTest.html
)
explaining how to test with cmake and ctest; it is a suggested read, and the
following just lists the main points of how to compile the tests and how to add
new ones.
At the time of writing, only the NR RLC tests have been integrated. The author
hopes that more tests follow suit.
# How to compile tests
To compile only the tests, a special target
`tests`
is available. It has to be
enabled with the special cmake variable
`ENABLE_TESTS`
:
```
bash
cd
openairinterface5g
mkdir
build
&&
cd
build
# you can also do that in cmake_targets/ran_build/build
cmake ..
-GNinja
-DENABLE_TESTS
=
ON
ninja tests
```
Then, you can run
`ctest`
to run all tests:
```
$ ctest
Test project /home/richie/w/ctest/build
Start 1: nr_rlc_tests
1/1 Test #1: nr_rlc_tests ..................... Passed 0.06 sec
100% tests passed, 0 tests failed out of 1
Total Test time (real) = 0.06 sec
```
A couple of interesting variables are
`--verbose`
,
`--output-on-failure`
.
# How to add a new test
As of now, there is no dedicated testing directory. Rather, tests are together
with the sources of the corresponding (sub)system. The generic four-step
process is
1.
Guard all the following steps with
`if(ENABLE_TESTS)`
. In a world where OAI
is tested completely, there would be many executables that would be of
tangential interest to the average user only. A "normal" build without tests
would result in less executables, due to this guard.
2.
Add an executable that you want to execute. In a
`CMakeLists.txt`
, do for
instance
`add_executable(my_test mytest.c)`
where
`mytest.c`
contains
`main()`
. You can then build this executable with
`ninja/make my_test`
,
given you ran
`cmake -DENABLE_TESTS=ON ...`
before.
3.
Create a dependency to
`tests`
so that triggering the
`tests`
(
`ninja/make
tests`
) target will build your test:
`add_dependencies(tests my_test)`
.
4.
Use
`add_test(NAME my_new_test COMMAND my_test <options>)`
to declare a new
test that will be run by
`ctest`
under name
`my_new_test`
.
In the simplest case, in an existing
`CMakeLists.txt`
, you might add the
following:
```
if(ENABLE_TESTS)
add_executable(my_test mytest.c)
add_dependencies(tests my_test)
add_test(NAME my_new_test COMMAND my_test) # no options required
endif()
```
Note that this might get more complicated, e.g., typically you will have to
link some library into the executable with
`target_link_libraries()`
, or pass
some option to the test program.
`ctest`
decides if a test passed via the return code of the program. So a test
executable that always passes is
`int main() { return 0; }`
and one that always
fails
`int main() { return 1; }`
. It is left as an exercise to the reader to
include these examples into
`ctest`
. Other programming languages other than C
or shell scripts are possible but discouraged. Obviously, though, a test in
a mainstream non-C programming language/shell script (C++, Rust, Python, Perl)
is preferable over no test.
Let's look at a more concrete, elaborate example, the NR RLC tests.
They are located in
`openair2/LAYER2/nr_rlc/tests/`
. Note that due to
historical reasons, a test script
`run_tests.sh`
allows to run all tests from
that directory directly, which you might also use to compare to the
`cmake`
/
`ctest`
implementation.
1.
Since the tests are in a sub-directory
`tests/`
, the inclusion of the entire
directory is guarded in
`openair2/LAYER2/nr_rlc/CMakeLists.txt`
(in fact, it
might in general be a good idea to create a separate sub-directory
`tests/`
!).
2.
The NR RLC tests in fact consist of one "test driver program" (
`test.c`
)
which is compiled with different "test stimuli" into the program. In total,
there are 17 stimuli (
`test1.h`
to
`test17.h`
) with corresponding known
"good" outputs after running (in
`test1.txt.gz`
to
`test17.txt.gz`
). To
implement this, the
`tests/CMakeLists.txt`
creates multiple executables
`nr_rlc_test_X`
via the loop over
`TESTNUM`
, links necessary libraries into
the test driver and a compile definition for the test stimuli.
3.
For each executable, create a dependency to
`tests`
.
4.
Finally, there is a single(!)
`ctest`
test that runs all the 17 test
executables at once(!). If you look at the shell script
`exec_nr_rlc_test.sh`
, you see that it runs the program, filters for
`TEST`
,
and compares with a predefined output from each test in
`testX.txt.gz`
,
which is
`gunzip`
ed on the fly... Anyway, the actual
`add_test()`
definition
just tells
`ctest`
to run this script (in the source directory), and passes
an option where to find the executables (in the build directory). This
slight complication is due to using shell scripts. An easier way is to
directly declare the executable in
`add_test()`
, and
`ctest`
will locate and
run the executable properly.
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment