# MAVSDK Integration Testing PX4 can be tested end to end to using integration tests based on [MAVSDK](https://mavsdk.mavlink.io). The tests are primarily developed against SITL and run in continuous integration (CI). In future we plan to generalise them for any platform/hardware. The instructions below explain how to setup and run the tests locally. ## Prerequisites ### Setup Developer Environment If you haven't done so already: * Install the development toolchain for [Linux](/px4-user-guide/development/getting_started/dev_env/dev_env_linux_ubuntu.md) or [macOS](/px4-user-guide/development/getting_started/dev_env/dev_env_mac.md) (Windows not supported). [Gazebo Classic](/px4-user-guide/development/simulation/sim_gazebo_classic.md) is required, and should be installed by default. * [Get the PX4 source code](/px4-user-guide/development/getting_started/building_px4.md#download-the-px4-source-code): ```sh git clone https://github.com/PX4/PX4-Autopilot.git --recursive cd PX4-Autopilot ``` ### Build PX4 for Testing To build PX4 source code for simulator testing, use: ```sh DONT_RUN=1 make px4_sitl gazebo-classic mavsdk_tests ``` ### Install the MAVSDK C++ Library The tests need the MAVSDK C++ library installed system-wide (e.g. in `/usr/lib` or `/usr/local/lib`). Install either from binaries or source: * [MAVSDK > C++ > C++ QuickStart](https://mavsdk.mavlink.io/main/en/cpp/quickstart.html): Install as a prebuilt library on supported platforms (recommended) * [MAVSDK > C++ Guide > Building from Source](https://mavsdk.mavlink.io/main/en/cpp/guide/build.html): Build C++ library from source. ## Run All PX4 Tests To run all SITL tests as defined in [sitl.json](https://github.com/PX4/PX4-Autopilot/blob/main/test/mavsdk_tests/configs/sitl.json), do: ```sh test/mavsdk_tests/mavsdk_test_runner.py test/mavsdk_tests/configs/sitl.json --speed-factor 10 ``` This will list all of the tests and then run them sequentially. To see all possible command line arguments use the `-h` argument: ```sh test/mavsdk_tests/mavsdk_test_runner.py -h usage: mavsdk_test_runner.py [-h] [--log-dir LOG_DIR] [--speed-factor SPEED_FACTOR] [--iterations ITERATIONS] [--abort-early] [--gui] [--model MODEL] [--case CASE] [--debugger DEBUGGER] [--verbose] config_file positional arguments: config_file JSON config file to use optional arguments: -h, --help show this help message and exit --log-dir LOG_DIR Directory for log files --speed-factor SPEED_FACTOR how fast to run the simulation --iterations ITERATIONS how often to run all tests --abort-early abort on first unsuccessful test --gui display the visualization for a simulation --model MODEL only run tests for one model --case CASE only run tests for one case --debugger DEBUGGER choice from valgrind, callgrind, gdb, lldb --verbose enable more verbose output ``` ## Run a Single Test Run a single test by specifying the `model` and test `case` as command line options. For example, to test flying a tailsitter in a mission you might run: ```bash test/mavsdk_tests/mavsdk_test_runner.py test/mavsdk_tests/configs/sitl.json --speed-factor 10 --model tailsitter --case 'Fly VTOL mission' ``` The easiest way to find out the current set of models and their associated test cases is to run all PX4 tests [as shown above](#run-all-px4-tests) (note, you can then cancel the build if you wish to test just one). At time of writing the list generated by running all tests is: ``` About to run 39 test cases for 3 selected models (1 iteration): - iris: - 'Land on GPS lost during mission (baro height mode)' - 'Land on GPS lost during mission (GPS height mode)' - 'Continue on mag lost during mission' - 'Continue on baro lost during mission (baro height mode)' - 'Continue on baro lost during mission (GPS height mode)' - 'Continue on baro stuck during mission (baro height mode)' - 'Continue on baro stuck during mission (GPS height mode)' - 'Takeoff and Land' - 'Fly square Multicopter Missions including RTL' - 'Fly square Multicopter Missions with manual RTL' - 'Fly straight Multicopter Mission' - 'Offboard takeoff and land' - 'Offboard position control' - 'Fly forward in position control' - 'Fly forward in altitude control' - standard_vtol: - 'Land on GPS lost during mission (baro height mode)' - 'Land on GPS lost during mission (GPS height mode)' - 'Continue on mag lost during mission' - 'Continue on baro lost during mission (baro height mode)' - 'Continue on baro lost during mission (GPS height mode)' - 'Continue on baro stuck during mission (baro height mode)' - 'Continue on baro stuck during mission (GPS height mode)' - 'Takeoff and Land' - 'Fly square Multicopter Missions including RTL' - 'Fly square Multicopter Missions with manual RTL' - 'Fly forward in position control' - 'Fly forward in altitude control' - tailsitter: - 'Land on GPS lost during mission (baro height mode)' - 'Land on GPS lost during mission (GPS height mode)' - 'Continue on mag lost during mission' - 'Continue on baro lost during mission (baro height mode)' - 'Continue on baro lost during mission (GPS height mode)' - 'Continue on baro stuck during mission (baro height mode)' - 'Continue on baro stuck during mission (GPS height mode)' - 'Takeoff and Land' - 'Fly square Multicopter Missions including RTL' - 'Fly square Multicopter Missions with manual RTL' - 'Fly forward in position control' - 'Fly forward in altitude control' ``` ## Notes on implementation * The tests are invoked from the test runner script [mavsdk\_test\_runner.py](https://github.com/PX4/PX4-Autopilot/blob/main/test/mavsdk_tests/mavsdk_test_runner.py), which is written in Python. In addition to MAVSDK, this runner starts `px4` as well as Gazebo for SITL tests, and collects the logs of these processes. * The test runner is a C++ binary that contains: * The [main](https://github.com/PX4/PX4-Autopilot/blob/main/test/mavsdk_tests/test_main.cpp) function to parse the arguments. * An abstraction around MAVSDK called [autopilot\_tester](https://github.com/PX4/PX4-Autopilot/blob/main/test/mavsdk_tests/autopilot_tester.h). * The actual tests using the abstraction around MAVSDK as e.g. [test\_multicopter\_mission.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/test/mavsdk_tests/test_multicopter_mission.cpp). * The tests use the [catch2](https://github.com/catchorg/Catch2) unit testing framework. The reasons for using this framework are: * Asserts (`REQUIRE`) which are needed to abort a test can be inside of functions (and not just in the top level test as is [the case with gtest](https://github.com/google/googletest/blob/main/docs/advanced.md#assertion-placement)). * Dependency management is easier because *catch2* can just be included as a header-only library. * *Catch2* supports [tags](https://github.com/catchorg/Catch2/blob/devel/docs/test-cases-and-sections.md#tags), which allows for flexible composition of tests. Terms used: * "model": This is the selected Gazebo model, e.g. `iris`. * "test case": This is a [catch2 test case](https://github.com/catchorg/Catch2/blob/master/docs/test-cases-and-sections.md). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://px4.gitbook.io/px4-user-guide/development/test_and_ci/integration_testing_mavsdk.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.