tcms_api.plugin_helpers module

class tcms_api.plugin_helpers.Backend(prefix='', verbose=False)

Bases: object

Facilitates RPC communications with the backend and implements behavior described at: http://kiwitcms.org/blog/atodorov/2018/11/05/test-runner-plugin-specification/

This class is intended to be used by Kiwi TCMS plugins implemented in Python. The plugin will call:

backend = Backend()
backend.configure()

... parse test results ...

test_case_id, _ = backend.test_case_get_or_create(<description>)
backend.add_test_case_to_plan(test_case_id, backend.plan_id)
test_executions = backend.add_test_case_to_run(test_case_id,
                                               backend.run_id)
for execution in test_executions:
    backend.update_test_execution(execution['id'],
                                  <status_id>,
                                  <comment>)

Parameters:prefix (str) –

Prefix which will be added to TestPlan.name and TestRun.summary

New in version 5.2.

add_comment(test_execution_id, comment)

Add comment string to TestExecution without changing the status

Important

Test runner plugins must call this method!

Parameters:

• test_execution_id (int) – tcms.testruns.models.TestExecution PK
• comment (str) – the string to add as a comment

Returns:

None

add_test_case_to_plan(case_id, plan_id)

Add a TestCase to a TestPlan if it is not already there!

Important

Test runner plugins must call this method!

Parameters:

• case_id (int) – tcms.testcases.models.TestCase PK
• plan_id (int) – tcms.testplans.models.TestPlan PK

Returns:

None

add_test_case_to_run(case_id, run_id)

Add a TestCase to a TestRun if it is not already there!

Important

Test runner plugins must call this method!

Parameters:

• case_id (int) – tcms.testcases.models.TestCase PK
• run_id (int) – tcms.testruns.models.TestRun PK

Returns:

List of serialized tcms.testruns.models.TestExecution objects

Return type:

list(dict)

configure()

This method is reading all the configs from the environment and will create necessary TestPlan and TestRun containers!

One of the main reasons for it is that tcms_api.tcms_api.TCMS.exec will try to connect immediately to Kiwi TCMS!

Important

Test runner plugins must call this method after initializing the backend object and before calling any of the other methods!

created_by_text

default_tester_id

Used internally and by default this is the user sending the API request. Use $TCMS_DEFAULT_TESTER_ID to override!

Plugins may want to override this.

Returns:User ID Return type:int

external_plan_id()

Allows the user to specify $TCMS_PLAN_ID to point to an existing TestPlan where new runs will be added!

Warning

Does not check if the specified TP exists!

Returns:tcms.testplans.models.TestPlan PK or 0 Return type:int

finish_test_run()

Important

Test runner plugins may call this method!

May be called at the end when there are no more test executions to be sent to Kiwi TCMS. Default implementation will update TR.stop_date.

Returns:None

get_build_id(version_id)

Return a tcms.management.models.Build (PK, name).

Warning

For internal use by .configure()!

Parameters:version_id (int) – tcms.management.models.Version PK for which to look for Build Returns:(build_id, build_name) Return type:tuple(int, str)

Order of precedence:

• use $TCMS_BUILD as Build.name if specified, otherwise
• use $TRAVIS_BUILD_NUMBER as Build.name if specified, otherwise
• use $BUILD_NUMBER as Build.name if specified

If Build doesn’t exist in the database it will be created with the specified version_id!

get_plan_id(run_id)

If a TestRun with PK run_id exists then return the TestPlan to which this TestRun is assigned, otherwise create new TestPlan with Product and Version specified by environment variables.

Warning

For internal use by .configure()!

If TCMS_PARENT_PLAN environment variable is specified and a new TestPlan is created then it will be created as a child TP.

New in version 11.2.

Parameters:run_id (int) – tcms.testruns.models.TestRun PK Returns:tcms.testplans.models.TestPlan PK Return type:int

get_plan_type_id()

Return an Integration PlanType.

Warning

For internal use by .configure()!

Returns:tcms.testplans.models.PlanType PK Return type:int

get_product_id(plan_id)

Return a tcms.management.models.Product PK.

Warning

For internal use by .configure()!

Parameters:plan_id (int) – tcms.testplans.models.TestPlan PK Return type:int

Order of precedence:

• plan_id is specified, then use TestPlan.product, otherwise
• use $TCMS_PRODUCT as Product.name if specified, otherwise
• use $TRAVIS_REPO_SLUG as Product.name if specified, otherwise
• use $JOB_NAME as Product.name if specified

If Product doesn’t exist in the database it will be created with the first tcms.management.models.Classification found!

get_run_id()

If $TCMS_RUN_ID is specified then assume the caller knows what they are doing and try to add test results to that TestRun. Otherwise will create a TestPlan and TestRun in which to record the results!

Warning

For internal use by .configure()!

Returns:tcms.testruns.models.TestRun PK Return type:int

get_status_id(name)

Get the PK of tcms.testruns.models.TestExecutionStatus matching the test execution status name or fallback based on weight.

Important

Test runner plugins must call this method like so:

id = backend.get_status_id('FAILED')

Parameters:name (str) – tcms.testruns.models.TestExecutionStatus name Return type:int

get_status_id_fallback(name)

Get status based on weight if name not found

Parameters:name (str) – tcms.testruns.models.TestExecutionStatus name Return type:int

get_statuses_by_weight(lookup_condition)

Get a list of statuses based on lookup condition.

Parameters:lookup_condition (dict) – tcms.testruns.models.TestExecutionStatus lookup condition Return type:list

get_version_id(product_id)

Return a tcms.management.models.Version (PK, name).

Warning

For internal use by .configure()!

Parameters:product_id (int) – tcms.management.models.Product PK for which to look for Version Returns:(version_id, version_value) Return type:tuple(int, str)

Order of precedence:

• use $TCMS_PRODUCT_VERSION as Version.value if specified, or
• use $TRAVIS_COMMIT as Version.value if specified, otherwise
• use $TRAVIS_PULL_REQUEST_SHA as Version.value if specified, otherwise
• use $GIT_COMMIT as Version.value if specified

If Version doesn’t exist in the database it will be created with the specified product_id!

log_info(was_created, obj_prefix, obj_id)

name = 'tcms_api.plugin_helpers.Backend'

prefix

Prefix may be overriden via TCMS_PREFIX environment variable.

New in version 11.2.

test_case_get_or_create(summary)

Search for a TestCase with the specified summary and Product. If it doesn’t exist in the database it will be created!

Important

Test runner plugins must call this method!

Parameters:summary (str) – A TestCase summary Returns:Serialized tcms.testcase.models.TestCase and boolean flag to indicate if the TestCase has just been created! Return type:(dict, bool)

update_test_execution(test_execution_id, status_id, comment=None, start_date=None, stop_date=None)

Update TestExecution with a status and comment.

Important

Test runner plugins must call this method!

Parameters:

• test_execution_id (int) – tcms.testruns.models.TestExecution PK
• status_id (int) – tcms.testruns.models.TestExecutionStatus PK, for example the ID for PASSED, FAILED, etc.
• comment (str) – the string to add as a comment, defaults to None
• start_date (datetime) – when execution began, default None
• stop_date (datetime) – when execution completed, default None

Returns:

None

version = '12.2'