NAME

Testopia::Webservice::TestRun

EXTENDS

Bugzilla::Webservice

DESCRIPTION

Provides methods for automated scripts to manipulate Testopia TestRuns

METHODS

add_cases
 Description: Add one or more cases to the selected test runs.

 Params:      $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.

              $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.
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.
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_id           | Integer        | Required  | ID of test plan                    |
  | environment       | Integer/String | Required  | ID or Name of Environment          |
  | build             | Integer/String | Required  | ID or Name of Build                |
  | manager           | Integer/String | Required  | ID or Login of run manager         |
  | summary           | String         | Required  |                                    |
  | product_version   | String         | Optional  | Defaults to plan's version         |
  | plan_text_version | Integer        | Optional  |                                    |
  | target_completion | Integer        | Optional  | Targetted Completion percentage    |
  | target_pass       | Integer        | Optional  | Targetted Pass percentage          |
  | notes             | String         | Optional  |                                    |
  | status            | Integer        | Optional  | 0:STOPPED 1: RUNNING (default 1)   |
  | cases             | Array/String   | Optional  | list of case ids to add to the run |
  +-------------------+----------------+-----------+------------------------------------+

 Returns:     The newly created object hash.
get
 Description: Used to load an existing test run from the database.

 Params:      $id - Integer: An integer representing the ID of the run in the database

 Returns:     Hash: A blessed Bugzilla::Extension::Testopia::TestRun object hash
get_bugs
 Description: Get the list of bugs attached to this run.

 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:     Array: An array of bug object hashes.
get_change_history
 Description: Get the list of changes to the fields of this run.

 Params:      $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.
get_completion_report
 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.
get_tags
 Description: Get the list of tags attached to this run.

 Params:      $id - Integer: An integer representing the ID of the run in the database

 Returns:     Array: An array of tags .
get_test_case_runs
 Description: Get the list of cases that this run is linked to.

 Params:      $id - Integer: An integer representing the ID in the database
                    for this run.

              $current - Boolean: 1 to only include the current set (what is displayed
                    in the web page) 0: to return all, current and historical.

 Returns:     Array: An array of test case-run object hashes.
get_test_cases
 Description: Get the list of cases that this run is linked to.

 Params:      $id - Integer: An integer representing the ID in the database
                    for this run.

 Returns:     Array: An array of test case object hashes.
get_case_tags
 Description: Get the list of tags associated with the cases in this run.

 Params:      $id - Integer: An integer representing the ID of the run in the database

 Returns:     Array: An array of tag object hashes.
get_test_plan
 Description: Get the plan that this run is associated with.

 Params:      $id - Integer: An integer representing the ID in the database
                    for this run.

 Returns:     Hash: A plan object hash.
list
 Description: Performs a search and returns the resulting list of test runs.

 Params:      $query - Hash: keys must match valid search fields.

    +--------------------------------------------------------+
    |                 Run Search Parameters                  |
    +--------------------------------------------------------+
    |        Key          |          Valid Values            |
    | build               | String: Product Name             |
    | build_id            | Integer                          |
    | environment         | String: Product Name             |
    | environment_id      | Integer                          |
    | manager             | A bugzilla login (email address) |
    | manager_type        | (select from email_variants)     |
    | milestone           | String                           |
    | notes               | String                           |
    | notes_type          | (select from query_variants)     |
    | plan_id             | comma separated integers         |
    | product             | String: Product Name             |
    | product_id          | Integer                          |
    | run_id              | comma separated integers         |
    | run_status          | 1: RUNNING 0: STOPPED            |
    | summary             | String                           |
    | summary_type        | (select from query_variants)     |    
    | tags                | String                           |
    | tags_type           | (select from tag_variants)       |
    | type_id             | Integer                          |
    | version             | String: Product version          |
    +--------------------------------------------------------+

    +--------------------------------------------------------+
    |                Paging and Sorting                      |
    +--------------------------------------------------------+
    |      Key       |            Description                |
    | dir            | "ASC" or "DESC"                       |
    | order          | field to sort by                      |
    +--------------------------------------------------------+
    | page_size      | integer: how many per page            |
    | page           | integer: page number                  |
    |            +++++++ OR +++++++                          |
    | start          | integer: Start with which record      |
    | limit          | integer: limit to how many            |
    +--------------------------------------------------------+
    | viewall        | 1: returns all records 0: first 25    |
    +--------------------------------------------------------+
      * The default is to only return 25 records at a time

    +----------------------------------------------------+
    |                 query_variants                     |
    +----------------+-----------------------------------+
    |      Key       |            Description            |
    | allwordssubstr | contains all of the words/strings |
    | anywordssubstr | contains any of the words/strings |
    | substring      | contains the string               |
    | casesubstring  | contains the string (exact case)  |
    | allwords       | contains all of the words         |
    | anywords       | contains any of the words         |
    | regexp         | matches the regexp                |
    | notregexp      | doesn't match the regexp          |
    +----------------+-----------------------------------+

            +-------------------------------------+
            |            email_variants           |
            +--------------+----------------------+
            |      Key     |      Description     |
            | substring    | contains             |
            | exact        | is                   |
            | regexp       | matches regexp       |
            | notregexp    | doesn't match regexp |
            +--------------+----------------------+

    +----------------------------------------------------+
    |                    tag_variants                    |
    +----------------+-----------------------------------+
    |      Key       |            Description            |
    | anyexact       | is tagged with                    |
    | allwordssubstr | contains all of the words/strings |
    | anywordssubstr | contains any of the words/strings |
    | substring      | contains the string               |
    | casesubstring  | contains the string (exact case)  |
    | regexp         | matches the regexp                |
    | notregexp      | doesn't match the regexp          |
    | allwords       | contains all of the words         |
    | anywords       | contains any of the words         |
    | nowords        | contains none of the words        | 
    +----------------------------------------------------+

 Returns:     Array: Matching test runs are retuned in a list of run object hashes.
list_count
 Description: Performs a search and returns the resulting count of runs.

 Params:      $query - Hash: keys must match valid search fields (see list).

 Returns:     Integer - total matching runs.
remove_tag
 Description: Remove a tag from a run.

 Params:      $run_id - Integer: An integer representing the ID in the database.

              $tag - String - A single tag to be removed. 

 Returns:     0 on success.
update
 Description: Updates the fields of the selected test run.

 Params:      $id - Integer: A single TestRun ID.

              $values - Hash of keys matching TestRun fields and the new values 
              to set each field to. See L<create> for description
                      +-------------------+----------------+
                      | Field             | Type           |
                      +-------------------+----------------+
                      | id (readonly)     | Integer        |
                      | plan_id           | Integer        |
                      | environment       | Integer/String |
                      | build             | Integer/String |
                      | manager           | Integer/String |
                      | summary           | String         |
                      | product_version   | String         |
                      | plan_text_version | Integer        |
                      | target_completion | Integer        |
                      | target_pass       | Integer        |
                      | notes             | String         |
                      | status            | Integer        |
                      +-------------------+----------------+

 Returns:     Hash: The updated test run object.

SEE ALSO

Bugzilla::Webservice

AUTHOR

Greg Hendricks <ghendricks@novell.com>