Tools/Tests/Setup

= Automated Tests =

Blender uses the CMake testing framework to run Python and GTest tests. Only part of Blender's code base is covered, developers are highly encouraged to add more tests.

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.

Downloading Test Files
Additional binary test files are needed for running the Blender tests. These are available through an SVN repository, separate from the Blender source repository.

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

To download the test files manually:

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.

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:

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.

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.

Inspection
Render and OpenGL drawing tests produce a HTML file to show the result of running regression tests, comparing renders and screenshots against a reference image. These can be found at:

Adding or Updating Tests
When adding a new test, or when there are benign test failures due to intentional changes, the reference images can be created or updated as follows:

After this all the tests should pass, and .blend files and references images can be committed.

Cycles GPU
For testing Cycles GPU rendering, `CYCLES_TEST_DEVICES` in the CMake configuration is a list of devices to test. By default it is only `CPU`, but `CUDA`, `OPTIX` and `HIP` can be added.

Eevee and Workbench
`WITH_OPENGL_RENDER_TESTS` enables Eevee and workbench tests, which are currently disabled by default due to different outputs of different GPUs. They render the same .blend files as Cycles.

Modifier Tests
Similar to render tests, modifier tests compare the output to a reference mesh. Updating the reference mesh for new test or on changes is done in the same way: