Authentication

tcms.xmlrpc.api.auth.login(request, credential)

Login into Nitrate

Parameters

credential (dict) – a mapping containing username and password.

Returns

Session ID

Return type

str

Raises

PermissionDenied – if either username or password is incorrect.

Example:

>>> Auth.login({'username': 'foo', 'password': 'bar'})
tcms.xmlrpc.api.auth.login_krbv(request)

Login into the Nitrate deployed with mod_auth_kerb

Returns

Session ID.

Return type

str

Example:

$ kinit
Password for username@example.com:

$ python
Auth.login_krbv()
tcms.xmlrpc.api.auth.logout(request)

Delete session information

TestBuild

tcms.xmlrpc.api.build.check_build(request, name, product)

Looks up and returns a build by name

Parameters
  • name (str) – name of the build.

  • product (int or str) – product_id of the product in the Database

Returns

matching TestBuild object hash or error if not found.

Return type

dict

Example:

# Get with product ID
Build.check_build('2008-02-25', 1)
# Get with product name
Build.check_build('2008-02-25', 'Product A')
tcms.xmlrpc.api.build.create(request, values)

Creates a new build object and stores it in the database

Parameters

values (dict) –

a mapping containing following items to create a TestBuild

  • product: (int or str) the product ID or name the new TestBuild should belong to.

  • name: (str) the build name.

  • description: (str) optional description.

  • is_active: (bool) optional. To indicate whether new build is active. Defaults to True.

Returns

a mapping serialized from newly created TestBuild.

Return type

dict

Example:

# Create build by product ID and set the build active.
Build.create({'product': 234, 'name': 'tcms_testing', 'description': 'None', 'is_active': 1})
# Create build by product name and set the build to inactive.
Build.create({'product': 'TCMS', 'name': 'tcms_testing 2', 'description': 'None', 'is_active': 0})
tcms.xmlrpc.api.build.get(request, build_id)

Used to load an existing build from the database.

Parameters

build_id (int) – the build ID.

Returns

A blessed Build object hash

Return type

list

Example:

Build.get(1234)
tcms.xmlrpc.api.build.get_caseruns(request, build_id)

Returns the list of case runs that this Build is used in.

Parameters

build_id (int) – build ID.

Returns

list of mappings of found case runs.

Example:

Build.get_caseruns(1234)
tcms.xmlrpc.api.build.get_runs(request, build_id)

Returns the list of runs that this Build is used in.

Parameters

build_id (int) – build ID.

Returns

list of test runs.

Return type

list

Example:

Build.get_runs(1234)
tcms.xmlrpc.api.build.lookup_id_by_name(request, name, product)

DEPRECATED - CONSIDERED HARMFUL Use Build.check_build instead

tcms.xmlrpc.api.build.lookup_name_by_id(request, build_id)

Lookup name by ID

Deprecated since version x.x: Use Build.get instead.

tcms.xmlrpc.api.build.update(request, build_id, values)

Description: Updates the fields of the selected build or builds.

Parameters
  • build_id (int) – the build ID.

  • values (dict) –

    a mapping containing build information to update.

    • product: (int or str) optional new product ID or name.

    • name: (str) optional new build name.

    • description: (str) optional new description.

    • is_active: (bool) set active or not optionally.

Returns

a mapping serialized from the updated TestBuild object.

Return type

dict

Example:

# Update name to 'foo' for build id 702
Build.update(702, {'name': 'foo'})
# Update status to inactive for build id 702
Build.update(702, {'is_active': 0})

Env

tcms.xmlrpc.api.env.filter_groups(request, query)

Performs a search and returns the resulting list of env groups.

Parameters

query (dict) –

mapping containing following criteria to find out envrionment groups.

  • id: (int) environment group ID.

  • name: (str) environment group name.

  • manager: ForeignKey: Auth.user

  • modified_by: ForeignKey: Auth.user

  • is_active: (bool)

  • property: ForeignKey: TCMSEnvProperty

Returns

list of mappings of found environment groups.

Return type

list

Example:

# Get all of env group name contains 'Desktop'
Env.filter_groups({'name__icontains': 'Desktop'})
tcms.xmlrpc.api.env.filter_properties(request, query)

Performs a search and returns the resulting list of env properties.

Parameters

query (dict) –

mapping containing following criteria to find out environment properties.

  • id: (int) environment property ID.

  • name: (str) property name.

  • is_active: (bool) whether to find active properties.

  • group: ForeignKey: TCMSEnvGroup

  • value: ForeignKey: TCMSEnvValues

Returns

Array: Matching env properties are retuned in a list of hashes.

Example:

# Get all of env properties name contains 'Desktop'
Env.filter_properties({'name__icontains': 'Desktop'})
tcms.xmlrpc.api.env.filter_values(request, query)

Performs a search and returns the resulting list of env properties.

Parameters

query (dict) –

mapping containing these criteria.

  • id: (int) ID of env value

  • value: (str)

  • is_active: (bool)

  • property: ForeignKey: TCMSEnvProperty

Returns

list of mappings containing found environment property values.

Return type

list

Example:

# Get all of env values name contains 'Desktop'
Env.filter_values({'name__icontains': 'Desktop'})
tcms.xmlrpc.api.env.get_properties(request, env_group_id=None, is_active=True)

Get the list of properties associated with this env group.

Parameters
  • env_group_id (int) – env_group_id of the env group in the Database Return all of properties when the argument is not specified.

  • is_active (bool) – If True, only include builds. Default: True.

Returns

list of found environment properties.

Return type

list

Example:

# Get all of properties
Env.get_properties()
# Get the properties in group 10
Env.get_properties(10)
tcms.xmlrpc.api.env.get_values(request, env_property_id=None, is_active=True)

Get the list of values associated with this env property.

Parameters
  • env_property_id (int) – environment property ID. If omitted, all environment property values will be returned.

  • is_active (bool) – indicate whether to get values from active properties. Default is True.

Returns

list of mappings containing found environment property values.

Return type

list

Example:

# Get all values from active environment properties
Env.get_values()
# Get the properties in group 10
Env.get_values(10)

Product

tcms.xmlrpc.api.product.add_component(request, product, name, initial_owner_id=None, initial_qa_contact_id=None)

Add component to selected product.

Parameters
  • product (int or str) – product ID or name.

  • name (str) – Component name

  • initial_owner_id (int) – optional initial owner ID. Defaults to current logged in user.

  • initial_qa_contact_id (int) – optional initial QA contact ID. Defaults to current logged in user.

Returns

a mapping of new Component.

Return type

dict

Example:

Product.add_component(71, 'JPBMM')
tcms.xmlrpc.api.product.add_version(request, values)

Add version to specified product.

Parameters

values (dict) –

a mapping containing these data

  • product: (int or str) product ID or name.

  • value: (str) the version value.

Returns

a mapping representing newly added Version.

Raises

ValueError – if fail to add version.

Example:

# Add version for specified product:
Product.add_version({'value': 'devel', 'product': 1})
{'product': 'Test Product', 'id': '1', 'value': 'devel', 'product_id': 1}
# Run it again:
Product.add_version({'value': 'devel', 'product': 1})
[['__all__', 'Version with this Product and Value already exists.']]
tcms.xmlrpc.api.product.check_category(request, name, product)

Looks up and returns a category by name.

Parameters
  • name (str) – name of the category.

  • product (int or str) – product ID or name.

Returns

a mapping representing the category.

Return type

dict

Example:

# Get with product ID
Product.check_category('Feature', 1)
# Get with product name
Product.check_category('Feature', 'product name')
tcms.xmlrpc.api.product.check_component(request, name, product)

Looks up and returns a component by name.

Parameters
  • name (str) – name of the category.

  • product – product ID or name.

Returns

a mapping representing a Component

Return type

dict

Example:

# Get with product ID
Product.check_component('acpi', 1)
# Get with product name
Product.check_component('acpi', 'Product A')
tcms.xmlrpc.api.product.check_product(request, name)

Looks up and returns a validated product.

Parameters

name (int or str) – product ID or name.

Returns

a mapping representing the Product.

Return type

dict

Example:

