Configure Balder

Balder is built to be highly customizable. You can limit the collection for different setups or scenarios, configure it through the global balderglob.py file, and even create your own plugins.

Console arguments

Balder offers many different command-line arguments. You can get an overview by running:

$ balder --help

Changing the working directory

Normally, Balder assumes that your current directory is the working directory. If you want to change that, you can use the command-line option --working-dir:

$ balder --working-dir <relative/absolute path to working director>

Limit the collected scenarios/setups

Balder also allows you to limit the collection of scenarios and setups by using the CLI flags --only-with-scenario or --only-with-setup. You can provide fixed strings for the path, but you can also use * to match any characters of a file or directory name or ** to match all directories and / or subdirectories.

The following command will consider all scenario files that have the filename scenario_one.py, regardless of their location:

$ balder --only-with-scenario **/scenario_one.py

The following example will collect all setups located in the relative directory setups or its subdirectories with the filename setup_example.py:

$ balder --only-with-setup setups/**/setup_example.py

Of course you can combine these both options:

$ balder --only-with-scenario scenarios/login/** --only-with-setup setups/office1/*

BalderSettings object

You can specify different settings in a BalderSetting class in your balderglob.py file. For this you have to create a new class inside the balderglob.py file, that inherits from BalderSetting.

You can specify various settings by defining a class in your balderglob.py file that inherits from BalderSetting. To do this, simply create a new class inside the balderglob.py file and have it extend the BalderSetting base class.

# file `balderglob.py`
import balder
...

class MySettings(balder.BalderSetting):
    ...
    used_global_connection_tree = "my-own-tree"
    ...

The following overview lists all the settings available in the BalderSetting class:

class balder.BalderSettings

This class can be overwritten to manipulate the default settings for the balder test system. You can overwrite these settings by defining a subclass in your balderglob.py.

force_covered_by_duplicates = False

specifies that the test run should include duplicated tests that are declared as @covered_by another test method

used_global_connection_tree = ''

specifies the connection tree identifier that should be used as global identifier (”” is the default one)

BalderPlugin object

You can also influence Balder’s mechanisms by developing your own Balder plugins. To achieve this, Balder provides a global plugin manager that allows you to register plugins and interact with various callbacks. This enables you to customize and extend the overall behavior of the Balder system.

Note

The plugin engine is still under development. If you need any additional callbacks, feel free to create a GitHub Feature Request

If you want to create and use a Balder plugin, simply define a new subclass of BalderPlugin and include it in your global balderglob.py file:

# file `balderglob.py`
import balder
...

class MyPlugin(balder.BalderPlugin):

    ...

    def modify_collected_pyfiles(self, pyfiles):
        ..
        return filtered_pyfiles

    ...

If you only want to use a third-party plugin, you simply need to install it and then import the plugin class into your balderglob.py file:

# file `balderglob.py`
import balder
...
from my.third.party.plugin import MyPluginClass

The following section provides documentation for the BalderPlugin class:

class balder.BalderPlugin(session: BalderSession)

This is the balder plugin class. You can create your own plugin, by creating a subclass of it. With that you are able to overwrite the methods you want to use in your plugin.

addoption(argument_parser: argparse.ArgumentParser)

The callback will be executed while the ArgumentParser is being created.

Parameters:

argument_parser – the argument parser object

filter_executor_tree(executor_tree: ExecutorTree) → None

This callback will be executed before the ExecutorTree runs. It contains the current representation of the ExecutorTree, that will be executed in the next step. With this callback it is possible to manipulate the ExecutorTree. You have not to return something, the given executor_tree is a reference.

Parameters:

executor_tree – the reference to the main ExecutorTree object balder uses for this session

modify_collected_classes(scenarios: List[Type[Scenario]], setups: List[Type[Setup]]) → Tuple[List[Type[Scenario]], List[Type[Setup]]]

This callback will be executed after the Collector has collected the Scenario classes and the Setup classes.

Parameters:

• scenarios – all collected Scenario classes that are currently in the collected list

• setups – all collected Setup classes that are currently in the collected list

Returns:

a tuple of lists, where the first list is the new list with all Scenario classes, the second element is a list with all Setup classes

modify_collected_pyfiles(pyfiles: List[Path]) → List[Path]

This callback will be executed after the Collector has collected all python files that are inside the current working directory.

Note

Note that these files are not filtered yet. The list will contain every existing python file.

Parameters:

pyfiles – a list with all python filepaths

Returns:

the new list of all filepaths

session_finished(executor_tree: ExecutorTree | None)

This callback will be executed at the end of every session. The callback will run in a collect-only and resolve-only session too. Note, that the executor_tree argument is None in a collect-only session.

Parameters:

executor_tree – the reference to the main ExecutorTree object that balder uses for this session