Betelgeuse Configuration Module

Betelgeuse ships with a Default Configuration which defines custom fields, default values for some fields and some transformations.

You can configure Betelgeuse and provide your own custom fields, default values and transformations by providing the --config-module option. The value of --config-module should be in Python path syntax, e.g. mycustom.config_module. Note that the config module should be on the Python import search path.

Some custom fields are enumerations and expect some specific values. You can check the Custom fields’ values choices document for a reference of the values allowed for some of the fields. Not all field that are enumerations are listed on the document, only ones that are not supposed to be customized.

Note

Polarion allows each project to customize its own custom fields. If you find an error message while importing the test cases, first check if the value matches the case (choice values are casesensitive) and then check if you project has customized the enumeration for that field.

Tutorial

In this tutorial shows how to create a configuration module which adds two more custom fields by extending the default configuration custom fields list. In addition to that, it will provide a default value for each added custom field and a transformation function to do a final processing on the first added field.

Let’s start by creating a new file named my_custom_config.py. Then the custom configuration can be added.

To provide two additional custom fields it will be required to read the custom fields that ships with Betelgeuse and extend that with the new ones. The Betelgeuse’s default configuration can be accessed by importing the module betelgeuse.default_config. Add the following content to the my_custom_config.py file:

from betelgeuse import default_config

TESTCASE_CUSTOM_FIELDS = default_config.TESTCASE_CUSTOM_FIELDS + ['myfield1', 'myfield2']

By doing that and running betelgeuse --config-module my_custom_config test-case ... will make Betelgeuse include myfield1 and myfield2 to the generated XML if the test case docstring includes them.

The next step is to provide a default value for each added field. Betelgeuse will look for a attribute called DEFAULT_{field_name.upper()}_VALUE for each field and, if it is defined, the default value will then be evaluated. The default value can be a plain string or a callable, for the latter it will be called and a test case object will be passed, see Testcase objects for information of available attributes.

The myfield1 default value will be a plain string and the myfield2 default value will be a callable that will return the current date. Add the following lines to the my_custom_config.py file:

import datetime

def get_default_myfield2(testcase):
    """Return the current date as string."""
    return str(datetime.date.today())


DEFAULT_MYFIELD1_VALUE = 'custom value'
DEFAULT_MYFIELD2_VALUE = get_default_myfield2

With that, whenever the added fields are not specified on a test case docstring, the configured default values are going to be used.

In addition to custom values, a transformation function can be defined and that will be after assigning all the field values. A transformation function is useful, for example, to ensure lower or upper case on a value. Betelgeuse will look for an attribute called TRANSFORM_{field_name.upper()}_VALUE on the configuration module and if defined will call that function passing the value and the testcase object, see Testcase objects for information of available attributes.

Let’s define a transformation function that will prefix the myfield1 with the value of myfield2. Add the following lines to the my_custom_config.py file:

def prefix_with_myfield2_value(value, testcase):
    """Prefix the value with the value of myfield2 field."""
    return '{} {}'.format(testcase.fields['myfield2'], value)

TRANSFORM_MYFIELD1_VALUE = prefix_with_myfield2_value

With that the needed configuration is in place and Betelgeuse can be run:

betelgeuse --config-module betelgeuse_config test-case \
    sample_project/tests \
    PROJECT test-cases.xml

It will generate the test-cases.xml file and the added fields should be set with the default values configured. It will use the default values since the new fields are not defined on any of the sample_project test cases.

Starting at version 1.8.0, Betelgeuse supports also configuring Requirements fields, custom fields, fields default values and field transformation functions. All that work in the same fashion as for Test Cases. The difference is that the default value attribute will be looked by DEFAULT_REQUIREMENT_{field_name.upper()}_VALUE and TRANSFORM_REQUIREMENT_{field_name.upper()}_VALUE for the transformation function.

As an example, to define a default value for the priority field, you can do so by having the following on your config file DEFAULT_REQUIREMENT_PRIORITY_VALUE = "medium". If the default value is set as a callable, then it will be called passing the related Requirement object. Now, trying to specify a custom transformation function for the same field, could be done by having TRANSFORM_REQUIREMENT_PRIORITY_VALUE = my_custom_transform on the config. Note that transformation functions for Requirements’ field values will receive the related field value as first argument and the related Requirement object.

To pass the config module to the requirements command, run the following:

$ betelgeuse --config-module my_custom_config  requirement \
    --assignee assignee \
    --approver approver1 \
    --approver approver2 \
    sample_project/tests \
    PROJECT \
    betelgeuse-requirements.xml

Note

Passing the options --assignee and --approver to the command above will set the values to the related field before processing the configuration module. That means that the values will be overridden if the config module define a default value for those field. The value passed via command line will be available on the Requirement object passed to the default or transformation callables. For example to access the value of assignee, do the following requirement_obj.fields.get("assignee") (before overriding it).

Default Configuration

The default configuration includes all the fields and custom fields that Betelgeuse will look for when parsing the source code. It also provides the default values and transformations for some of the fields.

