Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/PX4/PX4-Autopilot/llms.txt

Use this file to discover all available pages before exploring further.

PX4 is safety-critical software — a bug in flight control code can crash a vehicle. Every contribution must include adequate testing. This page explains the testing tools available, how to run them locally, and what the CI pipeline checks before a pull request can be merged.
Reviewers will not approve pull requests for new features or bug fixes without test evidence. This means either automated tests that run in CI, or flight logs uploaded to Flight Review for hardware-dependent changes.

​
Types of tests

Test typeWhen to useHow to run
Unit tests (gtest)Module-level logic, math, parsing, state machinesmake tests
SITL integration testsFlight behavior, failsafes, missions, mode changestest/mavsdk_tests/
Bench tests / flight logsHardware-dependent changes that can’t run in SITLUpload to Flight Review

​
Running tests locally

Always run tests locally before pushing. CI runs the same checks, so catching failures early saves time. 
make tests                    # run all unit tests
make px4_sitl_test            # SITL test suite
Run make tests after every meaningful logic change. Unit tests are fast and give you immediate feedback before you even open a pull request.

​
Unit tests

PX4 uses GoogleTest (gtest) as its unit test framework. Unit tests live alongside the modules they test, typically in a test/ subdirectory or a *_test.cpp file next to the module source.

​
Running unit tests

# Run all unit tests
make tests

# Run a specific test binary (after building)
./build/px4_sitl_default/unit_test_runner --gtest_filter=EkfTest.*

​
Writing a unit test

#include <gtest/gtest.h>
#include "my_module/my_module.hpp"

class MyModuleTest : public ::testing::Test {
protected:
	MyModule _module;
};

TEST_F(MyModuleTest, computesCorrectOutput) {
	const float result = _module.compute(1.0f);
	EXPECT_NEAR(result, 2.0f, 1e-5f);
}
Register your test target in the module’s CMakeLists.txt: 
px4_add_unit_gtest(
	SRC my_module_test.cpp
	LINKLIBS my_module
)
New features must include unit tests that exercise the new logic where it is practical to do so. Hardware-dependent code that cannot be tested in simulation should include flight log evidence instead.

​
SITL integration tests

Software-in-the-Loop (SITL) integration tests run the full PX4 stack in simulation using Gazebo. They test end-to-end flight behavior including missions, failsafes, and mode transitions.

​
Running SITL tests

make px4_sitl_test
SITL integration tests use MAVSDK to command the vehicle and verify behavior over MAVLink. Each test script in test/mavsdk_tests/ covers a specific flight scenario.

​
Hardware-in-the-loop tests

For changes that require real hardware (sensor drivers, actuator outputs, board-specific code), run bench tests or actual flight tests and upload the resulting log files:
1

Flash and fly

Build and flash the firmware to your hardware target, then perform the relevant test flight or bench test.
2

Retrieve the log

Copy the .ulg log file from the microSD card. Logs are stored in /fs/microsd/log/.
3

Upload to Flight Review

Upload the log to logs.px4.io and copy the resulting URL.
4

Link in your PR

Paste the Flight Review URL in your pull request description. Reviewers will examine the log to verify the fix or feature works correctly.

​
CI pipeline overview

PX4 uses GitHub Actions for continuous integration. Every pull request triggers the full CI pipeline automatically.

​
What CI checks

1

Format check

Runs make check_format to verify all changed C/C++ files are correctly formatted. Failures block the PR.
2

Build matrix

Builds PX4 for a matrix of target boards and configurations to catch compilation errors across platforms.
3

Unit tests

Runs make tests and reports any test failures.
4

SITL tests

Runs a subset of the SITL integration test suite in simulation.
5

Commit message lint

Validates that all commit messages and the PR title follow the type(scope): description conventional commit format.

​
CI workflow files

CI configuration lives in .github/workflows/. Use the ci scope when committing changes to workflow files: 
ci(workflows): add nightly Gazebo integration test job
All CI checks must pass before a maintainer can approve and merge your pull request. If a check fails on infrastructure issues (flaky test, network timeout), you can re-run the specific job from the GitHub Actions UI.

​
Pre-PR checklist

Before opening a pull request, confirm you have completed the following:
1

Format your code

make format
make check_format   # must exit 0
2

Run unit tests

make tests
3

Run SITL tests if applicable

make px4_sitl_test
4

Prepare test evidence

For hardware changes, upload your flight log to Flight Review and note the URL to include in your PR description.
5

Check your commit messages

Every commit message must follow type(scope): description. Fix them with an interactive rebase before pushing:
git rebase -i HEAD~N
git push --force-with-lease

Build docs developers (and LLMs) love

Get started for freeTalk to us