# Get with product ID
Product.check_product(1)
# Get with product name
Product.check_product('Product A')
tcms.xmlrpc.api.product.filter(request, query)

Performs a search and returns the resulting list of products.

Parameters

query (dict) –

a mapping containing following criteria.

  • id: (int) product id.

  • name: (str) product name.

  • classification: ForeignKey: Classification.

  • description: (str) description.

Returns

a mapping representing a Product.

Return type

dict

Example:

# Get all of product named 'product name'
Product.filter({'name': 'product name'})
tcms.xmlrpc.api.product.filter_categories(request, query)

Performs a search and returns the resulting list of categories.

Parameters

query (dict) –

a mapping containing following criteria.

  • id: (int) category ID.

  • name: (str) category name.

  • product: ForeignKey: Product.

  • description: (str) category description.

Returns

a mapping representing found category.

Return type

dict

Example:

# Get all of categories named like 'libvirt'
Product.filter_categories({'name__icontains': 'regression'})
# Get all of categories named in product 'product name'
Product.filter_categories({'product__name': 'product name'})
tcms.xmlrpc.api.product.filter_components(request, query)

Performs a search and returns the resulting list of components.

Parameters

query (dict) –

a mapping containing following criteria.

  • id: (int) product ID.

  • name: (str) component name.

  • product: ForeignKey: Product.

  • initial_owner: ForeignKey: Auth.User.

  • initial_qa_contact: ForeignKey: Auth.User.

  • description str: component description.

Returns

a mapping of found Component.

Return type

dict

Example:

# Get all of components named like 'libvirt'
Product.filter_components({'name__icontains': 'libvirt'})
# Get all of components named in product 'product name'
Product.filter_components({'product__name': 'product name'})
tcms.xmlrpc.api.product.filter_versions(request, query)

Performs a search and returns the resulting list of versions.

Parameters

query (dict) –

a mapping containing following criteria.

  • id: (int) ID of product

  • value: (str) version value.

  • product: ForeignKey: Product.

Returns

a list of mappings of Version.

Return type

list

Example:

# Get all of versions named like '2.4.0-SNAPSHOT'
Product.filter_versions({'value__icontains': '2.4.0-SNAPSHOT'})
# Get all of filter_versions named in product 'product name'
Product.filter_versions({'product__name': 'product name'})
tcms.xmlrpc.api.product.get(request, id)

Used to load an existing product from the database.

Parameters

id (int) – product ID.

Returns

a mapping representing found product.

Return type

Product.

Example:

Product.get(61)
tcms.xmlrpc.api.product.get_builds(request, product, is_active=True)

Get the list of builds associated with this product.

Parameters
  • product (int or str) – product ID or name.

  • is_active (bool) – if True, only return active builds. Otherwise, inactive builds will be returned.

Returns

a list of mappings of TestBuild.

Return type

list

Example:

# Get with product id including all builds
Product.get_builds(1)
# Get with product name excluding all inactive builds
Product.get_builds('product name', 0)
tcms.xmlrpc.api.product.get_cases(request, product)

Get the list of cases associated with this product.

Parameters

product (int or str) – product ID or name.

Returns

a list of mappings of TestCase.

Example:

# Get with product id
Product.get_cases(61)
# Get with product name
Product.get_cases('product name')
tcms.xmlrpc.api.product.get_categories(request, product)

Get the list of categories associated with this product.

Parameters

product (int or str) – product ID or name.

Returns

a list of mappings of TestCaseCategory.

Return type

list

Example:

# Get with product id Product.get_categories(61) # Get with product name Product.get_categories(‘product name’)

tcms.xmlrpc.api.product.get_category(request, id)

Get the category matching the given id.

Parameters

id (int) – category ID.

Returns

a mapping representing found TestCaseCategory.

Return type

dict

Example:

Product.get_category(11)
tcms.xmlrpc.api.product.get_component(request, id)

Get the component matching the given id.

Parameters

id (int) – component ID.

Returns

a mapping representing found Component.

Return type

dict

Example:

Product.get_component(11)
tcms.xmlrpc.api.product.get_components(request, product)

Get the list of components associated with this product.

Parameters

product (int or str) – product ID or name.

Returns

a list of mappings of Component.

Return type

list

Example:

# Get with product id
Product.get_components(61)
# Get with product name
Product.get_components('product name')
tcms.xmlrpc.api.product.get_environments(request, product)

FIXME: NOT IMPLEMENTED

tcms.xmlrpc.api.product.get_milestones(request, product)

FIXME: NOT IMPLEMENTED

tcms.xmlrpc.api.product.get_plans(request, product)

Get the list of plans associated with this product.

Parameters

product (int or str) – product ID or name.

Returns

a list of mappings of TestPlan.

Return type

list

Example:

# Get with product id
Product.get_plans(61)
# Get with product name
Product.get_plans('product name')
tcms.xmlrpc.api.product.get_runs(request, product)

Get the list of runs associated with this product.

Params product

product ID or name.

Returns

a list of mappings of test runs.

Return type

list

Example:

# Get with product id
Product.get_runs(1)
# Get with product name
Product.get_runs('product name')
tcms.xmlrpc.api.product.get_tag(request, id)

Get the list of tags.

Parameters

id (int) – tag ID.

Returns

a mapping representing found TestTag.

Return type

dict

Example:

Product.get_tag(1)
tcms.xmlrpc.api.product.get_versions(request, product)

Get the list of versions associated with this product.

Parameters

product (int or str) – product ID or name.

Returns

a list of mappings of versions.

Return type

list

Example:

# Get with product id
Product.get_versions(1)
# Get with product name
Product.get_versions('product name')
tcms.xmlrpc.api.product.lookup_id_by_name(request, name)

DEPRECATED - CONSIDERED HARMFUL Use Product.check_product instead

tcms.xmlrpc.api.product.lookup_name_by_id(request, id)

DEPRECATED Use Product.get instead

tcms.xmlrpc.api.product.update_component(request, component_id, values)

Update component to selected product.

Parameters
  • component_id (int) – component ID.

  • values (dict) –

    a mapping containing these new data.

    • name: (str) optional.

    • initial_owner_id: (int) optional.

    • initial_qa_contact_id: (int) optional.

Returns

a mapping representing updated Component.

Return type

dict

Example:

Product.update_component(1, {'name': 'NewName'})

Tag

tcms.xmlrpc.api.tag.get_tags(request, values)

Get tags by ID or name.

Parameters

values (dict) –

a mapping containing these criteria.

  • ids: (list[int]) list of tag IDs.

  • names: (list[str]) list of names.

Returns

a list of mappings of TestTag.

Return type

list

Example:

Tag.get_tags({'ids': [121, 123]})

TestPlan

tcms.xmlrpc.api.testplan.add_component(request, plan_ids, component_ids)

Adds one or more components to the selected test plan.

Parameters
  • plan_ids (int, str or list) – give one or more plan IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a plan ID.

  • component_ids (int, str or list) – give one or more component IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a component ID.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Example:

# Add component id 54321 to plan 1234
TestPlan.add_component(1234, 54321)
# Add component ids list [1234, 5678] to plan list [56789, 12345]
TestPlan.add_component([56789, 12345], [1234, 5678])
# Add component ids list '1234, 5678' to plan list '56789, 12345' with String
TestPlan.add_component('56789, 12345', '1234, 5678')
tcms.xmlrpc.api.testplan.add_tag(request, plan_ids, tags)

Add one or more tags to the selected test plans.

Parameters
  • plan_ids (int, str or list) – give one or more plan IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a plan ID.

  • tags (str or list[str]) – a tag name or list of tag names to be added.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Example:

# Add tag 'foobar' to plan 1
TestPlan.add_tag(1, 'foobar')
# Add tag list ['foo', 'bar'] to plan list [1, 2]
TestPlan.add_tag([1, 2], ['foo', 'bar'])
# Add tag list ['foo', 'bar'] to plan list [1, 2] with String
TestPlan.add_tag('1, 2', 'foo, bar')
tcms.xmlrpc.api.testplan.check_plan_type(request, name)

Get a plan type by name

Parameters

name (str) – the plan type.

Returns

a mapping of found TestPlanType.

Return type

dict

Example:

