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
- Tag.get_tags
- 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', 'description': 'None', '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')
Product.filter
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, an array of case_ids, 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, 12345], [1234, 5678]) # Add component ids list '1234, 5678' to cases list '56789, 12345' with String >>> TestCase.add_component('56789, 12345', '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, an array of case_ids, 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', 'bar'] to cases list [12345, 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, an array of case_ids, 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, 12345], [1234, 5678]) # Add case ids list 56789 and 12345 to run list 1234 and 5678 with String >>> TestCase.add_to_run('56789, 12345', '1234, 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, 610, 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, an array of case_ids, 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, 12345], [1234, 5678]) # Remove bug ids list '1234, 5678' from cases list '56789, 12345' with String >>> TestCase.detach_bug('56789, 12345', '1234, 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, 23456, 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, an array of case_ids, 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, 54321) # Add case ids list [56789, 12345] to plan list [1234, 5678] >>> TestCase.link_plan([56789, 12345], [1234, 5678]) # Add case ids list 56789 and 12345 to plan list 1234 and 5678 with String >>> TestCase.link_plan('56789, 12345', '1234, 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 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.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, an array of case_ids, 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, 5678] from cases list [56789, 12345] >>> TestCase.remove_component([56789, 12345], [1234, 5678]) # Remove component ids list '1234, 5678' from cases list '56789, 12345' with String >>> TestCase.remove_component('56789, 12345', '1234, 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, an array of case_ids, 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, 12345], ['foo', 'bar']) # Remove tag 'foo' and 'bar' from cases list '56789, 12345' with String >>> TestCase.remove_tag('56789, 12345', 'foo, 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, 12345], 'foobar') # Add 'foobar' to case runs list '56789, 12345' with String >>> TestCaseRun.add_comment('56789, 12345', '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, 'bug_id': 67890, 'bug_system_id': 1, 'summary': 'Testing TCMS', 'description': 'Just foo and bar', })
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, an array of case_run_ids, or a string of comma separated case_run_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 >>> TestCaseRun.detach_bug(1234, 54321) # Remove bug ids list [1234, 5678] from cases list [56789, 12345] >>> TestCaseRun.detach_bug([56789, 12345], [1234, 5678]) # Remove bug ids list '1234, 5678' from cases list '56789, 12345' with String >>> TestCaseRun.detach_bug('56789, 12345', '1234, 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, 565, 72, 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, 565, 72, 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, 23456], {'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, 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')
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, 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 plan 1234 >>> TestPlan.add_tag(1234, 'foobar') # Add tag list ['foo', 'bar'] to plan list [12345, 67890] >>> TestPlan.add_tag([12345, 67890], ['foo', 'bar']) # Add tag list ['foo', 'bar'] to plan list [12345, 67890] with String >>> TestPlan.add_tag('12345, 67890', 'foo, 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')
TestPlan.create
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, 23456, 34567 >>> TestPlan.filter({'case__case_id__in': [12345, 23456, 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, an array of plan_ids, 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, 54321) # Remove component ids list [1234, 5678] from plan list [56789, 12345] >>> TestPlan.remove_component([56789, 12345], [1234, 5678]) # Remove component ids list '1234, 5678' from plan list '56789, 12345' with String >>> TestPlan.remove_component('56789, 12345', '1234, 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, an array of plan_ids, 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, 12345], ['foo', 'bar']) # Remove tag 'foo' and 'bar' from plan list '56789, 12345' with String >>> TestPlan.remove_tag('56789, 12345', 'foo, 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, product_version(recommend), | | | | 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, 12345], [1234, 5678]) # Add case ids list '1234, 5678' to run list '56789, 12345' with String >>> TestRun.add_cases('56789, 12345', '1234, 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, 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 run 1234 >>> TestPlan.add_tag(1234, 'foobar') # Add tag list ['foo', 'bar'] to run list [12345, 67890] >>> TestPlan.add_tag([12345, 67890], ['foo', 'bar']) # Add tag list ['foo', 'bar'] to run list [12345, 67890] with String >>> TestPlan.add_tag('12345, 67890', 'foo, 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': 61, '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, 23456, 34567 >>> TestRun.filter({'case_run__case__case_id__in': [12345, 23456, 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')
TestRun.get_change_history
*** 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, 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.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 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 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, 12345], [1234, 5678]) # Remove case ids list '1234, 5678' from run list '56789, 12345' with String TestRun.remove_cases('56789, 12345', '1234, 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, an array of run_ids, 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, 12345], ['foo', 'bar']) # Remove tag 'foo' and 'bar' from run list '56789, 12345' with String >>> TestRun.remove_tag('56789, 12345', 'foo, 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, 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: # 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, an array of run_ids, 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()