XMLRPC API

Authentication

tcms.xmlrpc.api.auth.login(request, credential)[source]

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

Delete session information

tcms.xmlrpc.api.auth.login_krbv(request)[source]

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

TestBuild

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

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

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

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_runs(request, build_id)[source]

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.get_caseruns(request, build_id)[source]

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.lookup_id_by_name(request, name, product)[source]

DEPRECATED - CONSIDERED HARMFUL Use Build.check_build instead

tcms.xmlrpc.api.build.lookup_name_by_id(request, build_id)[source]

Lookup name by ID

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

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

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

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

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

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

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

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.check_category(request, name, product)[source]

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

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

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

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

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

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

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

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

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

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

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

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.add_component(request, product, name, initial_owner_id=None, initial_qa_contact_id=None)[source]

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.get_component(request, id)[source]

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.update_component(request, component_id, values)[source]

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'})
tcms.xmlrpc.api.product.get_components(request, product)[source]

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

FIXME: NOT IMPLEMENTED

tcms.xmlrpc.api.product.get_milestones(request, product)[source]

FIXME: NOT IMPLEMENTED

tcms.xmlrpc.api.product.get_plans(request, product)[source]

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

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

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.add_version(request, values)[source]

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.get_versions(request, product)[source]

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_name_by_id(request, id)[source]

DEPRECATED Use Product.get instead

tcms.xmlrpc.api.product.lookup_id_by_name(request, name)[source]

DEPRECATED - CONSIDERED HARMFUL Use Product.check_product instead

Tag

tcms.xmlrpc.api.tag.get_tags(request, values)[source]

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_tag(request, plan_ids, tags)[source]

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.add_component(request, plan_ids, component_ids)[source]

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.check_plan_type(request, name)[source]

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

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

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

Parameters:values (dict) –

a mapping containing these criteira.

  • author: ForeignKey: Auth.User
  • attachment: 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={})[source]

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

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_change_history(request, plan_id)[source]

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_env_groups(request, plan_id)[source]

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

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

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

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_components(request, plan_id)[source]

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_test_cases(request, plan_id)[source]

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_all_cases_tags(request, plan_id)[source]

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_test_runs(request, plan_id)[source]

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

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.lookup_type_id_by_name(request, name)[source]

DEPRECATED - CONSIDERED HARMFUL Use TestPlan.check_plan_type instead

tcms.xmlrpc.api.testplan.lookup_type_name_by_id(request, id)[source]

DEPRECATED - CONSIDERED HARMFUL Use TestPlan.get_plan_type instead

tcms.xmlrpc.api.testplan.remove_tag(request, plan_ids, tags)[source]

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.remove_component(request, plan_ids, component_ids)[source]

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.store_text(request, plan_id, text, author=None)[source]

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

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.

tcms.xmlrpc.api.testplan.import_case_via_XML(request, plan_id, xml_content)[source]

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

TestCase

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

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 occured.

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

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

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

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_bug(request, values)[source]

Add one or more bugs to the selected test cases.

Parameters:values

mapping or list of mappings containing these bug information.

  • case_id: (int) Required. Case ID.
  • bug_id: (int) Required. Bug ID.
  • bug_system_id: (int) Required. It could be 1 representing BZ(Default) and 2 representing JIRA.
  • summary: (str) optional Bug summary.
  • description: (str) optional bug description.
Returns:a list which is empty on success or a list of mappings with failure codes if a failure occured.

Example:

# Bug data to add
>>> values = {
        'case_id': 1,
        'bug_id': 1000,
        'bug_system_id': 1,
        'summary': 'Testing TCMS',
        'description': 'Just foo and bar',
    }
>>> TestCase.attach_bug(values)
tcms.xmlrpc.api.testcase.check_case_status(request, name)[source]

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

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.calculate_average_estimated_time(request, case_ids)[source]

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

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.create(request, values)[source]

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_bug(request, case_ids, bug_ids)[source]

Remove one or more bugs 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.
  • bug_ids – 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 bug id 1000 from case 1
>>> TestCase.detach_bug(1, 1000)
# Remove bug ids list [1000, 1001] from cases list [1, 2]
>>> TestCase.detach_bug([1, 2], [1000, 1001])
# Remove bug ids list '1000, 1001' from cases list '1, 2' with String
>>> TestCase.detach_bug('1, 2', '1000, 1001')
tcms.xmlrpc.api.testcase.filter(request, query)[source]

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)
  • attachment: 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={})[source]

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

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_bug_systems(request, id)[source]

Used to load an existing test case bug system from the database.

Parameters:id (int or str) – bug system ID.
Returns:a mappings representing found TestCaseBugSystem.
Return type:dict

Example:

>>> TestCase.get_bug_systems(1)
tcms.xmlrpc.api.testcase.get_bugs(request, case_ids)[source]

Get the list of bugs 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 TestCaseBug.
Return type:list

Example:

# Get bugs belong to ID 1
>>> TestCase.get_bugs(1)
# Get bug belong to case ids list [1, 2]
>>> TestCase.get_bugs([1, 2])
# Get bug belong to case ids list 1 and 2 with string
>>> TestCase.get_bugs('1, 2')
tcms.xmlrpc.api.testcase.get_case_run_history(request, case_id)[source]

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

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

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

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_plans(request, case_id)[source]

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_tags(request, case_id)[source]

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

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)
tcms.xmlrpc.api.testcase.get_priority(request, id)[source]

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)

