XMLRPC¶
Authentication¶
-
tcms.xmlrpc.api.auth.
login
(request, credential)¶ Login into Nitrate
- Parameters
credential (dict) – a mapping containing
username
andpassword
.- Returns
Session ID
- Return type
str
- Raises
PermissionDenied – if either
username
orpassword
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¶
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)
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)
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 tocase
,bug_id
is changed toissue_key
,bug_system_id
is changed totracker
. 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)
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)
-
tcms.xmlrpc.api.testcase.
link_plan
(request, case_ids, plan_ids)¶ “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)
-
tcms.xmlrpc.api.testcase.
unlink_plan
(requst, case_id, plan_id)¶ 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 orHH: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
orremove
.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 mapping representing found
TCMSEnvValue
.- Return type
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')
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)
-
tcms.xmlrpc.api.testrun.
link_env_value
(request, *args, **kwargs)¶ 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')
-
tcms.xmlrpc.api.testrun.
unlink_env_value
(request, *args, **kwargs)¶ 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 orHH: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 tocase_run
,bug_id
is changed toissue_key
,bz_system_id
is changed totracker
.issue_key
accepts string instead of integer.case_run
withinvalues
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.