Tools/GitBisectWithEventSimulation

= Automate Git Bisect with Event Simulation =

This page demonstrates how to find when bugs were introduced that can only be reproduced with interactive user actions.

Git Bisect Run
Git includes the ability to automate bisecting using a script, the typical workflow is as follows:

(replace: `a09c728`, `b6a0692` and `git_bisect.sh` with the values that apply to the issue you're investigating).

Once `git bisect run` is finished it will report the exact revision that introduced an error.

For more details on this see Fully automated bisecting with "git bisect run".

Simulating Events in Blender
Using a script often limits the kinds actions that can be automatically tested to things that can be performed in background mode (without a graphical window).

As Blender is a graphical application, there are times it can be useful to automate interface interactions such as activating menu items, pressing keys, interactive tools that require mouse motion... etc

Since Blender 2.81 it's possible to simulate events, and more recently a utility has been added to simplify the process of creating reproducible actions that can be automated without any user input.

Working Example
This is a practical example of how `git bisect run` was used with event simulation to find the cause of an error.

This can be used as a template, the actions argument will need to be changed for your specific use case.

The contents of `git_bisect.sh`:

These commands track down the commit that caused the error:

Hints

 * For a full list of options and other examples run:

`blender -b --python tests/python/bl_run_operators_event_simulate.py -- --help`


 * The example on this page relies on crashing for bisect to fail. If the issue you're investigating doesn't result in a crash, you will need another way to exit with a non-zero exit-code. This can be done using the `script.python_file_run` operator which will execute any Python script. This script needs to check for the error case and run `sys.exit(1)` for the failure state. The last action given should look like this:

`operator("script.python_file_run", filepath="/path/to/test_case.py")`


 * You may need to add `event(type="MOUSEMOVE", value="NOTHING")` as the last action, so the final state of the file is refreshed before exiting.


 * You may need to copy `tests/python/bl_run_operators_event_simulate.py` to a temporary location as bisecting to past revisions may remove functionality or the script it's self.


 * Menu search can be a quick way to to run an action: `menu("Add Curve Bezier")` Is the equivalent of pressing `F3`, typing in "Add Curve Bezier", then pressing `Enter`.


 * The `--keep-open` argument can be used to inspect the state of the file once event-simulation has finished, this is helpful when constructing actions and the state of the file is not what you expect. If you only want to keep blender open for a short period of time to see the result, adding dummy events is an alternative, e.g. `event(type="MOUSEMOVE", value="NOTHING", repeat=10_000)`


 * The `git_bisect.sh` script can be executed directly from the command-line, comment out the line that builds to quickly test the script.


 * To automatically run the script on file-save `inotifywait` (from inotify-tools) can be used. This allows for fast iterations when setting up command line arguments.