TestPlan.check_plan_type('regression')
tcms.xmlrpc.api.testplan.create(request, values)

Creates a new Test Plan object and stores it in the database.

Parameters

values (dict) –

a mapping containing these plan data:

  • product: (int) Required ID of product

  • name: (str) Required

  • type: (int) Required ID of plan type

  • product_version: (int) Required version ID.

  • default_product_version: (int) optional version ID.

  • text: (str) Required Plan documents, HTML acceptable.

  • parent: (int) optional Parent plan ID

  • is_active: bool optional 0: Archived 1: Active (Default 0)

Returns

a mapping of newly created TestPlan.

Return type

dict

Example:

# Minimal test case parameters
values = {
    'product': 1,
    'name': 'Testplan foobar',
    'type': 1,
    'parent_id': 2,
    'default_product_version': 1,
    'text':'Testing TCMS',
}
TestPlan.create(values)
tcms.xmlrpc.api.testplan.filter(request, values={})

Performs a search and returns the resulting list of test plans.

Parameters

values (dict) –

a mapping containing these criteira.

  • author: ForeignKey: Auth.User

  • attachments: ForeignKey: Attachment

  • case: ForeignKey: TestCase

  • create_date: DateTime

  • env_group: ForeignKey: Environment Group

  • name: (str)

  • plan_id: (int)

  • product: ForeignKey: Product

  • product_version: ForeignKey: Version

  • tag: ForeignKey: TestTag

  • text: ForeignKey: Test Plan Text

  • type: ForeignKey: Test Plan Type

Returns

list of mappings of found TestPlan.

Return type

list[dict]

Example:

# Get all of plans contain 'TCMS' in name
TestPlan.filter({'name__icontain': 'TCMS'})
# Get all of plans create by xkuang
TestPlan.filter({'author__username': 'xkuang'})
# Get all of plans the author name starts with x
TestPlan.filter({'author__username__startswith': 'x'})
# Get plans contain the case ID 1, 2, 3
TestPlan.filter({'case__case_id__in': [1, 2, 3]})
tcms.xmlrpc.api.testplan.filter_count(request, values={})

Performs a search and returns the resulting count of plans.

Parameters

values (dict) – a mapping containing criteria. See also TestPlan.filter.

Returns

total matching plans.

Return type

int

See also

See example of TestPlan.filter.

tcms.xmlrpc.api.testplan.get(request, plan_id)

Used to load an existing test plan from the database.

Parameters

plan_id (int) – plan ID.

Returns

a mapping of found TestPlan.

Return type

dict

Example:

TestPlan.get(1)
tcms.xmlrpc.api.testplan.get_all_cases_tags(request, plan_id)

Get the list of tags attached to this plan’s testcases.

Parameters

plan_id (int) – plan ID.

Returns

list of mappings of found TestTag.

Return type

list[dict]

Example:

TestPlan.get_all_cases_tags(137)
tcms.xmlrpc.api.testplan.get_change_history(request, plan_id)

Get the list of changes to the fields of this plan.

Parameters

plan_id (int) – plan ID.

Returns

a list of mappings of found history.

Warning

NOT IMPLEMENTED - History is different than before.

tcms.xmlrpc.api.testplan.get_components(request, plan_id)

Get the list of components attached to this plan.

Parameters

plan_id (int) – plan ID.

Returns

list of mappings of found Component.

Return type

list[dict]

Example:

TestPlan.get_components(1)
tcms.xmlrpc.api.testplan.get_env_groups(request, plan_id)

Get the list of env groups to the fields of this plan.

Parameters

plan_id (int) – plan ID.

Returns

list of mappings of found TCMSEnvGroup.

Return type

list[dict]

tcms.xmlrpc.api.testplan.get_plan_type(request, id)

Get plan type

Parameters

id (int) – plan ID.

Returns

a mapping of found TestPlanType.

Return type

dict

Example:

TestPlan.get_plan_type(1)
tcms.xmlrpc.api.testplan.get_product(request, plan_id)

Get the Product the plan is assiciated with.

Parameters

plan_id (int) – plan ID.

Returns

a mapping of found Product.

Return type

dict

Example:

TestPlan.get_product(1)
tcms.xmlrpc.api.testplan.get_tags(request, plan_id)

Get the list of tags attached to this plan.

Parameters

plan_id (int) – plan ID.

Returns

list of mappings of found TestTag.

Return type

list[dict]

Example:

TestPlan.get_tags(1)
tcms.xmlrpc.api.testplan.get_test_cases(request, plan_id)

Get the list of cases that this plan is linked to.

Parameters

plan_id (int) – plan ID.

Returns

list of mappings of found TestCase.

Return type

list[dict]

Example:

TestPlan.get_test_cases(1)
tcms.xmlrpc.api.testplan.get_test_runs(request, plan_id)

Get the list of runs in this plan.

Parameters

plan_id (int) – plan ID.

Returns

list of mappings of found TestRun.

Return type

list[dict]

Example:

TestPlan.get_test_runs(1)
tcms.xmlrpc.api.testplan.get_text(request, plan_id, plan_text_version=None)

The plan document for a given test plan.

Parameters
  • plan_id (int) – plan ID.

  • text (str) – the content to be added. Could contain HTML.

  • plan_text_version (int) – optional text version. Defaults to the latest if omitted.

Returns

a mapping of text.

Return type

dict

Example:

# Get all latest case text
TestPlan.get_text(1)
# Get all case text with version 4
TestPlan.get_text(1, 4)
tcms.xmlrpc.api.testplan.import_case_via_XML(request, plan_id, xml_content)

Add cases to plan via XML file

Parameters
  • plan_id (int) – plan ID.

  • xml_content (str) – content of XML document containing cases.

Returns

a simple string to indicate a successful import.

Example:

fb = open('tcms.xml', 'rb')
TestPlan.import_case_via_XML(1, fb.read())
tcms.xmlrpc.api.testplan.lookup_type_id_by_name(request, name)

DEPRECATED - CONSIDERED HARMFUL Use TestPlan.check_plan_type instead

tcms.xmlrpc.api.testplan.lookup_type_name_by_id(request, id)

DEPRECATED - CONSIDERED HARMFUL Use TestPlan.get_plan_type instead

tcms.xmlrpc.api.testplan.remove_component(request, plan_ids, component_ids)

Removes selected component from the selected test plan.

Parameters
  • plan_ids (int, str or list) – give one or more plan IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a plan ID.

  • component_ids (int, str or list) – give one or more component IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a component ID.

Returns

Empty on success.

Example:

# Remove component id 2 from plan 1
TestPlan.remove_component(1, 2)
# Remove component ids list [3, 4] from plan list [1, 2]
TestPlan.remove_component([1, 2], [3, 4])
# Remove component ids list '3, 4' from plan list '1, 2' with String
TestPlan.remove_component('1, 2', '3, 4')
tcms.xmlrpc.api.testplan.remove_tag(request, plan_ids, tags)

Remove a tag from a plan.

Parameters
  • plan_ids (int, str or list) – give one or more plan IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a plan ID.

  • tags (str or list[str]) – a tag name or a list of tag names to be removed.

Returns

Empty on success.

Example:

# Remove tag 'foo' from plan 1
TestPlan.remove_tag(1, 'foo')
# Remove tag 'foo' and 'bar' from plan list [1, 2]
TestPlan.remove_tag([1, 2], ['foo', 'bar'])
# Remove tag 'foo' and 'bar' from plan list '1, 2' with String
TestPlan.remove_tag('1, 2', 'foo, bar')
tcms.xmlrpc.api.testplan.store_text(request, plan_id, text, author=None)

Update the document field of a plan.

Parameters
  • plan_id (int) – plan ID.

  • text (str) – the content to be added. Could contain HTML.

  • author (int) – optional user ID of author. Defaults to request.user if omitted.

Returns

a mapping of newly stored text.

Return type

dict

Example:

TestPlan.store_text(1, 'Plan Text', 2)
tcms.xmlrpc.api.testplan.update(request, plan_ids, values)

Updates the fields of the selected test plan.

