tests/bluetooth/bsim_bt/bsim_test_mesh/README.rst

Bluetooth mesh BabbleSim tests
##############################

This directory contains a set of high level system tests for the Bluetooth mesh
subsystem. The tests run on the BabbleSim simulator, using the BabbleSim test
framework.

Tests are organized into bash scripts under the test_scripts folder. Each
subfolder of test_scripts contains tests for a specific module in the Bluetooth
mesh subsystem, and each folder has a corresponding test_<subfolder>.c under the
src/ directory containing the necessary test harnesses to execute the tests.

There's only a single test application for all the Bluetooth mesh BabbleSim
tests. The test application is built from this directory, and includes all test
harnesses in every build. The overlying bsim test framework selects the harness
to use at runtime, using the test identifiers passed in the test scripts.

Running the tests
*****************

The Bluetooth mesh tests have no extra requirements, and can be run using the
procedure described in the parent folder.

To only run the mesh tests, set ``SEARCH_PATH`` to point to this folder before
calling ``run_parallel.sh``

Debugging the tests
===================

Individual test harnesses can be run outside of ``RunTest()`` by setting the
``$SKIP`` array environment variable before calling ``RunTest``. This causes
``RunTest`` to skip starting processes for each application in the ``$SKIPPED``
array, so that they can be started independently in gdb, valgrind or some other
external tool.

When running test applications independently, make sure to assign the original
device number with -dXXX to the process.

Example: To debug the ``transport_tx_seg_block`` test harness in the transport
seg_block test, change transport/seg_block.sh to

..code-block::

   SKIP=(transport_tx_seg_block)
   RunTest mesh_transport_seg_block \
      transport_tx_seg_block \
      transport_rx_seg_block

Then separately, call

...code-block::

   gdb bs_nrf52_bsim_tests_bluetooth_bsim_bt_bsim_test_mesh_prj_conf \
       -s=mesh_transport_seg_block -d=0 -RealEncryption=1 \
       -testid=transport_tx_seg_block

Framework
*********

The Bluetooth mesh BabbleSim tests mainly operate on the test framework for the
BabbleSim platform, but with some mesh specific additions:

mesh_test.sh
=============

All test scripts in the Bluetooth mesh BabbleSim test suite follow a common
pattern for running a single test across N devices with different test
harnesses. ``mesh_test.sh`` is sourced in each test script, and its ``RunTest``
function is called once in each script with the following parameters:

..code-block::

   RunTest <test name> <harness_name_1> <harness_name_2>...

``RunTest`` starts one mesh application for each selected harness, before
starting the BabbleSim phy process.

mesh_test.c
===========

Common target side mesh behavior is collected in mesh_test.c and mesh_test.h.
This includes ``PASS``/``FAIL`` macros and some common mesh actions, such as
mesh initialization, as well as message sending and receiving.

The mesh_test module is never called from the framework, so each test harness
is free to call the parts that are appropriate for its implementation.
All utility functions can be replaced by custom behavior in each harness if the
generic implementation does not fit with the harness requirements.

Adding tests
************

Each test needs a separate test script and one or more test harnesses that
execute the test on target.

Test scripts should be organized by submodules under the test_scripts
directory, and each test case needs a separate test script with a single test
run.

Each test harness is defined by a ``struct bst_test_instance` structure, that
is presented to the test runner through an ``install`` function called from the
test application's main function. The harness contains a set of callback
functions that allows starting the test behavior.

Each mesh test harness should call the ``bt_mesh_test_cfg`` function from its
``test_init_f`` callback to set up the test timeout and mesh metadata. The test
will run until the mesh_test module's ``FAIL`` macro is called, or until the
test times out. At the test timeout, the test will pass if the ``PASS()`` macro
has been called - otherwise, it will fail.

..note::

   The Bluetooth stack must be initialized in the ``test_main_f`` function of
   the harness, as the previous callbacks are all executed in hardware threads.

The Bluetooth mesh tests include the entire Bluetooth host and controller
subsystems, so timing requirements should generally be kept fairly liberal to
avoid regressions on changes in the underlying layers.