Mirrors_Framework/PX4-Autopilot
1
0
Fork 0
mirror of https://github.com/PX4/PX4-Autopilot.git synced 2026-05-28 10:46:33 +08:00
Code Issues Actions 27 Packages Projects Releases Wiki Activity

docs: update integration tests (#24671)

Browse Source 
* docs: update integration tests

Updates for https://github.com/PX4/PX4-Autopilot/pull/22494.
Transferred from https://github.com/PX4/PX4-user_guide/pull/2970.

* Apply suggestions from code review

* Update docs/en/test_and_ci/integration_testing_ros1_mavros.md

---------

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
This commit is contained in:
Beat Küng
2025-05-07 05:52:03 +02:00
committed by GitHub
parent 87db286a88
commit fee575f944
8 changed files with 217 additions and 178 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/SUMMARY.md
+4 -2
View File
@@ -806,8 +806,10 @@
- [Test MC_05 - Indoor Flight (Manual Modes)](test_cards/mc_05_indoor_flight_manual_modes.md) - [Test MC_05 - Indoor Flight (Manual Modes)](test_cards/mc_05_indoor_flight_manual_modes.md)
- [Unit Tests](test_and_ci/unit_tests.md) - [Unit Tests](test_and_ci/unit_tests.md)
- [Continuous Integration](test_and_ci/continous_integration.md) - [Continuous Integration](test_and_ci/continous_integration.md)
- [MAVSDK Integration Testing](test_and_ci/integration_testing_mavsdk.md) - [Integration Testing](test_and_ci/integration_testing.md)
- [ROS Integration Testing](test_and_ci/integration_testing.md) - [MAVSDK Integration Testing](test_and_ci/integration_testing_mavsdk.md)
- [PX4 ROS2 Interface Library Integration Testing](test_and_ci/integration_testing_px4_ros2_interface.md)
- [ROS 1 Integration Testing](test_and_ci/integration_testing_ros1_mavros.md)
- [Docker Containers](test_and_ci/docker.md) - [Docker Containers](test_and_ci/docker.md)
- [Maintenance](test_and_ci/maintenance.md) - [Maintenance](test_and_ci/maintenance.md)
- [Drone Apps & APIs](robotics/index.md) - [Drone Apps & APIs](robotics/index.md)
docs/en/ros2/px4_ros2_interface_lib.md
+1 -17
View File
@@ -52,20 +52,4 @@ To get started using the library within an existing ROS 2 workspace:
When opening a pull request to PX4, CI runs the library integration tests. When opening a pull request to PX4, CI runs the library integration tests.
These test that mode registration, failsafes, and mode replacement, work as expected. These test that mode registration, failsafes, and mode replacement, work as expected.
The tests can also be run locally from PX4: For more information see [PX4 ROS2 Interface Library Integration Testing](../test_and_ci/integration_testing_px4_ros2_interface.md).
```sh
./test/ros_test_runner.py
```
And to run only a single case:
```sh
./test/ros_test_runner.py --verbose --case <case>
```
You can list the available test cases with:
```sh
./test/ros_test_runner.py --list-cases
```
docs/en/simulation/index.md
+2 -3
View File
@@ -153,9 +153,8 @@ make px4_sitl none_iris
The simulation can be further configured via environment variables: The simulation can be further configured via environment variables:
- `PX4_ESTIMATOR`: This variable configures which estimator to use. - Any of the [PX4 parameters](../advanced_config/parameter_reference.md) can be overridden via `export PX4_PARAM_{name}={value}`.
Possible options are: `ekf2` (default), `lpe` (deprecated). For example changing the estimator: `export PX4_PARAM_EKF2_EN=0; export PX4_PARAM_ATT_EN=1`.
It can be set via `export PX4_ESTIMATOR=lpe` before running the simulation.
The syntax described here is simplified, and there are many other options that you can configure via _make_ - for example, to set that you wish to connect to an IDE or debugger. The syntax described here is simplified, and there are many other options that you can configure via _make_ - for example, to set that you wish to connect to an IDE or debugger.
For more information see: [Building the Code > PX4 Make Build Targets](../dev_setup/building_px4.md#px4-make-build-targets). For more information see: [Building the Code > PX4 Make Build Targets](../dev_setup/building_px4.md#px4-make-build-targets).
docs/en/test_and_ci/index.md
+4 -2
View File
@@ -8,7 +8,9 @@ Test topics include:
- [Test Flights](../test_and_ci/test_flights.md) - How to make test flights (e.g. to [test PRs](../contribute/code.md#pull-requests)) - [Test Flights](../test_and_ci/test_flights.md) - How to make test flights (e.g. to [test PRs](../contribute/code.md#pull-requests))
- [Unit Tests](../test_and_ci/unit_tests.md) - [Unit Tests](../test_and_ci/unit_tests.md)
- [Continuous Integration (CI)](../test_and_ci/continous_integration.md) - [Continuous Integration (CI)](../test_and_ci/continous_integration.md)
- [ROS Integration Testing](../test_and_ci/integration_testing.md) - [Integration Testing](../test_and_ci/integration_testing.md)
- [MAVSDK Integration Testing](../test_and_ci/integration_testing_mavsdk.md) - [MAVSDK Integration Testing](../test_and_ci/integration_testing_mavsdk.md)
- [PX4 ROS2 Interface Library Integration Testing](../test_and_ci/integration_testing_px4_ros2_interface.md)
- [ROS 1 Integration Testing](../test_and_ci/integration_testing_ros1_mavros.md) (Deprecated)
- [Docker](../test_and_ci/docker.md) - [Docker](../test_and_ci/docker.md)
- [Maintenance](../test_and_ci/maintenance.md) - [Maintenance](../test_and_ci/maintenance.md)
docs/en/test_and_ci/integration_testing.md
+9 -148
View File
@@ -1,152 +1,13 @@
# Integration Testing using ROS # Integration Testing
This topic explains how to run (and extend) PX4's ROS-based integration tests. Integration tests are used to verify how well larger parts of a system work together.
In PX4 this generally means testing whole features of a vehicle, usually running in simulation.
The tests are run in [Continuous Integration (CI)](../test_and_ci/continous_integration.md) on every pull request.
::: info - [MAVSDK Integration Testing](../test_and_ci/integration_testing_mavsdk.md) - MAVSDK-based test framework for PX4.
[MAVSDK Integration Testing](../test_and_ci/integration_testing_mavsdk.md) is preferred when writing new tests. _This is the recommended framework for writing new Integration tests_
Use the ROS-based integration test framework for use cases that _require_ ROS (e.g. object avoidance). - [PX4 ROS2 Interface Library Integration Testing](../test_and_ci/integration_testing_px4_ros2_interface.md) - Integration Tests for the [PX4 ROS 2 Interface Library](../ros2/px4_ros2_interface_lib.md).
All PX4 integraton tests are executed automatically by our [Continuous Integration](../test_and_ci/continous_integration.md) system. The following framework should only be used for tests that require ROS 1:
:::
## Prerequisites: - [ROS 1 Integration Testing](../test_and_ci/integration_testing_ros1_mavros.md) (Deprecated)
- [jMAVSim Simulator](../sim_jmavsim/index.md)
- [Gazebo Classic Simulator](../sim_gazebo_classic/index.md)
- [ROS and MAVROS](../simulation/ros_interface.md)
## Execute Tests
To run the MAVROS tests:
```sh
source <catkin_ws>/devel/setup.bash
cd <PX4-Autopilot_clone>
make px4_sitl_default sitl_gazebo
make <test_target>
```
`test_target` is a makefile targets from the set: _tests_mission_, _tests_mission_coverage_, _tests_offboard_ and _tests_avoidance_.
Test can also be executed directly by running the test scripts, located under `test/`:
```sh
source <catkin_ws>/devel/setup.bash
cd <PX4-Autopilot_clone>
make px4_sitl_default sitl_gazebo
./test/<test_bash_script> <test_launch_file>
```
For example:
```sh
./test/rostest_px4_run.sh mavros_posix_tests_offboard_posctl.test
```
Tests can also be run with a GUI to see what's happening (by default the tests run "headless"):
```sh
./test/rostest_px4_run.sh mavros_posix_tests_offboard_posctl.test gui:=true headless:=false
```
The **.test** files launch the corresponding Python tests defined in `integrationtests/python_src/px4_it/mavros/`
## Write a New MAVROS Test (Python)
This section explains how to write a new python test using ROS 1/MAVROS, test it, and add it to the PX4 test suite.
We recommend you review the existing tests as examples/inspiration ([integrationtests/python_src/px4_it/mavros/](https://github.com/PX4/PX4-Autopilot/tree/main/integrationtests/python_src/px4_it/mavros)).
The official ROS documentation also contains information on how to use [unittest](http://wiki.ros.org/unittest) (on which this test suite is based).
To write a new test:
1. Create a new test script by copying the empty test skeleton below:
```python
#!/usr/bin/env python
# [... LICENSE ...]
#
# @author Example Author <author@example.com>
#
PKG = 'px4'
import unittest
import rospy
import rosbag
from sensor_msgs.msg import NavSatFix
class MavrosNewTest(unittest.TestCase):
"""
Test description
"""
def setUp(self):
rospy.init_node('test_node', anonymous=True)
rospy.wait_for_service('mavros/cmd/arming', 30)
rospy.Subscriber("mavros/global_position/global", NavSatFix, self.global_position_callback)
self.rate = rospy.Rate(10) # 10hz
self.has_global_pos = False
def tearDown(self):
pass
#
# General callback functions used in tests
#
def global_position_callback(self, data):
self.has_global_pos = True
def test_method(self):
"""Test method description"""
# FIXME: hack to wait for simulation to be ready
while not self.has_global_pos:
self.rate.sleep()
# TODO: execute test
if __name__ == '__main__':
import rostest
rostest.rosrun(PKG, 'mavros_new_test', MavrosNewTest)
```
1. Run the new test only
- Start the simulator:
```sh
cd <PX4-Autopilot_clone>
source Tools/simulation/gazebo/setup_gazebo.bash
roslaunch launch/mavros_posix_sitl.launch
```
- Run test (in a new shell):
```sh
cd <PX4-Autopilot_clone>
source Tools/simulation/gazebo/setup_gazebo.bash
rosrun px4 mavros_new_test.py
```
1. Add new test node to a launch file
- In `test/` create a new `<test_name>.test` ROS launch file.
- Call the test file using one of the base scripts _rostest_px4_run.sh_ or _rostest_avoidance_run.sh_
1. (Optional) Create a new target in the Makefile
- Open the Makefile
- Search the _Testing_ section
- Add a new target name and call the test
For example:
```sh
tests_<new_test_target_name>: rostest
@"$(SRC_DIR)"/test/rostest_px4_run.sh mavros_posix_tests_<new_test>.test
```
Run the tests as described above.
docs/en/test_and_ci/integration_testing_mavsdk.md
+14 -6
View File
@@ -7,6 +7,10 @@ In future we plan to generalise them for any platform/hardware.
The instructions below explain how to setup and run the tests locally. The instructions below explain how to setup and run the tests locally.
:::note
This is the recommended integration test framework for PX4.
:::
## Prerequisites ## Prerequisites
### Setup Developer Environment ### Setup Developer Environment
@@ -47,21 +51,21 @@ To run all SITL tests as defined in [sitl.json](https://github.com/PX4/PX4-Autop
test/mavsdk_tests/mavsdk_test_runner.py test/mavsdk_tests/configs/sitl.json --speed-factor 10 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. This will list all the tests and then run them sequentially.
To see all possible command line arguments use the `-h` argument: To see all possible command line arguments use the `-h` argument:
```sh ```sh
test/mavsdk_tests/mavsdk_test_runner.py -h 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] usage: mavsdk_test_runner.py [-h] [--log-dir LOG_DIR] [--speed-factor SPEED_FACTOR] [--iterations ITERATIONS] [--abort-early]
[--case CASE] [--debugger DEBUGGER] [--verbose] [--gui] [--model MODEL] [--case CASE] [--debugger DEBUGGER] [--upload] [--force-color]
config_file [--verbose] [--build-dir BUILD_DIR]
positional arguments: positional arguments:
config_file JSON config file to use config_file JSON config file to use
optional arguments: options:
-h, --help show this help message and exit -h, --help show this help message and exit
--log-dir LOG_DIR Directory for log files --log-dir LOG_DIR Directory for log files
--speed-factor SPEED_FACTOR --speed-factor SPEED_FACTOR
@@ -71,9 +75,13 @@ optional arguments:
--abort-early abort on first unsuccessful test --abort-early abort on first unsuccessful test
--gui display the visualization for a simulation --gui display the visualization for a simulation
--model MODEL only run tests for one model --model MODEL only run tests for one model
--case CASE only run tests for one case --case CASE only run tests for one case (or multiple cases with wildcard '*')
--debugger DEBUGGER choice from valgrind, callgrind, gdb, lldb --debugger DEBUGGER choice from valgrind, callgrind, gdb, lldb
--upload Upload logs to logs.px4.io
--force-color Force colorized output
--verbose enable more verbose output --verbose enable more verbose output
--build-dir BUILD_DIR
relative path where the built files are stored
``` ```
## Run a Single Test ## Run a Single Test
docs/en/test_and_ci/integration_testing_px4_ros2_interface.md
+29
View File
@@ -0,0 +1,29 @@
# Integration Testing for the PX4 ROS 2 Interface Library
This topic outlines the integration tests for the [PX4 ROS 2 Interface Library](../ros2/px4_ros2_interface_lib.md).
These test that mode registration, failsafes, and mode replacement, work as expected.
## CI Testing
When opening a pull request to PX4, CI runs the library integration tests.
## Running Tests Locally
The tests can also be run locally from PX4:
```sh
./test/ros_test_runner.py
```
And to run only a single case:
```sh
./test/ros_test_runner.py --verbose --case <case>
```
You can list the available test cases with:
```sh
./test/ros_test_runner.py --list-cases
```
docs/en/test_and_ci/integration_testing_ros1_mavros.md
+154
View File
@@ -0,0 +1,154 @@
# Integration Testing using ROS 1
This topic explains how to run (and extend) PX4's ROS (1) and MAVROS -based integration tests.
:::warning This test framework is deprecated.
It should be used only for new test cases that _require_ ROS 1.
[MAVSDK Integration Testing](../test_and_ci/integration_testing_mavsdk.md) is preferred when writing new tests.
:::
:::note
All PX4 integration tests are executed automatically by our [Continuous Integration](../test_and_ci/continous_integration.md) system.
:::
## Prerequisites
- [Gazebo Classic Simulator](../sim_gazebo_classic/index.md)
- [ROS and MAVROS](../simulation/ros_interface.md)
## Execute Tests
To run the MAVROS tests:
```sh
source <catkin_ws>/devel/setup.bash
cd <PX4-Autopilot_clone>
make px4_sitl_default sitl_gazebo
make <test_target>
```
`test_target` is a makefile targets from the set: _tests_mission_, _tests_mission_coverage_, _tests_offboard_ and _tests_avoidance_.
Test can also be executed directly by running the test scripts, located under `test/`:
```sh
source <catkin_ws>/devel/setup.bash
cd <PX4-Autopilot_clone>
make px4_sitl_default sitl_gazebo
./test/<test_bash_script> <test_launch_file>
```
For example:
```sh
./test/rostest_px4_run.sh mavros_posix_tests_offboard_posctl.test
```
Tests can also be run with a GUI to see what's happening (by default the tests run "headless"):
```sh
./test/rostest_px4_run.sh mavros_posix_tests_offboard_posctl.test gui:=true headless:=false
```
The **.test** files launch the corresponding Python tests defined in `integrationtests/python_src/px4_it/mavros/`
## Write a New MAVROS Test (Python)
This section explains how to write a new python test using ROS 1/MAVROS, test it, and add it to the PX4 test suite.
We recommend you review the existing tests as examples/inspiration ([integrationtests/python_src/px4_it/mavros/](https://github.com/PX4/PX4-Autopilot/tree/main/integrationtests/python_src/px4_it/mavros)).
The official ROS documentation also contains information on how to use [unittest](http://wiki.ros.org/unittest) (on which this test suite is based).
To write a new test:
1. Create a new test script by copying the empty test skeleton below:
```python
#!/usr/bin/env python
# [... LICENSE ...]
#
# @author Example Author <author@example.com>
#
PKG = 'px4'
import unittest
import rospy
import rosbag
from sensor_msgs.msg import NavSatFix
class MavrosNewTest(unittest.TestCase):
"""
Test description
"""
def setUp(self):
rospy.init_node('test_node', anonymous=True)
rospy.wait_for_service('mavros/cmd/arming', 30)
rospy.Subscriber("mavros/global_position/global", NavSatFix, self.global_position_callback)
self.rate = rospy.Rate(10) # 10hz
self.has_global_pos = False
def tearDown(self):
pass
#
# General callback functions used in tests
#
def global_position_callback(self, data):
self.has_global_pos = True
def test_method(self):
"""Test method description"""
# FIXME: hack to wait for simulation to be ready
while not self.has_global_pos:
self.rate.sleep()
# TODO: execute test
if __name__ == '__main__':
import rostest
rostest.rosrun(PKG, 'mavros_new_test', MavrosNewTest)
```
1. Run the new test only
- Start the simulator:
```sh
cd <PX4-Autopilot_clone>
source Tools/simulation/gazebo/setup_gazebo.bash
roslaunch launch/mavros_posix_sitl.launch
```
- Run test (in a new shell):
```sh
cd <PX4-Autopilot_clone>
source Tools/simulation/gazebo/setup_gazebo.bash
rosrun px4 mavros_new_test.py
```
1. Add new test node to a launch file
- In `test/` create a new `<test_name>.test` ROS launch file.
- Call the test file using one of the base scripts _rostest_px4_run.sh_ or _rostest_avoidance_run.sh_
1. (Optional) Create a new target in the Makefile
- Open the Makefile
- Search the _Testing_ section
- Add a new target name and call the test
For example:
```sh
tests_<new_test_target_name>: rostest
@"$(SRC_DIR)"/test/rostest_px4_run.sh mavros_posix_tests_<new_test>.test
```
Run the tests as described above.