Parameters
  • plan_ids (int, str or list) – give one or more plan IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a plan ID.

  • values (dict) –

    a mapping containing these plan data to update

    • product: (int) ID of product

    • name: (str)

    • type: (int) ID of plan type

    • product_version: (int) ID of version

    • default_product_version: (int) alternative version ID.

    • owner: (str)/(int) user_name/user_id

    • parent: (int) Parent plan ID

    • is_active: bool True/False

    • env_group: (int) New environment group ID

Returns

a mapping of updated TestPlan.

Return type

dict

Example:

# Update product to 7 for plan 1 and 2
TestPlan.update([1, 2], {'product': 7})

Deprecated since version x.y: default_product_version is deprecated and will be removed.

TestCase

tcms.xmlrpc.api.testcase.add_comment(request, case_ids, comment)

Adds comments to selected test cases.

Parameters
  • case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

  • comment (str) – the comment content to add.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occurred.

Example:

# Add comment 'foobar' to case 1
TestCase.add_comment(1, 'foobar')
# Add 'foobar' to cases list [1, 2]
TestCase.add_comment([1, 2], 'foobar')
# Add 'foobar' to cases list '1, 2' with String
TestCase.add_comment('1, 2', 'foobar')
tcms.xmlrpc.api.testcase.add_component(request, case_ids, component_ids)

Adds one or more components to the selected test cases.

Parameters
  • case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

  • component_ids (int, str or list) – give one or more component IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a component ID.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Example:

# Add component id 1 to case 1
TestCase.add_component(1, 1)
# Add component ids list [3, 4] to cases list [1, 2]
TestCase.add_component([1, 2], [3, 4])
# Add component ids list '3, 4' to cases list '1, 2' with String
TestCase.add_component('1, 2', '3, 4')
tcms.xmlrpc.api.testcase.add_tag(request, case_ids, tags)

Add one or more tags to the selected test cases.

Parameters
  • case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

  • tags (str or list) – tag name or a list of tag names to remove.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Example:

# Add tag 'foobar' to case 1
TestCase.add_tag(1, 'foobar')
# Add tag list ['foo', 'bar'] to cases list [1, 2]
TestCase.add_tag([1, 2], ['foo', 'bar'])
# Add tag list ['foo', 'bar'] to cases list [1, 2] with String
TestCase.add_tag('1, 2', 'foo, bar')
tcms.xmlrpc.api.testcase.add_to_run(request, case_ids, run_ids)

Add one or more cases to the selected test runs.

Parameters
  • case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

  • run_ids (int, str or list) – give one or more run IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a run ID.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Example:

# Add case 1 to run id 1
TestCase.add_to_run(1, 1)
# Add case ids list [1, 2] to run list [3, 4]
TestCase.add_to_run([1, 2], [3, 4])
# Add case ids list 1 and 2 to run list 3 and 4 with String
TestCase.add_to_run('1, 2', '3, 4')
tcms.xmlrpc.api.testcase.attach_issue(request, values)

Add one or more issues to the selected test cases.

Parameters

values (dict) –

mapping or list of mappings containing these bug information.

  • case: (int) Required. Case ID.

  • issue_key: (str) Required. issue key.

  • tracker: (int) Required. issue tracker ID.

  • summary: (str) optional issue’s summary.

  • description: (str) optional issue’s description.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Return type

list

Example:

values = {
    'case': 1,
    'issue_key': '1000',
    'tracker': 1,
    'summary': 'Testing TCMS',
    'description': 'Just foo and bar',
}
TestCase.attach_issue(values)

Changed in version 4.2: Some arguments passed via values are changed. case_id is changed to case, bug_id is changed to issue_key, bug_system_id is changed to tracker. Default issue tracker is not supported. So, if passed-in tracker does not exist, it will be treated as an error.

tcms.xmlrpc.api.testcase.calculate_average_estimated_time(request, case_ids)

Returns an average estimated time for cases.

Parameters

case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

Returns

Time in “HH:MM:SS” format.

Return type

str

Example:

TestCase.calculate_average_estimated_time([609, 610, 611])
tcms.xmlrpc.api.testcase.calculate_total_estimated_time(request, case_ids)

Returns an total estimated time for cases.

Parameters

case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

Returns

Time in “HH:MM:SS” format.

Return type

str

Example:

TestCase.calculate_total_estimated_time([609, 610, 611])
tcms.xmlrpc.api.testcase.check_case_status(request, name)

Looks up and returns a case status by name.

Parameters

name (str) – name of the case status.

Returns

a mapping representing found case status.

Return type

TestCaseStatus.

Example:

TestCase.check_case_status('proposed')
tcms.xmlrpc.api.testcase.check_priority(request, value)

Looks up and returns a priority by name.

Parameters

value (str) – name of the priority.

Returns

a mapping representing found priority.

Return type

Priority.

Example:

TestCase.check_priority('p1')
tcms.xmlrpc.api.testcase.create(request, values)

Creates a new Test Case object and stores it in the database.

Parameters

values

a mapping or list of mappings containing these case information for creation.

  • product: (int) Required ID of Product

  • category: (int) Required ID of Category

  • priority: (int) Required ID of Priority

  • summary: (str) Required

  • case_status: (int) optional ID of case status

  • plan Array/Str/Int optional ID or List of plan_ids

  • component: (int)/str optional ID of Priority

  • default_tester: (str) optional Login of tester

  • estimated_time: (str) optional 2h30m30s(recommend) or HH:MM:SS Format|

  • is_automated: (int) optional 0: Manual, 1: Auto, 2: Both

  • is_automated_proposed: (bool) optional Default 0

  • script: (str) optional

  • arguments: (str) optional

  • requirement: (str) optional

  • alias: (str) optional Must be unique

  • action: (str) optional

  • effect: (str) optional Expected Result

  • setup: (str) optional

  • breakdown: (str) optional

  • tag Array/str optional String Comma separated

  • bug Array/str optional String Comma separated

  • extra_link: (str) optional reference link

Returns

a mapping of newly created test case if a single case was created, or a list of mappings of created cases if more than one are created.

Return type

dict of list[dict]

Example:

# Minimal test case parameters
values = {
    'category': 1,
    'product': 1,
    'summary': 'Testing XML-RPC',
    'priority': 1,
}
TestCase.create(values)
tcms.xmlrpc.api.testcase.detach_issue(request, case_ids, issue_keys)

Remove one or more issues to the selected test cases.

Parameters
  • case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

  • issue_keys (int, str or list) – give one or more bug IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a bug ID.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Example:

# Remove issue key 1000 from case 1
TestCase.detach_issue(1, 1000)
# Remove issue keys list [1000, 1001] from cases list [1, 2]
TestCase.detach_issue([1, 2], [1000, 1001])
# Remove issue keys list '1000, 1001' from cases list '1, 2' with String
TestCase.detach_issue('1, 2', '1000, 1001')
tcms.xmlrpc.api.testcase.filter(request, query)

Performs a search and returns the resulting list of test cases.

Parameters

query (dict) –

a mapping containing these criteria.

  • author: A Bugzilla login (email address)

  • attachments: ForeignKey: Attachment

  • alias: (str)

  • case_id: (int)

  • case_status: ForeignKey: Case Stat

  • category: ForeignKey: Category

  • component: ForeignKey: Component

  • default_tester: ForeignKey: Auth.User

  • estimated_time: String: 2h30m30s(recommend) or HH:MM:SS

  • plan: ForeignKey: TestPlan

  • priority: ForeignKey: Priority

  • category__product: ForeignKey: Product

  • summary: (str)

  • tags: ForeignKey: Tags

  • create_date: Datetime

  • is_automated: 1: Only show current 0: show not current

  • script: (str)

Returns

list of mappings of found TestCase.

Return type

list

Example:

# Get all of cases contain 'TCMS' in summary
TestCase.filter({'summary__icontain': 'TCMS'})
# Get all of cases create by xkuang
TestCase.filter({'author__username': 'xkuang'})
# Get all of cases the author name starts with x
TestCase.filter({'author__username__startswith': 'x'})
# Get all of cases belong to the plan 1
TestCase.filter({'plan__plan_id': 1})
# Get all of cases belong to the plan create by xkuang
TestCase.filter({'plan__author__username': 'xkuang'})
# Get cases with ID 12345, 23456, 34567 - Here is only support array so far.
TestCase.filter({'case_id__in': [12345, 23456, 34567]})
tcms.xmlrpc.api.testcase.filter_count(request, values={})

