There's a mixture of RTPengine and RTPEngine, though we lowercase it
entirely most of the time, so let's stick to this and unify its style.
While at it remove the "the" article for rtpengine as well,
where applicable.
Change-Id: Idbad9313499942ad12ade2c9ce76fe3ec4cd2762
@ -45,7 +45,7 @@ As for setting up the kernel's forwarding chain: It's basically the same process
`sfd->stream->selected_sfd->socket.local`: the local source IP/port for the outgoing packet
**Handling behind the NAT**:\
If the RTPengine runs behind the NAT and local addresses are configured with different advertised endpoints,\
If rtpengine runs behind the NAT and local addresses are configured with different advertised endpoints,\
the SDP would not contain the address from `...->socket.local`, but rather from `sfd->local_intf->spec->address.advertised` (of type `sockaddr_t`).\
The port will be the same.
@ -120,7 +120,7 @@ This populates the list of `rtp_sinks` and `rtcp_sinks` for each packet stream.
Flags and attributes from the `call_subscription` objects are copied into the according sink_handler object(s).\
During actual packet handling and forwarding, only the `sink_handler` objects (and the packet_stream objects they related to) are used, not the `call_subscription` objects.
Processing of signaling event (offer/answer) to the RTPEngine,\
Processing of signaling event (offer/answer) to rtpengine,\
in terms of using functionality looks as following (for one `call_monologue`):
* signaling event begins (offer / answer)
@ -241,7 +241,7 @@ The tag value will taken:
Things are getting slightly more complicated, when there is a branched call.\
In this situation, the same offer is sent to multiple receivers, possibly with different options.\
At this point of time, multiple monologues are created in the RTPEngine and all of them without a known tag value\
At this point of time, multiple monologues are created in rtpengine and all of them without a known tag value\
(essentially without To-tag).
At this point they all are distinguished by the via-branch value.\
This is the page, which describes how to prepare unit tests for newly introduced features in the RTPEngine.
This is the page, which describes how to prepare unit tests for newly introduced features in rtpengine.
---
Adding of new tests is a required procedure, which allows us to cover fixes/changes/feature being added into the RTPEngine.\
Adding of new tests is a required procedure, which allows us to cover fixes/changes/feature being added into rtpengine.\
They make sure, that:
* first, new changes being added are reflecting the intention of these change, and hence give expected results
* second, they will make sure, that this expected behavior (in this very scope) won’t get broken in the future, by newer changes. And even if, we will notice that and will make sure to fix it.
@ -16,14 +16,14 @@ Here there is a bunch of files written in Perl, Python and C, dedicated for diff
_NOTE: They are being run with `make check` and during packaging._
_Nevertheless, not everything in that directory is actually run as part of `make check` (some are for manual testing)._
These tests actually spawn a real RTPengine process in a fake network environment (see `tests-preload.c` and its invocation in the `makefile`, and also the command-line options given at the start of each of these scripts) and then facilitate real SDP offer/answer exchanges and test real RTP forwarding against it.
These tests actually spawn a real rtpengine process in a fake network environment (see `tests-preload.c` and its invocation in the `makefile`, and also the command-line options given at the start of each of these scripts) and then facilitate real SDP offer/answer exchanges and test real RTP forwarding against it.
This is the closest possible way to simulate real SIP calls. The code supporting these tests is written using a few Perl libraries stored in `perl/` folder of the project, which are able to do the signalling, SRTP, ICE, etc.
Most importantly, there are some unit tests (e.g. `aead-aes-crypt` or `test-transcode`), but the most comprehensive test scripts are the ones called `auto-daemon-tests`.
Let’s take as an example the: `auto-daemon-tests.pl` \
This one has a huge amount of basic tests related to mostly general things RTPEngine does.
This one has a huge amount of basic tests related to mostly general things rtpengine does.
Let’s have a look into one of the tests, in this case ‘SDP version force increase':
@ -99,21 +99,21 @@ The syntax here is:
* `new_call;` - start a new test procedure, kinda new call
* `'SDP version force increase'` - is a test’s name
* `replace => ['force-increment-sdp-ver']` - is a given flag (emulates as if we would add this flag, when calling the `rtpengine_offer()`)
* first instance of the SDP (so before `----------------------------`) - is what we hand to the RTPEngine
* second instance after that, is what we expect RTPEngine to generate for us (as result)
* first instance of the SDP (so before `----------------------------`) - is what we hand to rtpengine
* second instance after that, is what we expect rtpengine to generate for us (as result)
* `SDP` - is an end of given SDPs for this sub-test
_NOTE: Every new test (new_call) can have many sub-tests included. So you can wrap into that something within one big scope, such as tests related to the SDP session version._
Generally said, if there is a new thing/feature being added into the RTPEngine, and this can potentially affect the behavior (even under some really specific circumstances), it’s important to cover this change with tests. For example: to emulate the call with a newly given flag and see that the expected results is given.
Generally said, if there is a new thing/feature being added into rtpengine, and this can potentially affect the behavior (even under some really specific circumstances), it’s important to cover this change with tests. For example: to emulate the call with a newly given flag and see that the expected results is given.
_NOTE: make `daemon-tests-main` inside of `/t` can be used to run the tests manually._
Individually the unit tests can be executed normally, but the `auto-daemon-tests` need special instrumentation. Either use `make daemon-tests-X` from within `t/`, or if there is a need to execute the test script manually and separately from RTPengine:
Individually the unit tests can be executed normally, but the `auto-daemon-tests` need special instrumentation. Either use `make daemon-tests-X` from within `t/`, or if there is a need to execute the test script manually and separately from rtpengine:
* Make sure `tests-preload.so` exists (`make -C t tests-preload.so`)
* In one shell: `LD_PRELOAD=t/tests-preload.so daemon/rtpengine --config-file=none -t -1 -i 203.0.113.1 ...` (CLI options taken from respective test script)
* In another shell: `LD_PRELOAD=t/tests-preload.so RTPE_TEST_NO_LAUNCH=1 perl -Iperl t/auto-daemon-tests.pl`
This even works with RTPengine running under a debugger or valgrind.
This even works with rtpengine running under a debugger or valgrind.
Another set of tests that is included is to run all of the `make check` tests under libasan. The top-level `make asan-check` target exists for that purpose and requires an initially clean source directory to execute properly.
@ -48,16 +48,16 @@ Important thing is to always point the `G_SLICE=always-malloc` environment varia
Other than that, the valgrind option `--leak-check=full` is also quite important thing to have, since it tells where exactly the memory leak is.
At this point the RTPEngine is up and running. It’s time to launch, in a separate terminal, tests themselves (those tests, which were prepared to cover a new feature, or just common tests, if there is no new feature and it was a bug fix).
At this point rtpengine is up and running. It’s time to launch, in a separate terminal, tests themselves (those tests, which were prepared to cover a new feature, or just common tests, if there is no new feature and it was a bug fix).
For that to work, the option telling that RTPEngine is already running, must be given:
For that to work, the option telling that rtpengine is already running, must be given:
This has been launched from the t/ folder. And the ‘RTPE_TEST_NO_LAUNCH=1’ tells the auto tests that the RTPEngine is already running and there is no need to launch another one.
This has been launched from the t/ folder. And the ‘RTPE_TEST_NO_LAUNCH=1’ tells the auto tests that rtpengine is already running and there is no need to launch another one.
_NOTE: Alternatively it’s possible to run tests with any other way sending commands to the RTPEngine, to let it do some work in the concerned scope._
_NOTE: Alternatively it’s possible to run tests with any other way sending commands to rtpengine, to let it do some work in the concerned scope._
After tests are finished, it’s time to collect the report from the valgrind.\
Ctrl+C the terminal, where the binary has been launched before, and if there are no issues, the report must look something like that:
@ -88,7 +88,7 @@ Running one particular test under the valgrind.\
In case there is a demand to run only one of those auto-daemon-tests under the valgrind, it’s possible to do so, just by editing the auto-daemon-tests.pl (or any other targeted test file indeed).
This detailed way of running one test, gives a list of advantages:
* there is the RTPEngine log file in the end (usually in the /tmp folder)
* there is the rtpengine log file in the end (usually in the /tmp folder)
* less time waiting, till test is finished
* for debugging memory issues, one can exactly see amount of bytes left not freed for this particular test (so no other tests will contribute here with not freed memory). Hence simpler to find the place triggering this memory leak.
@ -99,7 +99,7 @@ Then, after the definition of the test, it’s just required to place this row:
Which will tell the auto tests to stop running and generate a log file in the end. Furthermore, in a such way of running, it’s even possible to get the coredump. The folder for storing that will be selected according to defaults of the environment, where the RTPEngine was run. For example, in the Ubuntu 22.04, by default coredumps are being stored in the: `/var/lib/apport/coredump`
Which will tell the auto tests to stop running and generate a log file in the end. Furthermore, in a such way of running, it’s even possible to get the coredump. The folder for storing that will be selected according to defaults of the environment, where rtpengine was run. For example, in the Ubuntu 22.04, by default coredumps are being stored in the: `/var/lib/apport/coredump`
Michael Prokop
3 years ago