Layered Configuration System

ROAST uses a hierarchical or layered configuration system that is based on the open source library python-configuration.

This allows for configuration to be defined through a single file with key/value pairs or through a hierarchical template-based approach. In the template-based approach, a master configuration is established with interpolation expressions (placeholders) to be replaced with the corresponding value established in another configuration file through a process called string interpolation.

Configuration files must be named conf and can be written in a number of format types including:

Python (conf.py)
YAML (conf.yaml)
TOML (conf.toml)
JSON (conf.json)
INI (conf.ini)

Single File

In the single file approach, configuration can be defined through a file (conf.py).

var = "my_string"

Template-Based (Heirarchical)

In the template-based approach, a variable can be defined with its value to be substituted with another variable’s value. The top-level configuation file (conf.py):

var = {string_var}

At the test specific level, the variable and its value can be defined for a specific test or category of tests. The test specific configuration file (specific/conf.py):

string_var = "my_string"

When both files are loaded in the library, the test specific configuration file is “layered” on top of the template. The Python functionality behind this is str.format.

Warning

For Python configuration files, string interpolation is only supported in iterables.

Dot-Based Variables

Dot-based variables can be created from configuration files.

Python

A separator of __ is used to represent a .. For example:

aa__bb__cc = 1

would result in the configuration

{
    'aa.bb.c': 1,
}

An alternative is to use python-box. For example:

from box import Box
aa = Box(default_box=True)
aa.bb.cc = 1

del Box

Note

If this method is used, the last statement of del Box should be included. Otherwise, a key/value pair of “Box” and a Box class object will appear in the configuration.

Warning

String interpolation is only supported in iterables and not dictionaries.

Other Formats

With other formats, if heirarchy is part of the specification, dot-based variables will be created. For example, a TOML configuration:

[section]
var = "mystring"

would result in the configuration

{
    'section.var': 'mystring'
}

Accessing Configuration Values

When creating a configuration, the ConfigurationSet object that is returned can be accessed like a dictionary. If the configuration is assigned to conf, the value of var can be obtained using:

conf.get("var")
conf["var"]
conf.var

Similarly, dot-based variable values can be obtained using:

conf.get("section.var")
conf["section.var"]
conf.section.var