Performs a search and returns the resulting count of cases.

Parameters

values (dict) – a mapping containing same criteria with TestCase.filter.

Returns

the number of matching cases.

Return type

int

See also

Examples of TestCase.filter.

tcms.xmlrpc.api.testcase.get(request, case_id)

Used to load an existing test case from the database.

Parameters

case_id (int or str) – case ID.

Returns

a mappings representing found test case.

Return type

dict

Example:

TestCase.get(1)
tcms.xmlrpc.api.testcase.get_case_run_history(request, case_id)

Get the list of case-runs for all runs this case appears in.

To limit this list by build or other attribute, see TestCaseRun.filter.

Parameters

case_id (int or str) – case ID.

Returns

list of mappings of case runs.

Example:

TestCase.get_case_run_history(1)

Warning

NOT IMPLEMENTED - Case run history is different than before

tcms.xmlrpc.api.testcase.get_case_status(request, id=None)

Get the case status matching the given id.

Parameters

id (int) – case status ID.

Returns

a mapping representing found TestCaseStatus.

Return type

dict

Example:

# Get all of case status
TestCase.get_case_status()
# Get case status by ID 1
TestCase.get_case_status(1)
tcms.xmlrpc.api.testcase.get_change_history(request, case_id)

Get the list of changes to the fields of this case.

Parameters

case_id (int or str) – case ID.

Returns

a list of mappings of history.

Example:

TestCase.get_change_history(12345)

Warning

NOT IMPLEMENTED - Case history is different than before

tcms.xmlrpc.api.testcase.get_components(request, case_id)

Get the list of components attached to this case.

Parameters

case_id (int or str) – case ID.

Returns

a list of mappings of Component.

Return type

list[dict]

Example:

TestCase.get_components(1)
tcms.xmlrpc.api.testcase.get_issue_tracker(request, id)

Used to load an existing test case issue trackers from the database.

Parameters

id (int or str) – issue tracker ID.

Returns

a mappings representing found IssueTracker.

Return type

dict

Example:

TestCase.get_issue_tracker(1)
tcms.xmlrpc.api.testcase.get_issues(request, case_ids)

Get the list of issues that are associated with this test case.

Parameters

case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

Returns

list of mappings of Issue.

Return type

list[dict]

Example:

# Get issues belonging to case 1
TestCase.get_issues(1)
# Get issues belonging to cases [1, 2]
TestCase.get_issues([1, 2])
# Get issues belonging to case 1 and 2 with string
TestCase.get_issues('1, 2')
tcms.xmlrpc.api.testcase.get_plans(request, case_id)

Get the list of plans that this case is linked to.

Parameters

case_id (int or str) – case ID.

Returns

a list of mappings of TestPlan.

Return type

list[dict]

Example:

TestCase.get_plans(1)
tcms.xmlrpc.api.testcase.get_priority(request, id)

Get the priority matching the given id.

Parameters

id (int) – priority ID.

Returns

a mapping representing found Priority.

Return type

dict

Example:

TestCase.get_priority(1)
tcms.xmlrpc.api.testcase.get_tags(request, case_id)

Get the list of tags attached to this case.

Parameters

case_id (int or str) – case ID.

Returns

a list of mappings of TestTag.

Return type

list[dict]

Example:

TestCase.get_tags(1)
tcms.xmlrpc.api.testcase.get_text(request, case_id, case_text_version=None)

Get the associated case’ Action, Expected Results, Setup, Breakdown for a given version

Parameters
  • case_id (int or str) – case ID.

  • case_text_version (int) – optional version of the text you want returned. Defaults to the latest, if omitted.

Returns

a mapping representing a case text.

Return type

dict

Example:

# Get all latest case text
TestCase.get_text(1)
# Get all case text with version 4
TestCase.get_text(1, 4)

“Link test cases to the given plan.

Parameters
  • case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

  • plan_ids (int, str or list) – give one or more plan IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a plan ID.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Return type

list or list[dict]

Example:

# Add case 1 to plan id 2
TestCase.link_plan(1, 2)
# Add case ids list [1, 2] to plan list [3, 4]
TestCase.link_plan([1, 2], [3, 4])
# Add case ids list 1 and 2 to plan list 3 and 4 with String
TestCase.link_plan('1, 2', '3, 4')
tcms.xmlrpc.api.testcase.lookup_category_id_by_name(request, name, product)

Lookup category ID by name

Deprecated since version x.y: Use Product.check_category instead.

tcms.xmlrpc.api.testcase.lookup_category_name_by_id(request, id)

Lookup category name by ID

Deprecated since version x.y: Use Product.get_category instead.

tcms.xmlrpc.api.testcase.lookup_priority_id_by_name(request, value)

Lookup priority ID by name

Deprecated since version x.y: Use TestCase.check_priority instead.

tcms.xmlrpc.api.testcase.lookup_priority_name_by_id(request, id)

Lookup priority name by ID

Deprecated since version x.y: Use TestCase.get_priority instead.

tcms.xmlrpc.api.testcase.lookup_status_id_by_name(request, name)

Lookup status ID by name

Deprecated since version x.y: Use TestCase.check_case_status instead.

tcms.xmlrpc.api.testcase.lookup_status_name_by_id(request, id)

Lookup status name by ID

Deprecated since version x.y: Use TestCase.get_case_status instead.

tcms.xmlrpc.api.testcase.notification_add_cc(request, case_ids, cc_list)

Add email addresses to the notification CC list of specific TestCases

Parameters
  • case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

  • cc_list (list) – list of email addresses to be added to the specified cases.

tcms.xmlrpc.api.testcase.notification_get_cc_list(request, case_ids)

Return whole CC list of each TestCase

Parameters

case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

Returns

a mapping from case ID to list of CC email addresses.

Return type

dict(str, list)

tcms.xmlrpc.api.testcase.notification_remove_cc(request, case_ids, cc_list)

Remove email addresses from the notification CC list of specific TestCases

Parameters
  • case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

  • cc_list (list) – list of email addresses to be removed from specified cases.

tcms.xmlrpc.api.testcase.remove_component(request, case_ids, component_ids)

Removes selected component from the selected test case.

Parameters
  • case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

  • component_ids – give one or more component IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a component ID.

Returns

a list which is emtpy on success.

Return type

list

Example:

# Remove component id 1 from case 1
TestCase.remove_component(1, 1)
# Remove component ids list [3, 4] from cases list [1, 2]
TestCase.remove_component([1, 2], [3, 4])
# Remove component ids list '3, 4' from cases list '1, 2' with String
TestCase.remove_component('1, 2', '3, 4')
tcms.xmlrpc.api.testcase.remove_tag(request, case_ids, tags)

Remove a tag from a case.

Parameters
  • case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

  • tags (str or list) – tag name or a list of tag names to remove.

Returns

a list which is emtpy on success.

Return type

list

Example:

# Remove tag 'foo' from case 1
TestCase.remove_tag(1, 'foo')
# Remove tag 'foo' and bar from cases list [1, 2]
TestCase.remove_tag([1, 2], ['foo', 'bar'])
# Remove tag 'foo' and 'bar' from cases list '1, 2' with String
TestCase.remove_tag('1, 2', 'foo, bar')
tcms.xmlrpc.api.testcase.store_text(request, case_id, action, effect='', setup='', breakdown='', author_id=None)

Update the large text fields of a case.

Parameters
  • case_id (int) – case ID.

  • action (str) – action text of specified case.

  • effect (str) – effect text of specified case. Defaults to empty string if omitted.

  • setup (str) – setup text of specified case. Defaults to empty string if omitted.

  • breakdown (str) – breakdown text of specified case. Defaults to empty string if omitted.

  • auth_id (int) – author’s user ID.

Returns

a mapping of newly added text of specified case.

Return type

dict

Example:

TestCase.store_text(1, 'Action')
TestCase.store_text(1, 'Action', 'Effect', 'Setup', 'Breakdown', 2)

Unlink a test case from the given plan. If only one plan is linked, this will delete the test case.

