Setup

Tests require Blender to be built, see the official build instructions. This document assumes the directory layout to be:

~/blender-git/blender  # Blender source directory
~/blender-git/build    # Blender build directory

Running the tests is then done with make test:

cd ~/blender-git/blender
make test

GTest tests need Blender to be built with WITH_GTESTS enabled.

Downloading Test Files

Additional binary test files are needed for running the Blender tests. These are available through a Git submodule, separate from the Blender source repository.

make test will automatically download these files the first time it runs.

To download the test files manually:

cd ~/blender-git/blender
python3 ./build_files/utils/make_update.py --use-tests

Updating Test Files

Test files change along with the Blender source code. make update will update tests to the latest version if you have downloaded them once, together with the Blender source code.

cd ~/blender-git/blender
make update

Running Tests

make test runs all available tests. For fine control, use ctest directly.

ctest must be run from the build directory.

cd ~/blender-git/build

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:

ctest -C Release -R alembic

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.

...
Test  #5: bf_blenkernel_tests
...

Then run the test with verbose output:

ctest -R bf_blenkernel_tests -V

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

tests/data is a submodule, and making changes there requires some extra steps. These are instructions for the main branch. For doing this in a release branch, see here.

Ensure submodules are up to date.

make update

Commit test files to the main branch of the test data repository.

cd tests/data
git checkout main
.. make any changes ..
git commit testfile1 testfile2

Commit changes in the Blender repository, including the updated tests/data submodule hash.

cd ../..
git commit sourcefile1 sourcefile2 tests/data

Check everything is ok, and push to both repositories.

cd tests/data
git push origin main
cd ../..
git push origin main