Nitrate XML-RPC Service(Beta)
You need to invoke it using an XML-RPC Client!
python-nitrate is a Python interface to the Nitrate test case management system.
Changes from testopia
- [Model].filter- The 'filter' method is the replacement of list method in testopia.
It's a full featured wrapper of the 'filter' method of Django QuerySet.
It have following star features:
- Relationship- For example to get all of test cases belong to 'RHEL 5'
We use the category path for recommend:
>>> TestCase.filter({'category__product__name': 'Red Hat Enterprise Linux 5'}) - Field lookups- For example to get all test cases with summary starts with 'test':
>>> TestCase.filter({'summary__startswith': 'test'})Access this URL for more information.
- Relationship- For example to get all of test cases belong to 'RHEL 5'
- [Model].filter_count - See [Model].filter.
- Multiple operations- In Nitrate,most of functions are change to support multiple operations,
including add_bug,remove_bug,add_tag,remove_tag - Argument and response changes- Most of the function argument are compatible with testopia,
exclude some special function that not supported or deprecated.
And the response changes to hash not a array of hash,not just a array only.
How to handle ForeignKey arguments
In addition to the basic types such as Integers,Strings,Boolean,there is a relationship type called ForeignKey.
The Syntax of using ForeignKey in our XMLRPC API is quite simple:
foreignkey + '__' + fieldname + '__' + query_Syntax.
Taking TestCase.filter() for example,if the query is based on a default_tester's username starts with 'John',the Syntax will look like this:
TestCase.filter({'user__username__startswith': 'John'})
In which case,the foreignkey is 'user',fieldname is 'username',and query_Syntax is 'startswith',they are joined together using double underscores '__'.
For all the XMLRPC API,we have listed the available ForeignKey,however,for the available foreignkey field names that can be used in a query,please check out Nitrate source code on fedora. The definitions are located in files named 'models.py'; for a detailed query Syntax documentation,please check out the Django documentation:
https://docs.djangoproject.com/en/1.2/topics/db/queries/#field-lookupsAvailable methods
- Auth.login
- Auth.login_krbv
- Auth.logout
- Build.check_build
- Build.create
- Build.get
- Build.get_caseruns
- Build.get_runs
- Build.lookup_id_by_name
- Build.lookup_name_by_id
- Build.update
- Env.filter_groups
- Env.filter_properties
- Env.filter_values
- Env.get_properties
- Env.get_values
- Product.add_component
- Product.add_version
- Product.check_category
- Product.check_component
- Product.check_product
- Product.filter
- Product.filter_categories
- Product.filter_components
- Product.filter_versions
- Product.get
- Product.get_builds
- Product.get_cases
- Product.get_categories
- Product.get_category
- Product.get_component
- Product.get_components
- Product.get_environments
- Product.get_milestones
- Product.get_plans
- Product.get_runs
- Product.get_tag
- Product.get_versions
- Product.lookup_id_by_name
- Product.lookup_name_by_id
- Product.update_component
- @L_502_45@
- TestCase.add_comment
- TestCase.add_component
- TestCase.add_tag
- TestCase.add_to_run
- TestCase.attach_bug
- TestCase.calculate_average_estimated_time
- TestCase.calculate_total_estimated_time
- TestCase.check_case_status
- TestCase.check_priority
- TestCase.create
- TestCase.detach_bug
- TestCase.filter
- TestCase.filter_count
- TestCase.get
- TestCase.get_bug_systems
- TestCase.get_bugs
- TestCase.get_case_run_history
- TestCase.get_case_status
- TestCase.get_change_history
- TestCase.get_components
- TestCase.get_plans
- TestCase.get_priority
- TestCase.get_tags
- TestCase.get_text
- TestCase.link_plan
- TestCase.lookup_category_id_by_name
- TestCase.lookup_category_name_by_id
- TestCase.lookup_priority_id_by_name
- TestCase.lookup_priority_name_by_id
- TestCase.lookup_status_id_by_name
- TestCase.lookup_status_name_by_id
- TestCase.notification_add_cc
- TestCase.notification_get_cc_list
- TestCase.notification_remove_cc
- TestCase.remove_component
- TestCase.remove_tag
- TestCase.store_text
- TestCase.unlink_plan
- TestCase.update
- TestCasePlan.get
- TestCasePlan.update
- TestCaseRun.add_comment
- TestCaseRun.attach_bug
- TestCaseRun.attach_log
- TestCaseRun.check_case_run_status
- TestCaseRun.create
- TestCaseRun.detach_bug
- TestCaseRun.detach_log
- TestCaseRun.filter
- TestCaseRun.filter_count
- TestCaseRun.get
- TestCaseRun.get_bugs
- TestCaseRun.get_bugs_s
- TestCaseRun.get_case_run_status
- TestCaseRun.get_completion_time
- TestCaseRun.get_completion_time_s
- TestCaseRun.get_history
- TestCaseRun.get_history_s
- TestCaseRun.get_logs
- TestCaseRun.get_s
- TestCaseRun.lookup_status_id_by_name
- TestCaseRun.lookup_status_name_by_id
- TestCaseRun.update
- TestPlan.add_component
- TestPlan.add_tag
- TestPlan.check_plan_type
- TestPlan.create
- TestPlan.filter
- TestPlan.filter_count
- TestPlan.get
- TestPlan.get_all_cases_tags
- TestPlan.get_change_history
- TestPlan.get_components
- TestPlan.get_env_groups
- TestPlan.get_plan_type
- TestPlan.get_product
- TestPlan.get_tags
- TestPlan.get_test_cases
- TestPlan.get_test_runs
- TestPlan.get_text
- TestPlan.import_case_via_XML
- TestPlan.lookup_type_id_by_name
- TestPlan.lookup_type_name_by_id
- TestPlan.remove_component
- TestPlan.remove_tag
- TestPlan.store_text
- TestPlan.update
- TestRun.add_cases
- TestRun.add_tag
- TestRun.create
- TestRun.env_value
- TestRun.filter
- TestRun.filter_count
- TestRun.get
- TestRun.get_bugs
- TestRun.get_change_history
- TestRun.get_completion_report
- TestRun.get_env_values
- TestRun.get_tags
- TestRun.get_test_case_runs
- TestRun.get_test_cases
- TestRun.get_test_plan
- TestRun.link_env_value
- TestRun.remove_cases
- TestRun.remove_tag
- TestRun.unlink_env_value
- TestRun.update
- Testopia.api_version
- Testopia.log_call
- Testopia.nitrate_version
- Testopia.tcms_version
- Testopia.testopia_version
- User.filter
- User.get
- User.get_me
- User.join
- User.update
- Version.get
Descriptions
Auth.login
Description: Login into Nitrate
Params: $parameters - Hash: keys must match valid search fields.
+-------------------------------------------------------------------+
| Login Parameters |
+-------------------------------------------------------------------+
| Key | Valid Values |
| username | A nitrate login (email address) |
| password | String |
+-------------------------------------------------------------------+
Returns: String: Session ID.
Example:
>>> Auth.login({'username': 'foo','password': 'bar'})
Auth.login_krbv
Description: Login into the Nitrate deployed with mod_auth_kerb Returns: String: Session ID. Example: $ kinit Password for username@example.com: $ python >>> Auth.login_krbv()
Auth.logout
Description: Delete session information.
Build.check_build
Description: Looks up and returns a build by name.
Params: $name - String: name of the build.
$product - product_id of the product in the Database
Returns: Hash: Matching Build object hash or error if not found.
Example:
# Get with product ID
>>> Build.check_build('2008-02-25',61)
# Get with product name
>>> Build.check_build('2008-02-25','Red Hat Enterprise Linux 5')
Build.create
Description: Creates a new build object and stores it in the database
Params: $values - Hash: A reference to a hash with keys and values
matching the fields of the build to be created.
+-------------+----------------+-----------+---------------------------+
| Field | Type | Null | Description |
+-------------+----------------+-----------+---------------------------+
| product | Integer/String | required | ID or Name of product |
| name | String | required | |
| description | String | Optional | |
| is_active | Boolean | Optional | Defaults to True (1) |
+-------------+----------------+-----------+---------------------------+
Returns: The newly created object hash.
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','is_active': 0})
Build.get
Description: Used to load an existing build from the database. Params: $id - An integer representing the ID in the database Returns: A blessed Build object hash Example: >>> Build.get(1234)
Build.get_caseruns
Description: Returns the list of case-runs that this Build is used in. Params: $id - Integer: Build ID. Returns: Array: List of case-run object hashes. Example: >>> Build.get_caseruns(1234)
Build.get_runs
Description: Returns the list of runs that this Build is used in. Params: $id - Integer: Build ID. Returns: Array: List of run object hashes. Example: >>> Build.get_runs(1234)
Build.lookup_id_by_name
DEPRECATED - CONSIDERED HARMFUL Use Build.check_build instead
Build.lookup_name_by_id
DEPRECATED Use Build.get instead
Build.update
Description: Updates the fields of the selected build or builds.
Params: $id - Integer: A single build ID.
$values - Hash of keys matching Build fields and the new values
to set each field to.
+-------------+----------------+-----------+---------------------------+
| Field | Type | Null | Description |
+-------------+----------------+-----------+---------------------------+
| product | Integer/String | Optional | ID or Name of product |
| name | String | Optional | |
| description | String | Optional | |
| is_active | Boolean | Optional | True/False |
+-------------+----------------+-----------+---------------------------+
Returns: Hash: The updated Build object hash.
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.filter_groups
Description: Performs a search and returns the resulting list of env groups.
Params: $query - Hash: keys must match valid search fields.
+------------------------------------------------------------------+
| Product Search Parameters |
+------------------------------------------------------------------+
| Key | Valid Values |
| id | Integer: ID of env group |
| name | String |
| manager | ForeignKey: Auth.user |
| modified_by | ForeignKey: Auth.user |
| is_active | Boolean |
| property | ForeignKey: TCMSEnvProperty |
+------------------------------------------------------------------+
Returns: Array: Matching env groups are retuned in a list of hashes.
Example:
# Get all of env group name contains 'Desktop'
>>> Env.filter_groups({'name__icontains': 'Desktop'})
Env.filter_properties
Description: Performs a search and returns the resulting list of env properties.
Params: $query - Hash: keys must match valid search fields.
+------------------------------------------------------------------+
| Product Search Parameters |
+------------------------------------------------------------------+
| Key | Valid Values |
| id | Integer: ID of env properties |
| name | String |
| is_active | Boolean |
| 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'})
Env.filter_values
Description: Performs a search and returns the resulting list of env properties.
Params: $query - Hash: keys must match valid search fields.
+------------------------------------------------------------------+
| Product Search Parameters |
+------------------------------------------------------------------+
| Key | Valid Values |
| id | Integer: ID of env value |
| value | String |
| is_active | Boolean |
| property | ForeignKey: TCMSEnvProperty |
+------------------------------------------------------------------+
Returns: Array: Matching env values are retuned in a list of hashes.
Example:
# Get all of env values name contains 'Desktop'
>>> Env.filter_values({'name__icontains': 'Desktop'})
Env.get_properties
Description: Get the list of properties associated with this env group.
Params: $env_group_id - Integer: env_group_id of the env group in the Database
Return all of properties when the argument is not specific.
$is_active - Boolean: True to only include builds where is_active is true.
Default: True
Returns: Array: Returns an array of env properties objects.
Example:
# Get all of properties
>>> Env.get_properties()
# Get the properties in group 10
>>> Env.get_properties(10)
Env.get_values
Description: Get the list of values associated with this env property.
Params: $env_property_id - Integer: env_property_id of the env property in the Database
Return all of values when the argument is not specific.
$is_active - Boolean: True to only include builds where is_active is true.
Default: True
Returns: Array: Returns an array of env values objects.
Example:
# Get all of properties
>>> Env.get_properties()
# Get the properties in group 10
>>> Env.get_properties(10)
Product.add_component
Description: Add component to selected product.
Params: $product - Integer/String
Integer: product_id of the product in the Database
String: Product name
$name - String: Component name
[$initial_owner_id] - Integer: (OPTIONAL) The numeric ID or the login of the author.
Defaults to logged in user.
[$initial_qa_contact_id] - Integer: (OPTIONAL) The numeric ID or the login of the author.
Defaults to logged in user.
Returns: Hash: Component object hash.
Example:
>>> Product.add_component(71,'JPBMM')
Product.add_version
Description: Add version to specified product.
Params: $product - Integer/String
Integer: product_id of the product in the Database
String: Product name
$value - String
The name of the version string.
Returns: Array: Returns the newly added version object,error info if Failed.
Example:
# Add version for specified product:
>>> Product.add_version({'value': 'devel','product': 272})
{'product': 'QE Test Product','id': '1106','value': 'devel','product_id': 272}
# Run it again:
>>> Product.add_version({'value': 'devel','product': 272})
[['__all__','Version with this Product and Value already exists.']]
Product.check_category
Description: Looks up and returns a category by name.
Params: $name - String: name of the category.
$product - Integer/String
Integer: product_id of the product in the Database
String: Product name
Returns: Hash: Matching Category object hash or error if not found.
Example:
# Get with product ID
>>> Product.check_category('Feature',61)
# Get with product name
>>> Product.check_category('Feature','Red Hat Enterprise Linux 5')
Product.check_component
Description: Looks up and returns a component by name.
Params: $name - String: name of the category.
$product - Integer/String
Integer: product_id of the product in the Database
String: Product name
Returns: Hash: Matching component object hash or error if not found.
Example:
# Get with product ID
>>> Product.check_component('acpi',61)
# Get with product name
>>> Product.check_component('acpi','Red Hat Enterprise Linux 5')
Product.check_product
Description: Looks up and returns a validated product.
Params: $name - Integer/String
Integer: product_id of the product in the Database
String: Product name
Returns: Hash: Matching Product object hash or error if not found.
Example:
# Get with product ID
>>> Product.check_product(61)
# Get with product name
>>> Product.check_product('Red Hat Enterprise Linux 5')
@L_502_185@
Description: Performs a search and returns the resulting list of products.
Params: $query - Hash: keys must match valid search fields.
+------------------------------------------------------------------+
| Product Search Parameters |
+------------------------------------------------------------------+
| Key | Valid Values |
| id | Integer: ID of product |
| name | String |
| classification | ForeignKey: Classfication |
| description | String |
+------------------------------------------------------------------+
Returns: Array: Matching products are retuned in a list of hashes.
Example:
# Get all of product named 'Red Hat Enterprise Linux 5'
>>> Product.filter({'name': 'Red Hat Enterprise Linux 5'})
Product.filter_categories
Description: Performs a search and returns the resulting list of categories.
Params: $query - Hash: keys must match valid search fields.
+------------------------------------------------------------------+
| Component Search Parameters |
+------------------------------------------------------------------+
| Key | Valid Values |
| id | Integer: ID of product |
| name | String |
| product | ForeignKey: Product |
| description | String |
+------------------------------------------------------------------+
Returns: Array: Matching categories are retuned in a list of hashes.
Example:
# Get all of categories named like 'libvirt'
>>> Product.filter_categories({'name__icontains': 'regression'})
# Get all of categories named in product 'Red Hat Enterprise Linux 5'
>>> Product.filter_categories({'product__name': 'Red Hat Enterprise Linux 5'})
Product.filter_components
Description: Performs a search and returns the resulting list of components.
Params: $query - Hash: keys must match valid search fields.
+------------------------------------------------------------------+
| Component Search Parameters |
+------------------------------------------------------------------+
| Key | Valid Values |
| id | Integer: ID of product |
| name | String |
| product | ForeignKey: Product |
| initial_owner | ForeignKey: Auth.User |
| initial_qa_contact | ForeignKey: Auth.User |
| description | String |
+------------------------------------------------------------------+
Returns: Array: Matching components are retuned in a list of hashes.
Example:
# Get all of components named like 'libvirt'
>>> Product.filter_components({'name__icontains': 'libvirt'})
# Get all of components named in product 'Red Hat Enterprise Linux 5'
>>> Product.filter_components({'product__name': 'Red Hat Enterprise Linux 5'})
Product.filter_versions
Description: Performs a search and returns the resulting list of versions.
Params: $query - Hash: keys must match valid search fields.
+------------------------------------------------------------------+
| Component Search Parameters |
+------------------------------------------------------------------+
| Key | Valid Values |
| id | Integer: ID of product |
| value | String |
| product | ForeignKey: Product |
+------------------------------------------------------------------+
Returns: Array: Matching versions are retuned in a list of hashes.
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 'Red Hat Enterprise Linux 5'
>>> Product.filter_versions({'product__name': 'Red Hat Enterprise Linux 5'})
Product.get
Description: Used to load an existing product from the database. Params: $id - An integer representing the ID in the database Returns: A blessed TCMS Product object hash Example: >>> Product.get(61)
Product.get_builds
Description: Get the list of builds associated with this product.
Params: $product - Integer/String
Integer: product_id of the product in the Database
String: Product name
$is_active - Boolean: True to only include builds where is_active is true.
Default: True
Returns: Array: Returns an array of Build objects.
Example:
# Get with product id including all builds
>>> Product.get_builds(61)
# Get with product name excluding all inactive builds
>>> Product.get_builds('Red Hat Enterprise Linux 5',0)
Product.get_cases
Description: Get the list of cases associated with this product.
Params: $product - Integer/String
Integer: product_id of the product in the Database
String: Product name
Returns: Array: Returns an array of TestCase objects.
Example:
# Get with product id
>>> Product.get_cases(61)
# Get with product name
>>> Product.get_cases('Red Hat Enterprise Linux 5')
Product.get_categories
Description: Get the list of categories associated with this product.
Params: $product - Integer/String
Integer: product_id of the product in the Database
String: Product name
Returns: Array: Returns an array of Case Category objects.
Example:
# Get with product id
>>> Product.get_categories(61)
# Get with product name
>>> Product.get_categories('Red Hat Enterprise Linux 5')
Product.get_category
Description: Get the category matching the given id. Params: $id - Integer: ID of the category in the database. Returns: Hash: Category object hash. Example: >>> Product.get_category(11)
Product.get_component
Description: Get the component matching the given id. Params: $id - Integer: ID of the component in the database. Returns: Hash: Component object hash. Example: >>> Product.get_component(11)
Product.get_components
Description: Get the list of components associated with this product.
Params: $product - Integer/String
Integer: product_id of the product in the Database
String: Product name
Returns: Array: Returns an array of Component objects.
Example:
# Get with product id
>>> Product.get_components(61)
# Get with product name
>>> Product.get_components('Red Hat Enterprise Linux 5')
Product.get_environments
FIXME: NOT IMPLEMENTED
Product.get_milestones
FIXME: NOT IMPLEMENTED
Product.get_plans
Description: Get the list of plans associated with this product.
Params: $product - Integer/String
Integer: product_id of the product in the Database
String: Product name
Returns: Array: Returns an array of Test Plan objects.
Example:
# Get with product id
>>> Product.get_plans(61)
# Get with product name
>>> Product.get_plans('Red Hat Enterprise Linux 5')
Product.get_runs
Description: Get the list of runs associated with this product.
Params: $product - Integer/String
Integer: product_id of the product in the Database
String: Product name
Returns: Array: Returns an array of Test Run objects.
Example:
# Get with product id
>>> Product.get_runs(61)
# Get with product name
>>> Product.get_runs('Red Hat Enterprise Linux 5')
Product.get_tag
Description: Get the list of tags. Params: $id - Integer: ID of the tag in the database. Returns: Array: Returns an array of Tags objects. Example: >>> Product.get_tag(10)
Product.get_versions
Description: Get the list of versions associated with this product.
Params: $product - Integer/String
Integer: product_id of the product in the Database
String: Product name
Returns: Array: Returns an array of Version objects.
Example:
# Get with product id
>>> Product.get_runs(61)
# Get with product name
>>> Product.get_runs('Red Hat Enterprise Linux 5')
Product.lookup_id_by_name
DEPRECATED - CONSIDERED HARMFUL Use Product.check_product instead
Product.lookup_name_by_id
DEPRECATED Use Product.get instead
Product.update_component
Description: Update component to selected product.
Params: $component_id - Integer: ID of the component in the database.
$values - Hash of keys matching TestCase fields and the new values
to set each field to.
+-----------------------+----------------+-----------------------------------------+
| Field | Type | Null |
+-----------------------+----------------+-----------------------------------------+
| name | String | Optional |
| initial_owner_id | Integer | Optional(int - user_id) |
| initial_qa_contact_id | Integer | Optional(int - user_id) |
+-----------------------+----------------+-----------------------------------------+
Returns: Hash: Component object hash.
Example:
>>> Product.update_component(71,{'name': 'NewName'})
Tag.get_tags
Description: Get the list of tags.
Params: $values - Hash: keys must match valid search fields.
+------------------------------------------------------------+
| tag Search Parameters |
+------------------------------------------------------------+
| Key | Valid Values |
| ids | List of Integer |
| names | List of String |
+------------------------------------------------------------+
Returns: Array: An array of tag object hashes.
Example:
>>> values= {'ids': [121,123]}
>>> Tag.get_tags(values)
TestCase.add_comment
Description: Adds comments to selected test cases.
Params: $case_ids - Integer/Array/String: An integer representing the ID in the database,an array of case_ids,or a string of comma separated case_ids.
$comment - String - The comment
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occured.
Example:
# Add comment 'foobar' to case 1234
>>> TestCase.add_comment(1234,'foobar')
# Add 'foobar' to cases list [56789,12345]
>>> TestCase.add_comment([56789,12345],'foobar')
# Add 'foobar' to cases list '56789,12345' with String
>>> TestCase.add_comment('56789,12345','foobar')
TestCase.add_component
Description: Adds one or more components to the selected test cases.
Params: $case_ids - Integer/Array/String: An integer representing the ID in the database,or a string of comma separated case_ids.
$component_ids - Integer/Array/String - The component ID,an array of Component IDs
or a comma separated list of component IDs
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occured.
Example:
# Add component id 54321 to case 1234
>>> TestCase.add_component(1234,54321)
# Add component ids list [1234,5678] to cases list [56789,12345]
>>> TestCase.add_component([56789,[1234,5678])
# Add component ids list '1234,5678' to cases list '56789,12345' with String
>>> TestCase.add_component('56789,'1234,5678')
TestCase.add_tag
Description: Add one or more tags to the selected test cases.
Params: $case_ids - Integer/Array/String: An integer representing the ID in the database,or a string of comma separated case_ids.
$tags - String/Array - A single tag,an array of tags,or a comma separated list of tags.
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occured.
Example:
# Add tag 'foobar' to case 1234
>>> TestCase.add_tag(1234,'foobar')
# Add tag list ['foo','bar'] to cases list [12345,67890]
>>> TestCase.add_tag([12345,67890],['foo','bar'])
# Add tag list ['foo',67890] with String
>>> TestCase.add_tag('12345,67890','foo,bar')
TestCase.add_to_run
Description: Add one or more cases to the selected test runs.
Params: $case_ids - Integer/Array/String: An integer representing the ID in the database,or a string of comma separated case_ids.
$run_ids - Integer/Array/String: An integer representing the ID in the database
an array of IDs,or a comma separated list of IDs.
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occured.
Example:
# Add case 1234 to run id 54321
>>> TestCase.add_to_run(1234,54321)
# Add case ids list [56789,12345] to run list [1234,5678]
>>> TestCase.add_to_run([56789,5678])
# Add case ids list 56789 and 12345 to run list 1234 and 5678 with String
>>> TestCase.add_to_run('56789,5678')
TestCase.attach_bug
Description: Add one or more bugs to the selected test cases.
Params: $values - Array/Hash: A reference to a hash or array of hashes with keys and values
matching the fields of the test case bug to be created.
+-------------------+----------------+-----------+-------------------------------+
| Field | Type | Null | Description |
+-------------------+----------------+-----------+-------------------------------+
| case_id | Integer | required | ID of Case |
| bug_id | Integer | required | ID of Bug |
| bug_system_id | Integer | required | 1: BZ(Default),2: JIRA |
| summary | String | Optional | Bug summary |
| description | String | Optional | Bug description |
+-------------------+----------------+-----------+-------------------------------+
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occured.
Example:
>>> TestCase.attach_bug({
'case_id': 12345,'bug_id': 67890,'bug_system_id': 1,'summary': 'Testing TCMS','description': 'Just foo and bar',})
TestCase.calculate_average_estimated_time
Description: Returns an average estimated time for cases. Params: $case_ids - Integer/String: An integer representing the ID in the database. Returns: String: Time in "HH:MM:SS" format. Example: >>> TestCase.calculate_average_time([609,610,611])
TestCase.calculate_total_estimated_time
Description: Returns an total estimated time for cases. Params: $case_ids - Integer/String: An integer representing the ID in the database. Returns: String: Time in "HH:MM:SS" format. Example: >>> TestCase.calculate_total_time([609,611])
TestCase.check_case_status
Description: Looks up and returns a case status by name.
Params: $name - String: name of the case status.
Returns: Hash: Matching case status object hash or error if not found.
Example:
>>> TestCase.check_case_status('proposed')
TestCase.check_priority
Description: Looks up and returns a priority by name.
Params: $value - String: name of the priority.
Returns: Hash: Matching priority object hash or error if not found.
Example:
>>> TestCase.check_priority('p1')
TestCase.create
Description: Creates a new Test Case object and stores it in the database.
Params: $values - Array/Hash: A reference to a hash or array of hashes with keys and values
matching the fields of the test case to be created.
+----------------------------+----------------+-----------+---------------------------------------+
| Field | Type | Null | Description |
+----------------------------+----------------+-----------+---------------------------------------+
| product | Integer | required | ID of Product |
| category | Integer | required | ID of Category |
| priority | Integer | required | ID of Priority |
| summary | String | required | |
| case_status | Integer | Optional | ID of case status |
| plan | Array/Str/Int | Optional | ID or List of plan_ids |
| component | Integer/String | Optional | ID of Priority |
| default_tester | String | Optional | Login of tester |
| estimated_time | String | Optional | 2h30m30s(recommend) or HH:MM:SS Format|
| is_automated | Integer | Optional | 0: Manual,1: Auto,2: Both |
| is_automated_proposed | Boolean | Optional | Default 0 |
| script | String | Optional | |
| arguments | String | Optional | |
| requirement | String | Optional | |
| alias | String | Optional | Must be unique |
| action | String | Optional | |
| effect | String | Optional | Expected Result |
| setup | String | Optional | |
| breakdown | String | Optional | |
| tag | Array/String | Optional | String Comma separated |
| bug | Array/String | Optional | String Comma separated |
| extra_link | String | Optional | reference link |
+----------------------------+----------------+-----------+---------------------------------------+
Returns: Array/Hash: The newly created object hash if a single case was created,or
an array of objects if more than one was created. If any single case threw an
error during creation,a hash with an ERROR key will be set in its place.
Example:
# Minimal test case parameters
>>> values = {
'category': 135,'product': 61,'summary': 'Testing XML-RPC','priority': 1,}
>>> TestCase.create(values)
TestCase.detach_bug
Description: Remove one or more bugs to the selected test cases.
Params: $case_ids - Integer/Array/String: An integer representing the ID in the database,or a string of comma separated case_ids
$bug_ids - Integer/Array/String: An integer representing the ID in the database,an array of bug_ids,or a string of comma separated primary key of bug_ids.
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occured.
Example:
# Remove bug id 54321 from case 1234
>>> TestCase.detach_bug(1234,54321)
# Remove bug ids list [1234,5678] from cases list [56789,12345]
>>> TestCase.detach_bug([56789,5678])
# Remove bug ids list '1234,5678' from cases list '56789,12345' with String
>>> TestCase.detach_bug('56789,5678')
TestCase.filter
Description: Performs a search and returns the resulting list of test cases.
Params: $query - Hash: keys must match valid search fields.
+------------------------------------------------------------------+
| Case Search Parameters |
+------------------------------------------------------------------+
| Key | Valid Values |
| author | A bugzilla login (email address) |
| attachment | ForeignKey: Attchment |
| alias | String |
| case_id | Integer |
| 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: Test Plan |
| priority | ForeignKey: Priority |
| category__product | ForeignKey: Product |
| summary | String |
| tags | ForeignKey: Tags |
| create_date | Datetime |
| is_automated | 1: Only show current 0: show not current |
| script | Text |
+------------------------------------------------------------------+
Returns: Array: Matching test cases are retuned in a list of hashes.
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 137
>>> TestCase.filter({'plan__plan_id': 137})
# 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,34567]})
TestCase.filter_count
Description: Performs a search and returns the resulting count of cases. Params: $values - Hash: keys must match valid search fields (see filter). Returns: Integer - total matching cases. Example: # See TestCase.filter()
TestCase.get
Description: Used to load an existing test case from the database. Params: $id - Integer/String: An integer representing the ID in the database Returns: A blessed TestCase object Hash Example: >>> TestCase.get(1193)
TestCase.get_bug_systems
Description: Used to load an existing test case bug system from the database. Params: $id - Integer/String: An integer representing the ID in the database Returns: Array: An array of bug object hashes. Example: >>> TestCase.get_bug_systems(1)
TestCase.get_bugs
Description: Get the list of bugs that are associated with this test case.
Params: $case_ids - Integer/String: An integer representing the ID in the database
Returns: Array: An array of bug object hashes.
Example:
# Get bugs belong to ID 12345
>>> TestCase.get_bugs(12345)
# Get bug belong to case ids list [12456,23456]
>>> TestCase.get_bugs([12456,23456])
# Get bug belong to case ids list 12456 and 23456 with string
>>> TestCase.get_bugs('12456,23456')
TestCase.get_case_run_history
*** FIXME: NOT IMPLEMENTED - Case run history is different than before***
Description: 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.
Params: $case_id - Integer/String: An integer representing the ID in the database
Returns: Array: An array of case-run object hashes.
Example:
>>> TestCase.get_case_run_history(12345)
TestCase.get_case_status
Description: Get the case status matching the given id. Params: $id - Integer: ID of the case status in the database. Returns: Hash: case status object hash. Example: # Get all of case status >>> TestCase.get_case_status() # Get case status by ID 1 >>> TestCase.get_case_status(1)
TestCase.get_change_history
*** FIXME: NOT IMPLEMENTED - Case history is different than before*** Description: Get the list of changes to the fields of this case. Params: $case_id - Integer/String: An integer representing the ID in the database Returns: Array: An array of hashes with changed fields and their details. Example: >>> TestCase.get_change_history(12345)
TestCase.get_components
" Description: Get the list of components attached to this case. Params: $case_id - Integer/String: An integer representing the ID in the database Returns: Array: An array of component object hashes. Example: >>> TestCase.get_components(12345)
TestCase.get_plans
Description: Get the list of plans that this case is linked to. Params: $case_id - Integer/String: An integer representing the ID in the database Returns: Array: An array of test plan object hashes. Example: >>> TestCase.get_plans(12345)
TestCase.get_priority
Description: Get the priority matching the given id. Params: $id - Integer: ID of the priority in the database. Returns: Hash: Priority object hash. Example: >>> TestCase.get_priority(1)
TestCase.get_tags
Description: Get the list of tags attached to this case. Params: $case_id - Integer/String: An integer representing the ID in the database Returns: Array: An array of tag object hashes. Example: >>> TestCase.get_tags(12345)
TestCase.get_text
Description: The associated large text fields: Action,Expected Results,Setup,Breakdown
for a given version.
Params: $case_id - Integer/String: An integer representing the ID in the database
$version - Integer: (OPTIONAL) The version of the text you want returned.
Defaults to the latest.
Returns: Hash: case text object hash.
Example:
# Get all latest case text
>>> TestCase.get_text(12345)
# Get all case text with version 4
>>> TestCase.get_text(12345,4)
TestCase.link_plan
"
Description: Link test cases to the given plan.
Params: $case_ids - Integer/Array/String: An integer representing the ID in the database,or a string of comma separated case_ids.
$plan_ids - Integer/Array/String: An integer representing the ID in the database,an array of plan_ids,or a string of comma separated plan_ids.
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occurs
Example:
# Add case 1234 to plan id 54321
>>> TestCase.link_plan(1234,12345] to plan list [1234,5678]
>>> TestCase.link_plan([56789,5678])
# Add case ids list 56789 and 12345 to plan list 1234 and 5678 with String
>>> TestCase.link_plan('56789,5678')
TestCase.lookup_category_id_by_name
DEPRECATED - CONSIDERED HARMFUL Use Product.check_category instead
TestCase.lookup_category_name_by_id
DEPRECATED - CONSIDERED HARMFUL Use Product.get_category instead
TestCase.lookup_priority_id_by_name
DEPRECATED - CONSIDERED HARMFUL Use TestCase.check_priority instead
TestCase.lookup_priority_name_by_id
DEPRECATED - CONSIDERED HARMFUL Use TestCase.get_priority instead
TestCase.lookup_status_id_by_name
DEPRECATED - CONSIDERED HARMFUL Use TestCase.check_case_status instead
TestCase.lookup_status_name_by_id
DEPRECATED - CONSIDERED HARMFUL Use TestCase.get_case_status instead
TestCase.notification_add_cc
Description: Add email addresses to the notification CC list of specific TestCases
Params: $case_ids - Integer/Array: one or more TestCase IDs
$cc_list - Array: one or more Email addresses,which will be
added to each TestCase indicated by the case_ids.
Returns: JSON. When succeed,status is 0,and message maybe empty or
anything else that depends on the implementation. If something
wrong,status will be 1 and message will be a short description
to the error.
TestCase.notification_get_cc_list
Description: Return whole CC list of each TestCase
Params: $case_ids - Integer/Array: one or more TestCase IDs
Returns: An dictionary object with case_id as key and a list of CC as the value
Each case_id will be converted to a str object in the result.
TestCase.notification_remove_cc
Description: Remove email addresses from the notification CC list of specific TestCases
Params: $case_ids - Integer/Array: one or more TestCase IDs
$cc_list - Array: contians the email addresses that will
be removed from each TestCase indicated by case_ids.
Returns: JSON. When succeed,status will be 1 and message will be a short description
to the error.
TestCase.remove_component
Description: Removes selected component from the selected test case.
Params: $case_ids - Integer/Array/String: An integer representing the ID in the database,or a string of comma separated case_ids.
$component_ids - Integer: - The component ID to be removed.
Returns: Array: Empty on success.
Example:
# Remove component id 54321 from case 1234
>>> TestCase.remove_component(1234,54321)
# Remove component ids list [1234,12345]
>>> TestCase.remove_component([56789,5678])
# Remove component ids list '1234,12345' with String
>>> TestCase.remove_component('56789,5678')
TestCase.remove_tag
Description: Remove a tag from a case.
Params: $case_ids - Integer/Array/String: An integer or alias representing the ID in the database,or a string of comma separated case_ids.
$tags - String/Array - A single or multiple tag to be removed.
Returns: Array: Empty on success.
Example:
# Remove tag 'foo' from case 1234
>>> TestCase.remove_tag(1234,'foo')
# Remove tag 'foo' and bar from cases list [56789,12345]
>>> TestCase.remove_tag([56789,'bar'])
# Remove tag 'foo' and 'bar' from cases list '56789,12345' with String
>>> TestCase.remove_tag('56789,bar')
TestCase.store_text
Description: Update the large text fields of a case.
Params: $case_id - Integer: An integer or alias representing the ID in the database.
$action,$effect,$setup,$breakdown - String: Text for these fields.
[$author_id] = Integer/String: (OPTIONAL) The numeric ID or the login of the author.
Defaults to logged in user
Returns: Hash: case text object hash.
Example:
# Minimal
>>> TestCase.store_text(12345,'Action')
# Full arguments
>>> TestCase.store_text(12345,'Action','Effect','Setup','Breakdown',2260)
TestCase.unlink_plan
Description: Unlink a test case from the given plan. If only one plan is linked,this will delete
the test case.
Params: $case_ids - Integer/String: An integer or alias representing the ID in the database.
$plan_id - Integer: An integer representing the ID in the database.
Returns: Array: Array of plans hash still linked if any,empty if not.
Example:
>>> TestCase.unlink_plan(12345,137)
TestCase.update
Description: Updates the fields of the selected case or cases.
Params: $case_ids - Integer/String/Array
Integer: A single TestCase ID.
String: A comma separates string of TestCase IDs for batch
processing.
Array: An array of case IDs for batch mode processing
$values - Hash of keys matching TestCase fields and the new values
to set each field to.
Returns: Array: an array of case hashes. If the update on any particular
case Failed,the has will contain a ERROR key and the
message as to why it Failed.
+-----------------------+----------------+-----------------------------------------+
| Field | Type | Null |
+-----------------------+----------------+-----------------------------------------+
| case_status | Integer | Optional |
| product | Integer | Optional(required if changes category) |
| category | Integer | Optional |
| priority | Integer | Optional |
| default_tester | String/Integer | Optional(str - user_name,int - user_id)|
| estimated_time | String | Optional(2h30m30s(recommend) or HH:MM:SS|
| is_automated | Integer | Optional(0 - Manual,1 - Auto,2 - Both)|
| is_automated_proposed | Boolean | Optional |
| script | String | Optional |
| arguments | String | Optional |
| summary | String | Optional |
| requirement | String | Optional |
| alias | String | Optional |
| notes | String | Optional |
| extra_link | String | Optional(reference link)
+-----------------------+----------------+-----------------------------------------+
Example:
# Update alias to 'tcms' for case 12345 and 23456
>>> TestCase.update([12345,23456],{'alias': 'tcms'})
TestCasePlan.get
Description: Used to load an existing test-case-plan from the database.
Params: $case_id - Integer: An integer representing the ID of the test case in the database.
$plan_id - Integer: An integer representing the ID of the test plan in the database.
Returns: A blessed TestCasePlan object hash
Example:
>>> TestCasePlan.get(81307,3551)
TestCasePlan.update
Description: Updates the sortkey of the selected test-case-plan.
Params: $case_id - Integer: An integer representing the ID of the test case in the database.
$plan_id - Integer: An integer representing the ID of the test plan in the database.
$sortkey - Integer: An integer representing the ID of the sortkey in the database.
Returns: A blessed TestCasePlan object hash
Example:
# Update sortkey of selected test-case-plan to 450
>>> TestCasePlan.update(81307,3551,450)
TestCaseRun.add_comment
Description: Adds comments to selected test case runs.
Params: $case_run_ids - Integer/Array/String: An integer representing the ID in the database,an array of case_run_ids,or a string of comma separated case_run_ids.
$comment - String - The comment
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occured.
Example:
# Add comment 'foobar' to case run 1234
>>> TestCaseRun.add_comment(1234,'foobar')
# Add 'foobar' to case runs list [56789,12345]
>>> TestCaseRun.add_comment([56789,'foobar')
# Add 'foobar' to case runs list '56789,12345' with String
>>> TestCaseRun.add_comment('56789,'foobar')
TestCaseRun.attach_bug
Description: Add one or more bugs to the selected test cases.
Params: $values - Array/Hash: A reference to a hash or array of hashes with keys and values
matching the fields of the test case bug to be created.
+-------------------+----------------+-----------+------------------------+
| Field | Type | Null | Description |
+-------------------+----------------+-----------+------------------------+
| case_run_id | Integer | required | ID of Case |
| bug_id | Integer | required | ID of Bug |
| bug_system_id | Integer | required | 1: BZ(Default),2: JIRA|
| summary | String | Optional | Bug summary |
| description | String | Optional | Bug description |
+-------------------+----------------+-----------+------------------------+
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occured.
Example:
>>> TestCaseRun.attach_bug({
'case_run_id': 12345,})
TestCaseRun.attach_log
Description: Add new log link to TestCaseRun
Params: $caserun_id - Integer
$name - String: A short description to this new link,and accept 64 characters at most.
$url - String: The actual URL.
TestCaseRun.check_case_run_status
Params: $name - String: the status name.
Returns: Hash: Matching case run status object hash or error if not found.
Example:
>>> TestCaseRun.check_case_run_status('idle')
TestCaseRun.create
*** It always report - ValueError: invalid literal for int() with base 10: '' ***
Description: Creates a new Test Case Run object and stores it in the database.
Params: $values - Hash: A reference to a hash with keys and values
matching the fields of the test case to be created.
+--------------------+----------------+-----------+------------------------------------------------+
| Field | Type | Null | Description |
+--------------------+----------------+-----------+------------------------------------------------+
| run | Integer | required | ID of Test Run |
| case | Integer | required | ID of test case |
| build | Integer | required | ID of a Build in plan's product |
| assignee | Integer | Optional | ID of assignee |
| case_run_status | Integer | Optional | Defaults to "IDLE" |
| case_text_version | Integer | Optional | Default to latest case text version |
| notes | String | Optional | |
| sortkey | Integer | Optional | a.k.a. Index,Default to 0 |
+--------------------+----------------+-----------+------------------------------------------------+
Returns: The newly created object hash.
Example:
# Minimal test case parameters
>>> values = {
'run': 1990,'case': 12345,'build': 123,}
>>> TestCaseRun.create(values)
TestCaseRun.detach_bug
Description: Remove one or more bugs to the selected test case-runs.
Params: $case_run_ids - Integer/Array/String: An integer or alias representing the ID in the database,or a string of comma separated case_run_ids.
$bug_ids - Integer/Array/String: An integer representing the ID in the database,or a string of comma separated primary key of bug_ids.
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occured.
Example:
# Remove bug id 54321 from case 1234
>>> TestCaseRun.detach_bug(1234,12345]
>>> TestCaseRun.detach_bug([56789,12345' with String
>>> TestCaseRun.detach_bug('56789,5678')
TestCaseRun.detach_log
Description: Remove log link to TestCaseRun
Params: $case_run_id - Integer
$link_id - Integer: Id of LinkReference instance
TestCaseRun.filter
Description: Performs a search and returns the resulting list of test cases.
Params: $values - Hash: keys must match valid search fields.
+----------------------------------------------------------------+
| Case-Run Search Parameters |
+----------------------------------------------------------------+
| Key | Valid Values |
| case_run_id | Integer |
| assignee | ForeignKey: Auth.User |
| build | ForeignKey: Build |
| case | ForeignKey: Test Case |
| case_run_status | ForeignKey: Case Run Status |
| notes | String |
| run | ForeignKey: Test Run |
| tested_by | ForeignKey: Auth.User |
| running_date | Datetime |
| close_date | Datetime |
+----------------------------------------------------------------+
Returns: Object: Matching test cases are retuned in a list of hashes.
Example:
# Get all case runs contain 'TCMS' in case summary
>>> TestCaseRun.filter({'case__summary__icontain': 'TCMS'})
TestCaseRun.filter_count
Description: Performs a search and returns the resulting count of cases. Params: $query - Hash: keys must match valid search fields (see filter). Returns: Integer - total matching cases. Example: # See distinct_count()
TestCaseRun.get
Description: Used to load an existing test case-run from the database.
Params: $case_run_id - Integer: An integer representing the ID in
the database for this case-run.
Returns: A blessed TestCaseRun object hash
Example:
>>> TestCaseRun.get(1193)
TestCaseRun.get_bugs
Description: Get the list of bugs that are associated with this test case.
Params: $case_run_ids - Integer: An integer representing the ID in
the database for this case-run.
Returns: Array: An array of bug object hashes.
Example:
>>> TestCase.get_bugs(12345)
TestCaseRun.get_bugs_s
Description: Get the list of bugs that are associated with this test case.
Params: $run_id - Integer: An integer representing the ID of the test run in the database.
$case_id - Integer: An integer representing the ID of the test case in the database.
$build_id - Integer: An integer representing the ID of the test build in the database.
$environment_id - Optional Integer: An integer representing the ID of the environment in the database.
Returns: Array: An array of bug object hashes.
Example:
>>> TestCaseRun.get_bugs_s(3113,565,72,90)
TestCaseRun.get_case_run_status
Params: $case_run_status_id - Integer(Optional): ID of the status to return
Returns: Hash: Matching case run status object hash when your specific the case_run_status_id
or return all of case run status.
It will return error the case run status you specific id not found.
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)
TestCaseRun.get_completion_time
Description: Returns the time in seconds that it took for this case to complete.
Params: $case_run_id - Integer: An integer representing the ID in
the database for this case-run.
Returns: Integer: Seconds since run was started till this case was completed.
Or empty hash for insufficent data.
Example:
>>> TestCaseRun.get_completion_time(1193)
TestCaseRun.get_completion_time_s
Description: Returns the time in seconds that it took for this case to complete.
Params: $case_id - Integer: An integer representing the ID of the test case in the database.
$run_id - Integer: An integer representing the ID of the test run in the database.
$build_id - Integer: An integer representing the ID of the test build in the database.
$environment_id - Optional Integer: An integer representing the ID of the environment in the database.
Returns: Integer: Seconds since run was started till this case was completed.
Or empty hash for insufficent data.
Example:
>>> TestCaseRun.get_completion_time_s(3113,90)
TestCaseRun.get_history
*** FIXME: NOT IMPLEMENTED - Case history is different than before ***
Description: Get the list of case-runs for all runs this case appears in.
To limit this list by build or other attribute,see TestCaseRun.query
Params: $caserun_id - Integer: An integer representing the ID in
the database for this case-run.
Returns: Array: An array of case-run object hashes.
TestCaseRun.get_history_s
*** FIXME: NOT IMPLEMENTED - Case history is different than before ***
Description: 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.
Params: $case_id - Integer: An integer representing the ID of the test case in the database.
$run_id - Integer: An integer representing the ID of the test run in the database.
$build_id - Integer: An integer representing the ID of the test build in the database.
$environment_id - Integer: An integer representing the ID of the environment in the database.
Returns: Array: An array of case-run object hashes.
TestCaseRun.get_logs
Description: Get log links to TestCaseRun Params: $case_run_id - Integer:
TestCaseRun.get_s
Description: Used to load an existing test case from the database.
Params: $case_id - Integer: An integer representing the ID of the test case in the database.
$run_id - Integer: An integer representing the ID of the test run in the database.
$build_id - Integer: An integer representing the ID of the test build in the database.
$environment_id - Optional Integer: An integer representing the ID of the environment in the database.
Returns: A blessed TestCaseRun object hash
Example:
>>> TestCaseRun.get_s(3113,90)
TestCaseRun.lookup_status_id_by_name
DEPRECATED - CONSIDERED HARMFUL Use TestCaseRun.check_case_run_status instead
TestCaseRun.lookup_status_name_by_id
DEPRECATED - CONSIDERED HARMFUL Use TestCaseRun.get_case_run_status instead
TestCaseRun.update
Description: Updates the fields of the selected case-runs.
Params: $caserun_ids - Integer/String/Array
Integer: A single TestCaseRun ID.
String: A comma separates string of TestCaseRun IDs for batch
processing.
Array: An array of TestCaseRun IDs for batch mode processing
$values - Hash of keys matching TestCaseRun fields and the new values
to set each field to.
+--------------------+----------------+
| Field | Type |
+--------------------+----------------+
| build | Integer |
| assignee | Integer |
| case_run_status | Integer |
| notes | String |
| sortkey | Integer |
+--------------------+----------------+
Returns: Hash/Array: 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,{'assignee': 2206})
TestPlan.add_component
Description: Adds one or more components to the selected test plan.
Params: $plan_ids - Integer/Array/String: An integer representing the ID of the plan in the database.
$component_ids - Integer/Array/String - The component ID,an array of Component IDs
or a comma separated list of component IDs.
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occured.
Example:
# Add component id 54321 to plan 1234
>>> TestPlan.add_component(1234,5678] to plan list [56789,12345]
>>> TestPlan.add_component([56789,5678' to plan list '56789,12345' with String
>>> TestPlan.add_component('56789,5678')
TestPlan.add_tag
Description: Add one or more tags to the selected test plans.
Params: $plan_ids - Integer/Array/String: An integer representing the ID of the plan in the database,an arry of plan_ids,or a string of comma separated plan_ids.
$tags - String/Array - A single tag,or a comma separated list of tags.
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occured.
Example:
# Add tag 'foobar' to plan 1234
>>> TestPlan.add_tag(1234,'bar'] to plan list [12345,67890]
>>> TestPlan.add_tag([12345,67890] with String
>>> TestPlan.add_tag('12345,bar')
TestPlan.check_plan_type
Params: $name - String: the plan type.
Returns: Hash: Matching plan type object hash or error if not found.
Example:
>>> TestPlan.check_plan_type('regression')
@L_403_272@
Description: Creates a new Test Plan object and stores it in the database.
Params: $values - Hash: A reference to a hash with keys and values
matching the fields of the test plan to be created.
+-------------------------------------------+----------------+-----------+-------------------------------------------+
| Field | Type | Null | Description |
+-------------------------------------------+----------------+-----------+-------------------------------------------+
| product | Integer | required | ID of product |
| name | String | required | |
| type | Integer | required | ID of plan type |
| product_version(default_product_version) | Integer | required | ID of version,product_version(recommend),|
| | | | default_product_version will be deprecated|
| | | | in future release. |
| text | String | required | Plan documents,HTML acceptable. |
| parent | Integer | Optional | Parent plan ID |
| is_active | Boolean | Optional | 0: Archived 1: Active (Default 0) |
+-------------------------------------------+----------------+-----------+-------------------------------------------+
Returns: The newly created object hash.
Example:
# Minimal test case parameters
>>> values = {
'product': 61,'name': 'Testplan foobar','type': 1,'parent_id': 150,'default_product_version': 93,'text':'Testing TCMS',}
>>> TestPlan.create(values)
TestPlan.filter
Description: Performs a search and returns the resulting list of test plans.
Params: $values - Hash: keys must match valid search fields.
+------------------------------------------------------------+
| Plan Search Parameters |
+----------------------------------------------------------+
| Key | Valid Values |
| author | ForeignKey: Auth.User |
| attachment | ForeignKey: Attachment |
| case | ForeignKey: Test Case |
| create_date | DateTime |
| env_group | ForeignKey: Environment Group |
| name | String |
| plan_id | Integer |
| product | ForeignKey: Product |
| product_version | ForeignKey: Version |
| tag | ForeignKey: Tag |
| text | ForeignKey: Test Plan Text |
| type | ForeignKey: Test Plan Type |
+------------------------------------------------------------+
Returns: Array: Matching test plans are retuned in a list of plan object hashes.
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 12345,34567
>>> TestPlan.filter({'case__case_id__in': [12345,34567]})
TestPlan.filter_count
Description: Performs a search and returns the resulting count of plans. Params: $values - Hash: keys must match valid search fields (see filter). Returns: Integer - total matching plans. Example: # See distinct_count()
TestPlan.get
Description: Used to load an existing test plan from the database. Params: $id - Integer/String: An integer representing the ID of this plan in the database Returns: Hash: A blessed TestPlan object hash Example: >>> TestPlan.get(137)
TestPlan.get_all_cases_tags
Description: Get the list of tags attached to this plan's testcases. Params: $plan_id - Integer An integer representing the ID of this plan in the database Returns: Array: An array of tag object hashes. Example: >>> TestPlan.get_all_cases_tags(137)
TestPlan.get_change_history
*** FIXME: NOT IMPLEMENTED - History is different than before *** Description: Get the list of changes to the fields of this plan. Params: $plan_id - Integer: An integer representing the ID of this plan in the database Returns: Array: An array of hashes with changed fields and their details.
TestPlan.get_components
Description: Get the list of components attached to this plan. Params: $plan_id - Integer/String: An integer representing the ID in the database Returns: Array: An array of component object hashes. Example: >>> TestPlan.get_components(12345)
TestPlan.get_env_groups
Description: Get the list of env groups to the fields of this plan. Params: $plan_id - Integer: An integer representing the ID of this plan in the database Returns: Array: An array of hashes with env groups.
TestPlan.get_plan_type
Params: $id - Integer: ID of the plan type to return Returns: Hash: Matching plan type object hash or error if not found. Example: >>> TestPlan.get_plan_type(3)
TestPlan.get_product
Description: Get the Product the plan is assiciated with. Params: $plan_id - Integer: An integer representing the ID of the plan in the database. Returns: Hash: A blessed Product hash. Example: >>> TestPlan.get_product(137)
TestPlan.get_tags
Description: Get the list of tags attached to this plan. Params: $plan_id - Integer An integer representing the ID of this plan in the database Returns: Array: An array of tag object hashes. Example: >>> TestPlan.get_tags(137)
TestPlan.get_test_cases
Description: Get the list of cases that this plan is linked to. Params: $plan_id - Integer: An integer representing the ID of the plan in the database Returns: Array: An array of test case object hashes. Example: >>> TestPlan.get_test_cases(137)
TestPlan.get_test_runs
Description: Get the list of runs in this plan. Params: $plan_id - Integer: An integer representing the ID of this plan in the database Returns: Array: An array of test run object hashes. Example: >>> TestPlan.get_test_runs(plan_id)
TestPlan.get_text
Description: The plan document for a given test plan.
Params: $plan_id - Integer: An integer representing the ID of this plan in the database
$version - Integer: (OPTIONAL) The version of the text you want returned.
Defaults to the latest.
Returns: Hash: Text and author information.
Example:
# Get all latest case text
>>> TestPlan.get_text(137)
# Get all case text with version 4
>>> TestPlan.get_text(137,4)
TestPlan.import_case_via_XML
Description: Add cases to plan via XML file
Params: $plan_id - Integer: A single TestPlan ID.
$values - String: String which read from XML file object.
Returns: String: Success update cases
Example:
# Update product to 61 for plan 207 and 208
>>> fb = open('tcms.xml','rb')
>>> TestPlan.import_case_via_XML(3798,fb.read())
TestPlan.lookup_type_id_by_name
DEPRECATED - CONSIDERED HARMFUL Use TestPlan.check_plan_type instead
TestPlan.lookup_type_name_by_id
DEPRECATED - CONSIDERED HARMFUL Use TestPlan.get_plan_type instead
TestPlan.remove_component
Description: Removes selected component from the selected test plan.
Params: $plan_ids - Integer/Array/String: An integer representing the ID in the database,or a string of comma separated plan_ids.
$component_ids - Integer: - The component ID to be removed.
Returns: Array: Empty on success.
Example:
# Remove component id 54321 from plan 1234
>>> TestPlan.remove_component(1234,5678] from plan list [56789,12345]
>>> TestPlan.remove_component([56789,5678' from plan list '56789,12345' with String
>>> TestPlan.remove_component('56789,5678')
TestPlan.remove_tag
Description: Remove a tag from a plan.
Params: $plan_ids - Integer/Array/String: An integer or alias representing the ID in the database,or a string of comma separated plan_ids.
$tag - String - A single tag to be removed.
Returns: Array: Empty on success.
Example:
# Remove tag 'foo' from plan 1234
>>> TestPlan.remove_tag(1234,'foo')
# Remove tag 'foo' and 'bar' from plan list [56789,12345]
>>> TestPlan.remove_tag([56789,'bar'])
# Remove tag 'foo' and 'bar' from plan list '56789,12345' with String
>>> TestPlan.remove_tag('56789,bar')
TestPlan.store_text
Description: Update the document field of a plan.
Params: $plan_id - Integer: An integer representing the ID of this plan in the database.
$text - String: Text for the document. Can contain HTML.
[$author] = Integer: (OPTIONAL) The numeric ID or the login of the author.
Defaults to logged in user.
Returns: Hash: The new text object hash.
Example:
>>> TestPlan.store_text(1234,'Plan Text',2207)
TestPlan.update
Description: Updates the fields of the selected test plan.
Params: $plan_ids - Integer: A single TestPlan ID.
$values - Hash of keys matching TestPlan fields and the new values
to set each field to.
+-------------------------------------------+----------------+--------------------------------------------+
| Field | Type | Description |
+-------------------------------------------+----------------+--------------------------------------------+
| product | Integer | ID of product |
| name | String | |
| type | Integer | ID of plan type |
| product_version(default_product_version) | Integer | ID of version,|
| | | default_product_version will be deprecated |
| | | in future release. |
| owner | String/Integer | user_name/user_id |
| parent | Integer | Parent plan ID |
| is_active | Boolean | True/False |
| env_group | Integer | |
+-------------------------+----------------+--------------------------------------------------------------+
Returns: Hash: The updated test plan object.
Example:
# Update product to 61 for plan 207 and 208
>>> TestPlan.update([207,208],{'product': 61})
TestRun.add_cases
Description: Add one or more cases to the selected test runs.
Params: $run_ids - Integer/Array/String: An integer representing the ID in the database
an array of IDs,or a comma separated list of IDs.
$case_ids - Integer/Array/String: An integer or alias representing the ID in the database,an arry of case_ids or aliases,or a string of comma separated case_ids.
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occured.
Example:
# Add case id 54321 to run 1234
>>> TestRun.add_cases(1234,54321)
# Add case ids list [1234,5678] to run list [56789,12345]
>>> TestRun.add_cases([56789,5678])
# Add case ids list '1234,5678' to run list '56789,12345' with String
>>> TestRun.add_cases('56789,5678')
TestRun.add_tag
Description: Add one or more tags to the selected test runs.
Params: $run_ids - Integer/Array/String: An integer representing the ID in the database,an arry of run_ids,or a string of comma separated run_ids.
$tags - String/Array - A single tag,or a comma separated list of tags.
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occured.
Example:
# Add tag 'foobar' to run 1234
>>> TestPlan.add_tag(1234,'bar'] to run list [12345,bar')
TestRun.create
Description: Creates a new Test Run object and stores it in the database.
Params: $values - Hash: A reference to a hash with keys and values
matching the fields of the test run to be created.
+-------------------+----------------+-----------+---------------------------------------+
| Field | Type | Null | Description |
+-------------------+----------------+-----------+---------------------------------------+
| plan | Integer | required | ID of test plan |
| build | Integer/String | required | ID of Build |
| errata_id | Integer | Optional | ID of Errata |
| manager | Integer | required | ID of run manager |
| summary | String | required | |
| product | Integer | required | ID of product |
| product_version | Integer | required | ID of product version |
| default_tester | Integer | Optional | ID of run default tester |
| plan_text_version | Integer | Optional | |
| estimated_time | String | Optional | 2h30m30s(recommend) or HH:MM:SS Format|
| notes | String | Optional | |
| status | Integer | Optional | 0:RUNNING 1:STOPPED (default 0) |
| case | Array/String | Optional | list of case ids to add to the run |
| tag | Array/String | Optional | list of tag to add to the run |
+-------------------+----------------+-----------+---------------------------------------+
Returns: The newly created object hash.
Example:
>>> values = {'build': 384,'manager': 137,'plan': 137,'errata_id': 124,'product_version': 93,'summary': 'Testing XML-RPC for TCMS',}
>>> TestRun.create(values)
TestRun.env_value
Description: add/remove env values to the given runs,function is same as link_env_value/unlink_env_value
Params: $action - String: 'add' or 'remove'.
$run_ids - Integer/Array/String: An integer representing the ID in the database,an array of run_ids,or a string of comma separated run_ids.
$env_value_ids - Integer/Array/String: An integer representing the ID in the database,an array of env_value_ids,or a string of comma separated env_value_ids.
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occured.
Example:
# Add env value 13 to run id 8748
>>> TestRun.env_value('add',8748,13)
TestRun.filter
Description: Performs a search and returns the resulting list of test runs.
Params: $values - Hash: keys must match valid search fields.
+--------------------------------------------------------+
| Run Search Parameters |
+--------------------------------------------------------+
| Key | Valid Values |
| build | ForeignKey: Build |
| cc | ForeignKey: Auth.User |
| env_value | ForeignKey: Environment Value |
| default_tester | ForeignKey: Auth.User |
| run_id | Integer |
| manager | ForeignKey: Auth.User |
| notes | String |
| plan | ForeignKey: Test Plan |
| summary | String |
| tag | ForeignKey: Tag |
| product_version | ForeignKey: Version |
+--------------------------------------------------------+
Returns: Array: Matching test runs are retuned in a list of run object hashes.
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 12345,34567
>>> TestRun.filter({'case_run__case__case_id__in': [12345,34567]})
TestRun.filter_count
Description: Performs a search and returns the resulting count of runs. Params: $query - Hash: keys must match valid search fields (see filter). Returns: Integer - total matching runs. Example: # See distinct_count()
TestRun.get
Description: Used to load an existing test run from the database.
Params: $run_id - Integer: An integer representing the ID of the run
in the database
Returns: Hash: A blessed TestRun object hash
Example:
>>> TestRun.get(1193)
TestRun.get_bugs
*** FIXME: BUGGY IN SERIALISER - List can not be serialize. ***
Description: Get the list of bugs attached to this run.
Params: $run_ids - Integer/Array/String: An integer representing the ID in the database
an array of integers or a comma separated list of integers.
Returns: Array: An array of bug object hashes.
Example:
# Get bugs belong to ID 12345
>>> TestRun.get_bugs(12345)
# Get bug belong to run ids list [12456,23456]
>>> TestRun.get_bugs([12456,23456])
# Get bug belong to run ids list 12456 and 23456 with string
>>> TestRun.get_bugs('12456,23456')
@L_762_301@
*** FIXME: NOT IMPLEMENTED - History is different than before *** Description: Get the list of changes to the fields of this run. Params: $run_id - Integer: An integer representing the ID of the run in the database Returns: Array: An array of hashes with changed fields and their details.
TestRun.get_completion_report
*** FIXME: NOT IMPLEMENTED ***
Description: Get a report of the current status of the selected runs combined.
Params: $runs - Integer/Array/String: An integer representing the ID in the database
an array of integers or a comma separated list of integers.
Returns: Hash: A hash 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.
TestRun.get_env_values
Description: Get the list of env values to this run. Params: $run_id - Integer: An integer representing the ID of the run in the database Returns: Array: An array of tag object hashes. Example: >>> TestRun.get_env_values(8748)
TestRun.get_tags
Description: Get the list of tags attached to this run. Params: $run_id - Integer: An integer representing the ID of the run in the database Returns: Array: An array of tag object hashes. Example: >>> TestRun.get_tags(1193)
TestRun.get_test_case_runs
Description: Get the list of cases that this run is linked to.
Params: $run_id - Integer: An integer representing the ID in the database
for this run.
Returns: Array: An array of test case-run object hashes.
Example:
# Get all of case runs
>>> TestRun.get_test_case_runs(1193)
TestRun.get_test_cases
Description: Get the list of cases that this run is linked to.
Params: $run_id - Integer: An integer representing the ID in the database
for this run.
Returns: Array: An array of test case object hashes.
Example:
>>> TestRun.get_test_cases(1193)
TestRun.get_test_plan
Description: Get the plan that this run is associated with.
Params: $run_id - Integer: An integer representing the ID in the database
for this run.
Returns: Hash: A plan object hash.
Example:
>>> TestRun.get_test_plan(1193)
TestRun.link_env_value
Description: Link env values to the given runs.
Params: $run_ids - Integer/Array/String: An integer representing the ID in the database,or a string of comma separated env_value_ids.
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occured.
Example:
# Add env value 13 to run id 8748
>>> TestRun.link_env_value(8748,13)
TestRun.remove_cases
Description: Remove one or more cases from the selected test runs.
Params: $run_ids - Integer/Array/String: An integer representing the ID in the database
an array of IDs,or a string of comma separated case_ids.
Returns: Array: empty on success
Exception: When any exception is thrown on the server side,it will be
returned as JSON,which contains two items:
- status: 1.
- message: str,any message specific to the error on the server
Example:
# Remove case 54321 from run 1234
TestRun.remove_cases(1234,54321)
# Remove case ids list [1234,5678] from run list [56789,12345]
TestRun.remove_cases([56789,5678])
# Remove case ids list '1234,5678' from run list '56789,12345' with String
TestRun.remove_cases('56789,5678')
TestRun.remove_tag
Description: Remove a tag from a run.
Params: $run_ids - Integer/Array/String: An integer or alias representing the ID in the database,or a string of comma separated run_ids.
$tag - String - A single tag to be removed.
Returns: Array: Empty on success.
Example:
# Remove tag 'foo' from run 1234
>>> TestRun.remove_tag(1234,'foo')
# Remove tag 'foo' and 'bar' from run list [56789,12345]
>>> TestRun.remove_tag([56789,'bar'])
# Remove tag 'foo' and 'bar' from run list '56789,12345' with String
>>> TestRun.remove_tag('56789,bar')
TestRun.unlink_env_value
Description: Unlink env values to the given runs.
Params: $run_ids - Integer/Array/String: An integer representing the ID in the database,or a string of comma separated env_value_ids.
Returns: Array: empty on success or an array of hashes with failure
codes if a failure occured.
Example:
# Unlink env value 13 to run id 8748
>>> TestRun.unlink_env_value(8748,13)
TestRun.update
Description: Updates the fields of the selected test run.
Params: $run_ids - Integer/Array/String: An integer or alias representing the ID in the database,or a string of comma separated run_ids.
$values - Hash of keys matching TestRun fields and the new values
to set each field to. See params of TestRun.create for description
+-------------------+----------------+--------------------------------+
| Field | Type | Description |
+-------------------+----------------+--------------------------------+
| plan | Integer | TestPlan.plan_id |
| product | Integer | Product.id |
| build | Integer | Build.id |
| errata_id | Integer | Errata.id |
| manager | Integer | Auth.User.id |
| default_tester | Intege | Auth.User.id |
| summary | String | |
| estimated_time | TimeDelta | 2h30m30s(recommend) or HH:MM:SS|
| product_version | Integer | |
| plan_text_version | Integer | |
| notes | String | |
| status | Integer | 0:RUNNING 1:FINISHED |
+-------------------+----------------+ -------------------------------+
Returns: Hash: The updated test run object.
Example:
# Update status to finished for run 1193 and 1194
>>> TestRun.update([1193,1194],{'status': 1})
Testopia.api_version
Description: Return the API version of Nitrate.
Testopia.log_call
Log XMLRPC-specific invocations
This is copied from kobo.django.xmlrpc.decorators to add custom abitlities,so that we don't have to wait upstream to make the changes.
Usage::
from tcms.core.decorators import log_call
@log_call(namespace='TestNamespace')
def func(request):
return None
Testopia.nitrate_version
Description: Returns the version of Nitrate on this server.
Testopia.tcms_version
Description: Returns the version of Nitrate on this server.
Testopia.testopia_version
Description: Returns the version of Nitrate on this server.
User.filter
Description: Performs a search and returns the resulting list of test cases
Params: $query - Hash: keys must match valid search fields.
+------------------------------------------------------------------+
| Case Search Parameters |
+------------------------------------------------------------------+
| Key | Valid Values |
| id | Integer: ID |
| username | String: User name |
| first_name | String: User first name |
| last_name | String: User last name |
| email | String Email |
| is_active | Boolean: Return the active users |
| groups | ForeignKey: AuthGroup |
+------------------------------------------------------------------+
Returns: Array: Matching test cases are retuned in a list of hashes.
Example:
>>> User.filter({'username__startswith': 'x'})
User.get
Description: Used to load an existing test case from the database.
Params: $id - Integer/String: An integer representing the ID in the
database
Returns: A blessed User object Hash
Example:
>>> User.get(2206)
User.get_me
Description: Get the information of myself. Returns: A blessed User object Hash Example: >>> User.get_me()
User.join
Description: Add user to a group specified by name.
Returns: None
Raises: PermissionDenied
Object.DoesNotExist
Example:
>>> User.join('username','groupname')
User.update
Description: Updates the fields of the selected user. it also can change
the informations of other people if you have permission.
Params: $values - Hash of keys matching TestCase fields and the new
values to set each field to.
$id - Integer/String(Optional)
Integer: A single TestCase ID.
String: A comma string of User ID.
Default: The ID of myself
Returns: A blessed User object Hash
+--------------+--------+-----------------------------------------+
| Field | Type | Null |
+--------------+--------+-----------------------------------------+
| first_name | String | Optional |
| last_name | String | Optional(required if changes category) |
| email | String | Optional |
| password | String | Optional |
| old_password | String | required by password |
+--------------+--------+-----------------------------------------+
Example:
>>> User.update({'first_name': 'foo'})
>>> User.update({'password': 'foo','old_password': '123'})
>>> User.update({'password': 'foo','old_password': '123'},2206)
Version.get
Description: Retrieve XMLRPC's version Params: No parameters. Returns: A list that represents the version. Example: Version.get()原文链接：https://www.f2er.com/xml/296064.html
