tcms_api.plugin_helpers module

class tcms_api.plugin_helpers.Backend(prefix='')[source]

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)[source]

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)[source]

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)[source]

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()[source]

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!

default_tester_id()[source]

Used internally and by default this is the user sending the API request. Plugins may want to override this.

Returns:User ID
Return type:int
external_plan_id()[source]

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()[source]

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)[source]

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)[source]

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()!

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

Return an Integration PlanType.

Warning

For internal use by .configure()!

Returns:tcms.testplans.models.PlanType PK
Return type:int
get_product_id(plan_id)[source]

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()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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!

test_case_get_or_create(summary)[source]

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)[source]

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
Returns:

None