Setup¶
Tests require Blender to be built, see the official build instructions. This document assumes the directory layout to be:
Running the tests is then done with make test:
GTest tests need Blender to be built
with WITH_GTESTS enabled.
Updating Test Files¶
Test files change along with the Blender source code. Pulling the latest
changes with make update will update tests to the latest version together
with the Blender source code.
Running Tests¶
make test runs all available tests. For fine control, use
ctest
directly.
ctest must be run from the build directory.
Some example commands are:
# List available tests
ctest -N
# Run all tests with name matching "alembic"
ctest -R alembic
# Show verbose output for a test, to get more information on why it failed
ctest -VV -R alembic
# Run tests in parallel, and show verbose output for failed tests
ctest -j 4 --output-on-failure
When building with Visual Studio or Xcode, the build configuration needs
to be specified for every ctest command, for example:
Some GTest tests bundle together all tests within a Blender module. It's
possible to run only specific test within a module as follows. Find the
name of the module test, for example by listing all tests with ctest -N.
Then run the test with verbose output:
This shows the exact command that is run for each test. You can then copy-paste that command to run it yourself.
ASAN builds¶
Running tests on ASAN builds is tricky, because ASAN will fail most of
them due to false/unrelated memory leak detection. However, completely
'silencing' ASAN reports using the exitcode=0 ASAN_OPTIONS is a
(very) bad idea, as it will also hide many actual issues, including
segfaults!
The first step is to remove memleaks errors which happen in third party
libraries, see the ASAN
page
for details.
The guardedalloc test intentionally attempts to allocate an invalid
amount of memory and expects to fail and return NULL in that case.
allocator_may_return_null=true is required for this test to behave
as expected.
ASAN_OPTIONS="allocator_may_return_null=true" LSAN_OPTIONS="print_suppressions=false:suppressions=/path/to/blender/tools/config/analysis/lsan.supp" ctest -j 4 --output-on-failure
No LSAN Suppressions
In case LSAN suppressions do not work for some reason, it is also
possible to pass leak_check_at_exit=false to ASAN_OPTIONS.
However, doing this will also hide valid memleaks reports,
which should be avoided as much as possible.
Adding Tests¶
Tests can be written in Python or C++. For tests that can easily be written in Python, this is preferred. Lower-level tests can be written in C++ files next to the sources under test. See the language-specific pages for more info.
Committing Test Data¶
Test data is part of the Blender repository, so making changes to tests follows the same general instructions as a normal pull request and commit.
Test files can be found in the directory ~/blender-git/blender/tests/files/
Make sure the tests pass before committing to main
You should run your tests to make sure they pass before committing them to main. This can be done locally, or using the Blender Bot from Gitea to ensure they pass on all platforms. The steps for testing on the build bot are as follows:
Create a pull request with your changes to the Blender source code and relevant test files.
On the projects.blender.org page for your pull request, comment @blender-bot build
to get the build bot to test your changes.
But default this does not run all tests. Usually tests that need a GPU are not run by default. You can find documentation on additional tags to specify in order to enable extra tests in the Blender Bot README.
If the tests pass, then you can merge the pull request into main.