Note

The testcase fields are present on the configuration for information only. Each field requires specific processing, and because that, Betelgeuse won’t be able to process additional fields.

If you override the betelgeuse.default_config.TESTCASE_FIELDS and remove some of the fields they will not be processed and added to the generated XML. It is hightly recommended to avoid overriding or extending this configuration.

You can override or extend any of the defined information on your configuration module. Make sure to use valid values or your import will fail since Betelgeuse does not validate the values on Polarion.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
"""Default Betelgeuse configuration."""
from betelgeuse import parser


####################
# Helper functions #
####################

def _get_default_description(testcase):
    """Return the default value for description field."""
    return parser.parse_rst(testcase.docstring)


def _get_default_title(testcase):
    """Return the default value for title field."""
    return testcase.name


def _get_default_caseposneg(testcase):
    """Return the default value for caseposneg custom field."""
    return 'negative' if 'negative' in testcase.name.lower() else 'positive'


def _transform_to_lower(value, requirement_or_testcase):
    """Transform a field value to lower case.

    This is used to transform both Requirement and Test Case field values. The
    ``requirement_or_testcase`` argument is defined but not used.
    """
    return value.lower()


######################
# Requirement Fields #
######################

#: Default testcase fields
REQUIREMENT_FIELDS = (
    'approvers',
    'assignee',
    'categories',
    'description',
    'duedate',
    'id',
    'initialestimate',
    'plannedin',
    'priority',
    'severity',
    'status',
    'title',
)

#: Default requirement custom fields
REQUIREMENT_CUSTOM_FIELDS = (
    'reqtype',
)

###################
# Testcase Fields #
###################

#: Default testcase fields
TESTCASE_FIELDS = (
    'approvers',
    'assignee',
    'description',
    'duedate',
    'expectedresults',
    'id',
    'initialestimate',
    'parametrized',
    'requirement',
    'status',
    'steps',
    'title',
)

#: Default testcase custom fields
TESTCASE_CUSTOM_FIELDS = (
    'arch',
    'automation_script',
    'caseautomation',
    'casecomponent',
    'caseimportance',
    'caselevel',
    'caseposneg',
    'setup',
    'subcomponent',
    'subtype1',
    'subtype2',
    'tags',
    'tcmsarguments',
    'tcmsbug',
    'tcmscaseid',
    'tcmscategory',
    'tcmscomponent',
    'tcmsnotes',
    'tcmsplan',
    'tcmsreference',
    'tcmsrequirement',
    'tcmsscript',
    'tcmstag',
    'teardown',
    'testtier',
    'testtype',
    'upstream',
    'variant',
)

########################
# Default field values #
########################

# Test case fields default values
DEFAULT_CASEAUTOMATION_VALUE = 'automated'
DEFAULT_CASECOMPONENT_VALUE = '-'
DEFAULT_CASEIMPORTANCE_VALUE = 'medium'
DEFAULT_CASELEVEL_VALUE = 'component'
DEFAULT_CASEPOSNEG_VALUE = _get_default_caseposneg
DEFAULT_DESCRIPTION_VALUE = _get_default_description
DEFAULT_PARAMETRIZED_VALUE = 'no'
DEFAULT_SUBTYPE1_VALUE = '-'
DEFAULT_TESTTYPE_VALUE = 'functional'
DEFAULT_TITLE_VALUE = _get_default_title
DEFAULT_UPSTREAM_VALUE = 'no'

# Requirement fields default values
DEFAULT_REQUIREMENT_PRIORITY_VALUE = 'high'
DEFAULT_REQUIREMENT_SEVERITY_VALUE = 'should_have'
DEFAULT_REQUIREMENT_STATUS_VALUE = 'approved'
DEFAULT_REQUIREMENT_REQTYPE_VALUE = 'functional'

####################################
# Value transformation definitions #
####################################

# Test case value transform
TRANSFORM_CASEAUTOMATION_VALUE = _transform_to_lower
TRANSFORM_CASECOMPONENT_VALUE = _transform_to_lower
TRANSFORM_CASEIMPORTANCE_VALUE = _transform_to_lower
TRANSFORM_CASELEVEL_VALUE = _transform_to_lower
TRANSFORM_CASEPOSNEG_VALUE = _transform_to_lower
TRANSFORM_PARAMETRIZED_VALUE = _transform_to_lower
TRANSFORM_SUBTYPE1_VALUE = _transform_to_lower
TRANSFORM_TESTTYPE_VALUE = _transform_to_lower
TRANSFORM_UPSTREAM_VALUE = _transform_to_lower

# Requirement value transform
TRANSFORM_REQUIREMENT_PRIORITY_VALUE = _transform_to_lower
TRANSFORM_REQUIREMENT_SEVERITY_VALUE = _transform_to_lower
TRANSFORM_REQUIREMENT_STATUS_VALUE = _transform_to_lower
TRANSFORM_REQUIREMENT_REQTYPE_VALUE = _transform_to_lower

Rquirement objects

Testcase objects