TestRun.pm

- NAME
- EXTENDS
- DESCRIPTION
- METHODS
- SEE ALSO
- AUTHOR

# NAME

Bugzilla::Testopia::Webservice::TestRun

# EXTENDS

Bugzilla::Webservice

# DESCRIPTION

Provides methods for automated scripts to manipulate Testopia TestRuns

# METHODS

`add_tag($run_ids, $tags)`

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

       Params:      $run_ids - Integer/Array/String: An integer or alias representing the ID in the database,
                        an arry of run_ids or aliases, 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:     undef/Array: undef on success or an array of hashes with failure
                    codes if a failure occured.

`create($values)`

       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  |                                    |
        | notes             | String         | Optional  |                                    |
        | status            | Integer        | Optional  | 0:STOPPED 1: RUNNING (default 1)   |
        +-------------------+----------------+-----------+------------------------------------+

       Returns:     The newly created object hash.

`get($run_id)`

       Description: Used to load an existing test run from the database.

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

       Returns:     A blessed Bugzilla::Testopia::TestRun object hash

`get_change_history($run_id)`

       Description: Get the list of changes to the fields of this run.

       Params:      $run_id - Integer/String: An integer representing the ID in the database
                          or a string representing the unique alias for this run.

       Returns:     Array: An array of hashes with changed fields and their details.

`get_completion_report($runs)`

       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($run_id)`

       Description: Get the list of tags attached to this run.

       Params:      $run_id - Integer/String: An integer representing the ID in the database
                          or a string representing the unique alias for this run.

       Returns:     Array: An array of tag object hashes.

`get_test_case_runs($run_id, $current)`

       Description: Get the list of cases that this run is linked to.

       Params:      $run_id - Integer/String: 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 object hashes.

`get_test_cases($run_id)`

       Description: Get the list of cases that this run is linked to.

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

       Returns:     Array: An array of test case object hashes.

`get_test_plan($run_id)`

       Description: Get the plan that this run is associated with.

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

       Returns:     Hash: A plan object hash.

`list($query)`

       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    |
          +--------------------------------------------------------+

          +----------------------------------------------------+
          |                 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 hashes.

`remove_tag($run_id, $tag)`

       Description: Remove a tag from a run.

       Params:      $run_id - Integer/String: An integer or alias representing the ID in the database.

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

       Returns:     0 on success.

`update($ids, $values)`

       Description: Updates the fields of the selected test run.

       Params:      $ids - 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           |
                            +-------------------+----------------+
                            | plan_id           | Integer        |
                            | environment       | Integer/String |
                            | build             | Integer/String |
                            | manager           | Integer/String |
                            | summary           | String         |
                            | product_version   | String         |
                            | plan_text_version | Integer        |
                            | notes             | String         |
                            | status            | Integer        |
                            +-------------------+----------------+

       Returns:     Hash: The updated test run object.

# SEE ALSO

the Bugzilla::Testopia::TestRun manpage the Bugzilla::Webservice manpage

# AUTHOR

Greg Hendricks <ghendricks@novell.com>