Parameters
  • case_id (int or str) – case ID.

  • plan_id (int) – plan ID from where to unlink the specified case.

Returns

a list of mappings of test plans that are still linked to the specified case. If there is no linked test plans, empty list will be returned.

Return type

list[dict]

Example:

# Unlink case 100 from plan 10
TestCase.unlink_plan(100, 10)
tcms.xmlrpc.api.testcase.update(request, case_ids, values)

Updates the fields of the selected case or cases.

$values - Hash of keys matching TestCase fields and the new values

to set each field to.

Parameters
  • case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

  • values (dict) –

    a mapping containing these case data to update.

    • case_status: (ini) optional

    • product: (ini) optional (Required if changes category)

    • category: (ini) optional

    • priority: (ini) optional

    • default_tester: (str or int) optional (str - user_name, int - user_id)

    • estimated_time: (str) optional (2h30m30s(recommend) or HH:MM:SS

    • is_automated: (ini) optional (0 - Manual, 1 - Auto, 2 - Both)

    • is_automated_proposed: (bool) optional

    • script: (str) optional

    • arguments: (str) optional

    • summary: (str) optional

    • requirement: (str) optional

    • alias: (str) optional

    • notes: (str) optional

    • extra_link: (str) optional (reference link)

Returns

a list of mappings of updated TestCase.

Return type

list(dict)

Example:

# Update alias to 'tcms' for case 1 and 2
TestCase.update([1, 2], {'alias': 'tcms'})

TestCasePlan

tcms.xmlrpc.api.testcaseplan.get(request, case_id, plan_id)

Used to load an existing test-case-plan from the database.

Parameters
  • case_id (int) – case ID.

  • plan_id (int) – plan ID.

Returns

a mapping of TestCasePlan.

Return type

dict

Example:

TestCasePlan.get(1, 2)
tcms.xmlrpc.api.testcaseplan.update(request, case_id, plan_id, sortkey)

Updates the sortkey of the selected test-case-plan.

Parameters
  • case_id (int) – case ID.

  • plan_id (int) – plan ID.

  • sortkey (int) – the sort key.

Returns

a mapping of TestCasePlan.

Return type

dict

Example:

# Update sortkey of selected test-case-plan to 10
TestCasePlan.update(1, 2, 10)

TestRun

tcms.xmlrpc.api.testrun.add_cases(request, *args, **kwargs)

Add one or more cases to the selected test runs.

Parameters
  • run_ids (int, str or list) – give one or more run IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a run ID.

  • case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Return type

list

Example:

# Add case id 10 to run 1
TestRun.add_cases(1, 10)
# Add case ids list [10, 20] to run list [1, 2]
TestRun.add_cases([1, 2], [10, 20])
# Add case ids list '10, 20' to run list '1, 2' with String
TestRun.add_cases('1, 2', '10, 20')
tcms.xmlrpc.api.testrun.add_tag(request, *args, **kwargs)

Add one or more tags to the selected test runs.

Parameters
  • run_ids (int, str or list) – give one or more run IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a run ID.

  • tags (str or list) – tag name or a list of tag names to remove.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Return type

list

Example:

# Add tag 'foobar' to run 1
TestPlan.add_tag(1, 'foobar')
# Add tag list ['foo', 'bar'] to run list [1, 2]
TestPlan.add_tag([1, 2], ['foo', 'bar'])
# Add tag list ['foo', 'bar'] to run list [1, 2] with String
TestPlan.add_tag('1, 2', 'foo, bar')
tcms.xmlrpc.api.testrun.create(request, *args, **kwargs)

Creates a new Test Run object and stores it in the database.

Parameters

values (dict) –

a mapping containing these data to create a test run.

  • plan: (int) Required ID of test plan

  • build: (int)/(str) Required ID of Build

  • manager: (int) Required ID of run manager

  • summary: (str) Required

  • product: (int) Required ID of product

  • product_version: (int) Required ID of product version

  • default_tester: (int) optional ID of run default tester

  • plan_text_version: (int) optional

  • estimated_time: (str) optional, could be in format 2h30m30s, which is recommended or HH:MM:SS.

  • notes: (str) optional

  • status: (int) optional 0:RUNNING 1:STOPPED (default 0)

  • case: list or (str) optional list of case ids to add to the run

  • tag: list or (str) optional list of tag to add to the run

Returns

a mapping representing newly created TestRun.

Return type

dict

Changed in version 4.5: Argument errata_id is removed.

Example:

values = {
    'build': 2,
    'manager': 1,
    'plan': 1,
    'product': 1,
    'product_version': 2,
    'summary': 'Testing XML-RPC for TCMS',
}
TestRun.create(values)
tcms.xmlrpc.api.testrun.env_value(request, *args, **kwargs)

Add or remove env values to the given runs, function is same as link_env_value or unlink_env_value

Parameters
  • action (str) – what action to do, add or remove.

  • run_ids (int, str or list) – give one or more run IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a run ID.

  • env_value_ids (int, str or list) – give one or more environment value IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a environment value ID.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Return type

list

Example:

# Add env value 20 to run id 8
TestRun.env_value('add', 8, 20)
tcms.xmlrpc.api.testrun.filter(request, values={})

Performs a search and returns the resulting list of test runs.

Parameters

values (dict) –

a mapping containing these criteria.

  • build: ForeignKey: TestBuild

  • cc: ForeignKey: Auth.User

  • env_value: ForeignKey: Environment Value

  • default_tester: ForeignKey: Auth.User

  • run_id: (int)

  • manager: ForeignKey: Auth.User

  • notes: (str)

  • plan: ForeignKey: TestPlan

  • summary: (str)

  • tag: ForeignKey: Tag

  • product_version: ForeignKey: Version

Returns

list of mappings of found TestRun.

Return type

list

Example:

# Get all of runs contain 'TCMS' in summary
TestRun.filter({'summary__icontain': 'TCMS'})
# Get all of runs managed by xkuang
TestRun.filter({'manager__username': 'xkuang'})
# Get all of runs the manager name starts with x
TestRun.filter({'manager__username__startswith': 'x'})
# Get runs contain the case ID 1, 2, 3
TestRun.filter({'case_run__case__case_id__in': [1, 2, 3]})
tcms.xmlrpc.api.testrun.filter_count(request, values={})

Performs a search and returns the resulting count of runs.

Parameters

values (dict) – a mapping containing criteria. See also TestRun.filter.

Returns

total matching runs.

Return type

int

See also

See examples of TestRun.filter.

tcms.xmlrpc.api.testrun.get(request, run_id)

Used to load an existing test run from the database.

Parameters

run_id (int) – test run ID.

Returns

a mapping representing found TestRun.

Return type

dict

Example:

TestRun.get(1)
tcms.xmlrpc.api.testrun.get_change_history(request, run_id)

Get the list of changes to the fields of this run.

Parameters

run_id (int) – run ID.

Returns

list of mapping with changed fields and their details.

Return type

list

Warning

NOT IMPLEMENTED - History is different than before.

tcms.xmlrpc.api.testrun.get_completion_report(request, run_ids)

Get a report of the current status of the selected runs combined.

Parameters

run_ids (int, str or list) – give one or more run IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a run ID.

Returns

A mapping containing counts and percentages of the combined totals of case-runs in the run. Counts only the most recently statused case-run for a given build and environment.

Return type

dict

Warning

NOT IMPLEMENTED

tcms.xmlrpc.api.testrun.get_env_values(request, run_id)

Get the list of env values to this run.

Parameters

run_id (int) – run ID.

Returns

a list of mappings representing found TCMSEnvValue.

Return type

list[dict]

Example:

TestRun.get_env_values(8)
tcms.xmlrpc.api.testrun.get_issues(request, run_ids)

Get the list of issues attached to this run.

Parameters

run_ids (int, str or list) – give one or more run IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a run ID.

Returns

a list of mappings of Issue.

Return type

list[dict]

Example:

# Get issues belonging to ID 12345
TestRun.get_issues(1)
# Get issues belonging to run ids list [1, 2]
TestRun.get_issues([1, 2])
# Get issues belonging to run ids list 1 and 2 with string
TestRun.get_issues('1, 2')
tcms.xmlrpc.api.testrun.get_tags(request, run_id)

Get the list of tags attached to this run.

Parameters

run_id (int) – run ID.

Returns

a mapping representing found TestTag.

Return type

dict

Example:

TestRun.get_tags(1)
tcms.xmlrpc.api.testrun.get_test_case_runs(request, run_id)

Get the list of cases that this run is linked to.

Parameters

run_id (int) – run ID.

Returns

a list of mappings of found TestCaseRun.

Return type

list[dict]

Example:

# Get all of case runs
TestRun.get_test_case_runs(1)
tcms.xmlrpc.api.testrun.get_test_cases(request, run_id)

Get the list of cases that this run is linked to.

Parameters

run_id (int) – run ID.

Returns

a list of mappings of found TestCase.

Return type

list[dict]

Example:

TestRun.get_test_cases(1)
tcms.xmlrpc.api.testrun.get_test_plan(request, run_id)

Get the plan that this run is associated with.

Parameters

run_id (int) – run ID.

Returns

a mapping of found TestPlan.

Return type

dict

Example:

TestRun.get_test_plan(1)

Link env values to the given runs.

Parameters
  • run_ids (int, str or list) – give one or more run IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a run ID.

  • env_value_ids (int, str or list) – give one or more environment value IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a environment value ID.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Return type

list

Example:

# Add env value 1 to run id 2
TestRun.link_env_value(2, 1)
tcms.xmlrpc.api.testrun.remove_cases(request, *args, **kwargs)

Remove one or more cases from the selected test runs.

Parameters
  • run_ids (int, str or list) – give one or more run IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a run ID.

  • case_ids (int, str or list) – give one or more case IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case ID.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Return type

list

Example:

# Remove case 10 from run 1
TestRun.remove_cases(1, 10)
# Remove case ids list [10, 20] from run list [1, 2]
TestRun.remove_cases([1, 2], [10, 20])
# Remove case ids list '10, 20' from run list '1, 2' with String
TestRun.remove_cases('1, 2', '10, 20')
tcms.xmlrpc.api.testrun.remove_tag(request, *args, **kwargs)

Remove a tag from a run.

Parameters
  • run_ids (int, str or list) – give one or more run IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a run ID.

  • tags (str or list) – tag name or a list of tag names to remove.

Returns

a list which is empty on success.

Return type

list

Example:

# Remove tag 'foo' from run 1
TestRun.remove_tag(1, 'foo')
# Remove tag 'foo' and 'bar' from run list [1, 2]
TestRun.remove_tag([1, 2], ['foo', 'bar'])
# Remove tag 'foo' and 'bar' from run list '1, 2' with String
TestRun.remove_tag('1, 2', 'foo, bar')

Unlink env values to the given runs.

Parameters
  • run_ids (int, str or list) – give one or more run IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a run ID.

  • env_value_ids (int, str or list) – give one or more environment value IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a environment value ID.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Return type

list

Example:

# Unlink env value 1 to run id 2
TestRun.unlink_env_value(2, 1)
tcms.xmlrpc.api.testrun.update(request, *args, **kwargs)

Updates the fields of the selected test run.

Parameters
  • run_ids (int, str or list) – give one or more run IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a run ID.

  • values (dict) –

    a mapping containing these data to update specified runs.

    • plan: (int) TestPlan.plan_id

    • product: (int) Product.id

    • build: (int) Build.id

    • manager: (int) Auth.User.id

    • default_tester: Intege Auth.User.id

    • summary: (str)

    • estimated_time: (TimeDelta) in format 2h30m30s which is recommended or HH:MM:SS.

    • product_version: (int)

    • plan_text_version: (int)

    • notes: (str)

    • status: (int) 0:RUNNING 1:FINISHED

Returns

list of mappings of the updated test runs.

Return type

list[dict]

Changed in version 4.5: Argument errata_id is removed.

Example:

# Update status to finished for run 1 and 2
TestRun.update([1, 2], {'status': 1})

TestCaseRun

tcms.xmlrpc.api.testcaserun.add_comment(request, case_run_ids, comment)

Adds comments to selected test case runs.

Parameters
  • case_run_ids – give one or more case run IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case run ID.

  • comment (str) – the comment content to add.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Return type

list

Example:

# Add comment 'foobar' to case run 1
TestCaseRun.add_comment(1, 'foobar')
# Add 'foobar' to case runs list [1, 2]
TestCaseRun.add_comment([1, 2], 'foobar')
# Add 'foobar' to case runs list '1, 2' with String
TestCaseRun.add_comment('1, 2', 'foobar')
tcms.xmlrpc.api.testcaserun.attach_issue(request, values)

Add one or more issues to the selected test cases.

Parameters

values (dict) –

a mapping containing these data to create a test run.

  • issue_key: (str) Required the issue key.

  • case_run: (int) Required ID of Case

  • tracker: (int) Required ID of issue tracker that issue should belong to.

  • summary: (str) optional issue’s summary

  • description: (str) optional issue’ description

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Return type

list

Example:

# Attach an issue 67890 to case run 12345
TestCaseRun.attach_issue({
        'case_run': [12345],
        'issue_key': '67890',
        'tracker': 1,
        'summary': 'Testing TCMS',
        'description': 'Just foo and bar',
    })

Changed in version 4.2: Some arguments passed via values are changed. case_run_id is changed to case_run, bug_id is changed to issue_key, bz_system_id is changed to tracker. issue_key accepts string instead of integer. case_run within values must be a list of test case ids.

tcms.xmlrpc.api.testcaserun.attach_log(request, case_run_id, name, url)

Add new log link to TestCaseRun

Parameters
  • case_run_id (int) – case run ID.

  • name (str) – link name.

  • url (str) – link URL.

tcms.xmlrpc.api.testcaserun.check_case_run_status(request, name)

Get case run status by name

Parameters

name (str) – the status name.

Returns

a mapping representing found case run status.

Return type

dict

Example:

TestCaseRun.check_case_run_status('idle')
tcms.xmlrpc.api.testcaserun.create(request, values)

Creates a new Test Case Run object and stores it in the database.

Parameters

values (dict) –

a mapping containing these data to create a case run.

  • run: (int) Required ID of Test Run

  • case: (int) Required ID of test case

  • build: (int) Required ID of a Build in plan’s product

  • assignee: (int) optional ID of assignee

  • case_run_status: (int) optional Defaults to “IDLE”

  • case_text_version: (int) optional Default to latest case text version

  • notes: (str) optional

  • sortkey: (int) optional a.k.a. Index, Default to 0

Returns

a mapping representing a newly created case run.

Return type

dict

Example:

# Minimal test case parameters
values = {
    'run': 1990,
    'case': 12345,
    'build': 123,
}
TestCaseRun.create(values)
tcms.xmlrpc.api.testcaserun.detach_issue(request, case_run_ids, issue_keys)

Remove one or more issues to the selected test case-runs.

Parameters
  • case_run_ids – give one or more case run IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case run ID.

  • issue_keys (int, str or list) – give one or more case run IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case run ID.

Returns

a list which is empty on success or a list of mappings with failure codes if a failure occured.

Return type

list

Example:

# Remove issue 1000 from case run 1
TestCaseRun.detach_issue(1, 1000)
# Remove issues [1000, 2000] from case runs list [1, 2]
TestCaseRun.detach_issue([1, 2], [1000, 2000])
# Remove issues '1000, 2000' from case runs list '1, 2' with String
TestCaseRun.detach_issue('1, 2', '1000, 2000')
tcms.xmlrpc.api.testcaserun.detach_log(request, case_run_id, link_id)

Remove log link to TestCaseRun

Parameters
  • case_run_id (int) – case run ID.

  • link_id (int) – case run ID.

tcms.xmlrpc.api.testcaserun.filter(request, values={})

Performs a search and returns the resulting list of test cases.

Parameters

values (dict) –

a mapping containing these criteria.

  • case_run_id: (int)

  • assignee: ForeignKey: Auth.User

  • build: ForeignKey: TestBuild

  • case: ForeignKey: TestCase

  • case_run_status: ForeignKey: TestCaseRunStatus

  • notes: (str)

  • run: ForeignKey: TestRun

  • tested_by: ForeignKey: Auth.User

  • running_date: Datetime

  • close_date: Datetime

Returns

a list of found TestCaseRun.

Return type

list[dict]

Example:

# Get all case runs contain 'TCMS' in case summary
TestCaseRun.filter({'case__summary__icontain': 'TCMS'})
tcms.xmlrpc.api.testcaserun.filter_count(request, values={})

Performs a search and returns the resulting count of cases.

Parameters

values (dict) – a mapping containing criteria. See also TestCaseRun.filter.

Returns

total matching cases.

Return type

int

See also

See example in TestCaseRun.filter.

tcms.xmlrpc.api.testcaserun.get(request, case_run_id)

Used to load an existing test case-run from the database.

Parameters

case_run_id (int) – case run ID.

Returns

a mapping representing found TestCaseRun.

Return type

dict

Example:

TestCaseRun.get(1)
tcms.xmlrpc.api.testcaserun.get_case_run_status(request, case_run_status_id=None)

Get case run status

Parameters

case_run_status_id (int) – optional case run status ID.

Returns

a mapping representing a case run status of specified ID. Otherwise, a list of mappings of all case run status will be returned, if case_run_status_id is omitted.

Return type

dict or list[dict]

Example:

# Get all of case run status
TestCaseRun.get_case_run_status()
# Get case run status by ID 1
TestCaseRun.get_case_run_status(1)
tcms.xmlrpc.api.testcaserun.get_completion_time(request, case_run_id)

Returns the time in seconds that it took for this case to complete.

Parameters

case_run_id (int) – caes run ID.

Returns

Seconds since run was started till this case was completed. Or empty hash for insufficent data.

Return type

int

Example:

TestCaseRun.get_completion_time(1)
tcms.xmlrpc.api.testcaserun.get_completion_time_s(request, run_id, case_id, build_id, environment_id=0)

Returns the time in seconds that it took for this case to complete.

Parameters
  • case_id (int) – case ID.

  • run_id (int) – run ID.

  • build_id (int) – build ID.

  • environment_id (int) – optional environment ID. Defaults to 0.

Returns

Seconds since run was started till this case was completed. Or empty hash for insufficent data.

Return type

int

Example:

TestCaseRun.get_completion_time_s(1, 2, 3, 4)
tcms.xmlrpc.api.testcaserun.get_history(request, case_run_id)

Get the list of case-runs for all runs this case appears in.

Parameters

case_run_id (int) – case run ID.

Returns

a list of mappings of TestCaseRun.

Return type

list[dict]

Warning

NOT IMPLEMENTED

tcms.xmlrpc.api.testcaserun.get_history_s(request, run_id, build_id, environment_id)

Get the list of case-runs for all runs this case appears in.

Parameters
  • case_id (int) – case ID.

  • run_id (int) – run ID.

  • build_id (int) – build ID.

  • environment_id (int) – optional environment ID. Defaults to 0.

Returns

a list mappings of TestCaseRun.

Return type

list[dict]

Warning

NOT IMPLEMENTED

tcms.xmlrpc.api.testcaserun.get_issues(request, case_run_id)

Get the list of issues that are associated with this test case run

Parameters

case_run_id (int) – case run ID.

Returns

a list of mappings of Issue.

Rytpe

list[dict]

Example:

TestCaseRun.get_issues(10)
tcms.xmlrpc.api.testcaserun.get_issues_s(request, run_id, case_id, build_id, environment_id=0)

Get the list of issues that are associated with this test case run

Parameters
  • case_id (int) – case ID.

  • run_id (int) – run ID.

  • build_id (int) – build ID.

  • environment_id (int) – optional environment ID. Defaults to 0.

Returns

a list of found Issue.

Return type

list[dict]

Example:

TestCaseRun.get_issues_s(1, 2, 3, 4)
tcms.xmlrpc.api.testcaserun.get_logs(request, case_run_id)

Get log links to TestCaseRun

Parameters

case_run_id (int) – case run ID.

Returns

list of mappings of found logs LinkReference.

Return type

list[dict]

tcms.xmlrpc.api.testcaserun.get_s(request, case_id, run_id, build_id, environment_id=0)

Used to load an existing test case from the database.

Parameters
  • case_id (int) – case ID.

  • run_id (int) – run ID.

  • build_id (int) – build ID.

  • environment_id (int) – optional environment ID. Defaults to 0.

Returns

a list of found TestCaseRun.

Return type

list[dict]

Example:

TestCaseRun.get_s(1, 2, 3, 4)
tcms.xmlrpc.api.testcaserun.lookup_status_id_by_name(request, name)

DEPRECATED - CONSIDERED HARMFUL Use TestCaseRun.check_case_run_status instead

tcms.xmlrpc.api.testcaserun.lookup_status_name_by_id(request, id)

DEPRECATED - CONSIDERED HARMFUL Use TestCaseRun.get_case_run_status instead

tcms.xmlrpc.api.testcaserun.update(request, case_run_ids, values)

Updates the fields of the selected case-runs.

Parameters
  • case_run_ids – give one or more case run IDs. It could be an integer, a string containing comma separated IDs, or a list of int each of them is a case run ID.

  • values (dict) –

    a mapping containing these data to update specified case runs.

    • build: (int)

    • assignee: (int)

    • case_run_status: (int)

    • notes: (str)

    • sortkey: (int)

Returns

In the case of a single object, it is returned. If a list was passed, it returns an array of object hashes. If the update on any particular object failed, the hash will contain a ERROR key and the message as to why it failed.

Example:

# Update alias to 'tcms' for case 12345 and 23456
TestCaseRun.update([12345, 23456], {'assignee': 2206})

Version

tcms.xmlrpc.api.version.get(request)

Retrieve XMLRPC’s version

Returns

A list that represents the version.

Return type

list

Example:

Version.get()

User

tcms.xmlrpc.api.user.filter(request, query)

Performs a search and returns the resulting list of test cases

Parameters

query (dict) –

a mapping containing these criteria.

  • id: (int): ID

  • username: (str): User name

  • first_name: (str): User first name

  • last_name: (str): User last name

  • email: (str) Email

  • is_active: bool: Return the active users

  • groups: ForeignKey: AuthGroup

Returns

a list of mappings of found User.

Return type

list[dict]

Example:

User.filter({'username__startswith': 'z'})
tcms.xmlrpc.api.user.get(request, id)

Used to load an existing test case from the database.

Parameters

id (int) – user ID.

Returns

a mapping of found User.

Return type

dict

Example:

User.get(2)
tcms.xmlrpc.api.user.get_me(request)

Get the information of myself.

Returns

a mapping of found User.

Return type

dict

Example:

User.get_me()
tcms.xmlrpc.api.user.join(request, *args, **kwargs)

Add user to a group specified by name.

Parameters
  • username (str) – user name.

  • groupname (str) – group name to add given user name.

Raises
  • PermissionDenied – if the request has no permission to add a user to a group.

  • Object.DoesNotExist – if user name or group name does not exist.

Example:

User.join('username', 'groupname')
tcms.xmlrpc.api.user.update(request, values=None, id=None)

Updates the fields of the selected user. it also can change the informations of other people if you have permission.

Parameters
  • id (int) – optional user ID. Defaults to update current user if omitted.

  • values (dict) –

    a mapping containing these data to update a user.

    • first_name: (str) optional

    • last_name: (str) optional (Required if changes category)

    • email: (str) optional

    • password: (str) optional

    • old_password: (str) Required by password

Returns

a mapping representing the updated user.

Return type

dict

Example:

User.update({'first_name': 'foo'})
User.update({'password': 'foo', 'old_password': '123'})
User.update({'password': 'foo', 'old_password': '123'}, 2)

testopia

tcms.xmlrpc.api.testopia.api_version(request)

Return the API version of Nitrate.

tcms.xmlrpc.api.testopia.nitrate_version(request)

Returns the version of Nitrate on this server.

tcms.xmlrpc.api.testopia.tcms_version(request)

Returns the version of Nitrate on this server.

tcms.xmlrpc.api.testopia.testopia_version(request)

Returns the version of Nitrate on this server.