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 |