“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_name_by_id(request, id)[source]

Lookup category name by ID

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

tcms.xmlrpc.api.testcase.lookup_category_id_by_name(request, name, product)[source]

Lookup category ID by name

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

tcms.xmlrpc.api.testcase.lookup_priority_name_by_id(request, id)[source]

Lookup priority name by ID

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

tcms.xmlrpc.api.testcase.lookup_priority_id_by_name(request, value)[source]

Lookup priority ID by name

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

tcms.xmlrpc.api.testcase.lookup_status_name_by_id(request, id)[source]

Lookup status name by ID

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

tcms.xmlrpc.api.testcase.lookup_status_id_by_name(request, name)[source]

Lookup status ID by name

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

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

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

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

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

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

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

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

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

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

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
  • errata_id: (int) optional ID of Errata
  • 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

Example:

>>> values = {
        'build': 2,
        'manager': 1,
        'plan': 1,
        'errata_id': 2,
        '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={})[source]

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

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

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_bugs(request, run_ids)[source]

Get the list of bugs 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 TestCaseBug.
Return type:list[dict]

Example:

# Get bugs belong to ID 12345
>>> TestRun.get_bugs(1)
# Get bug belong to run ids list [1, 2]
>>> TestRun.get_bugs([1, 2])
# Get bug belong to run ids list 1 and 2 with string
>>> TestRun.get_bugs('1, 2')
tcms.xmlrpc.api.testrun.get_change_history(request, run_id)[source]

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

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

Get the list of env values to this run.

Parameters:run_id (int) – run ID.
Returns:a mapping representing found TCMSEnvValue.
Return type:dict

Example:

>>> TestRun.get_env_values(8)
tcms.xmlrpc.api.testrun.get_tags(request, run_id)[source]

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

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

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

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
    • errata_id: (int) Errata.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]

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

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_bug(request, values)[source]

Add one or more bugs to the selected test cases.

Parameters:values (dict) –

a mapping containing these data to create a test run.

  • case_run_id: (int) Required ID of Case
  • bug_id: (int) Required ID of Bug
  • bug_system_id: (int) Required 1: BZ(Default), 2: JIRA
  • summary: (str) optional Bug summary
  • description: (str) optional Bug 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 a bug 67890 to case run 12345
>>> TestCaseRun.attach_bug({
        'case_run_id': 12345,
        'bug_id': 67890,
        'bug_system_id': 1,
        'summary': 'Testing TCMS',
        'description': 'Just foo and bar',
    })
tcms.xmlrpc.api.testcaserun.attach_log(request, case_run_id, name, url)[source]

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

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

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_bug(request, case_run_ids, bug_ids)[source]

Remove one or more bugs 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.
  • bug_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.
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 bug id 1000 from case run 1
>>> TestCaseRun.detach_bug(1, 1000)
# Remove bug ids list [1000, 2000] from case runs list [1, 2]
>>> TestCaseRun.detach_bug([1, 2], [1000, 2000])
# Remove bug ids list '1000, 2000' from case runs list '1, 2' with String
>>> TestCaseRun.detach_bug('1, 2', '1000, 2000')
tcms.xmlrpc.api.testcaserun.detach_log(request, case_run_id, link_id)[source]

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

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

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

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_s(request, case_id, run_id, build_id, environment_id=0)[source]

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.get_bugs(request, case_run_id)[source]

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

Parameters:case_run_id (int) – case run ID.
Returns:a list of mappings of TestCaseBug.
Rytpe:list[dict]

Example:

>>> TestCase.get_bugs(10)
tcms.xmlrpc.api.testcaserun.get_bugs_s(request, run_id, case_id, build_id, environment_id=0)[source]

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

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 TestCaseBug.

Return type:

list[dict]

Example:

>>> TestCaseRun.get_bugs_s(1, 2, 3, 4)
tcms.xmlrpc.api.testcaserun.get_case_run_status(request, case_run_status_id=None)[source]

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

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

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

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

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_logs(request, case_run_id)[source]

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.lookup_status_name_by_id(request, id)[source]

DEPRECATED - CONSIDERED HARMFUL Use TestCaseRun.get_case_run_status instead

tcms.xmlrpc.api.testcaserun.lookup_status_id_by_name(request, name)[source]

DEPRECATED - CONSIDERED HARMFUL Use TestCaseRun.check_case_run_status instead

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

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

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

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

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

Get the information of myself.

Returns:a mapping of found User.
Return type:dict

Example:

>>> User.get_me()
tcms.xmlrpc.api.user.update(request, values=None, id=None)[source]

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)
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')

testopia

tcms.xmlrpc.api.testopia.api_version(request)[source]

Return the API version of Nitrate.

tcms.xmlrpc.api.testopia.nitrate_version(request)[source]

Returns the version of Nitrate on this server.

tcms.xmlrpc.api.testopia.tcms_version(request)[source]

Returns the version of Nitrate on this server.

tcms.xmlrpc.api.testopia.testopia_version(request)[source]

Returns the version of Nitrate on this server.