TestCaseRun.pm

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

# NAME

Bugzilla::Testopia::Webservice::TestCaseRun

# EXTENDS

Bugzilla::Webservice

# DESCRIPTION

Provides methods for automated scripts to manipulate Testopia TestCaseRuns.

# SYNOPSIS

Test case-runs are the mapping of a test case in a given run for a particular build and environment. There are therefore two ways to refer to a given case-run:

        By ID: The unique case_run_id
        By Combination: $run_id, $case_id, $build_id, $environment_id

TestCaseRun methods are therefore overloaded to support either of these two methods of looking up the case-run you are interested in.

EXAMPLE:

TestCaseRun->`get($caserun_id)` TestCaseRun->get($run_id, $case_id, $build_id, $environment_id)

# METHODS

`attach_bug($caserun_id, $bug_ids)`

       Description: Add one or more bugs to the selected test case-runs.

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

                    $bug_ids - Integer/Array/String: An integer or alias representing the ID in the database,
                        an array of bug_ids or aliases, or a string of comma separated bug_ids.

       Returns:     undef.

`attach_bug($run_id, $case_id, $build_id, $environment_id, $bug_ids)`

       Description: Add one or more bugs to the selected test case-runs.

       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.

                    $bug_ids - Integer/Array/String: An integer or alias representing the ID in the database,
                        an array of bug_ids or aliases, or a string of comma separated bug_ids.

       Returns:     undef.

`create($values)`

       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_id             | Integer        | Required  | Test Run Number                                |
        | case_id            | Integer/String | Required  | ID or alias of test case                       |
        | build              | Integer/String | Required  | ID or name of a Build in plan's product        |
        | environment        | Integer/String | Required  | ID or name of an Environment in plan's product |
        | assignee           | Integer/String | Optional  | Defaults to test case default tester           |
        | status             | String         | Optional  | Defaults to "IDLE"                             |
        | case_text_version  | Integer        | Optional  |                                                |
        | notes              | String         | Optional  |                                                |
        | sortkey            | Integer        | Optional  | a.k.a. Index                                   |
        +--------------------+----------------+-----------+------------------------------------------------+
          Valid statuses include: IDLE, PASSED, FAILED, RUNNING, PAUSED, BLOCKED

       Returns:     The newly created object hash.

`detach_bug($caserun_id, $bug_id)`

       Description: Remove a bug from a test case-run.

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

                    $bug_ids - Integer/Array/String: An integer or alias representing the ID in the database,
                        an array of bug_ids or aliases, or a string of comma separated bug_ids.

       Returns:     undef.

`detach_bug($run_id, $case_id, $build_id, $environment_id, $bug_id)`

       Description: Remove a bug from a test case-run.

       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.

                    $bug_id - Integer: An integer or alias representing the ID of
                        the bug in the database,

       Returns:     undef.

`get($caserun_id)`

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

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

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

`get($run_id, $case_id, $build_id, $environment_id)`

       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 - Integer: An integer representing the ID of the environment in the database.

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

`get_bugs($caserun_id)`

       Description: Get the list of bugs that are associated with this test case.

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

       Returns:     Array: An array of bug object hashes.

`get_bugs($run_id, $case_id, $build_id, $environment_id)`

       Description: Get the list of bugs that are associated with this test case.

       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 bug object hashes.

`get_completion_time($caserun_id)`

       Description: Get the list of components attached to this case.

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

       Returns:     Array: An array of component object hashes.

`get_completion_time($run_id, $case_id, $build_id, $environment_id)`

       Description: Get the list of components attached to this case.

       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 component object hashes.

`get_history($caserun_id)`

       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::list.

       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.

`get_history($run_id, $case_id, $build_id, $environment_id)`

       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::list.

       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.

`list($query)`

       Description: Performs a search and returns the resulting list of test cases.

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

          +--------------------------------------------------------+
          |               Case-Run Search Parameters               |
          +--------------------------------------------------------+
          |        Key          |          Valid Values            |
          | andor               | 1: Author AND tester, 0: OR      |
          | assignee            | A bugzilla login (email address) |
          | assignee_type       | (select from email_variants)     |
          | build               | String                           |
          | build_id            | Integer                          |
          | case_id             | comma separated integers         |
          | case_run_status     | String: Status                   |
          | case_run_status_id  | Integer: Status                  |
          | case_summary        | String: Requirement              |
          | case_summary_type   | (select from query_variants)     |
          | category            | String: Category Name            |
          | category_id         | Integer                          |
          | component           | String: Component Name           |
          | environment         | String                           |
          | environment_id      | Integer                          |
          | isactive            | 0: Only show current 1: show all |
          | isautomated         | 1: true 0: false                 |
          | milestone           | String                           |
          | notes               | String                           |
          | notes_type          | (select from query_variants)     |
          | plan_id             | comma separated integers         |
          | priority            | String: Priority                 |
          | priority_id         | Integer                          |
          | product             | String                           |
          | product_id          | Integer                          |
          | requirement         | String: Requirement              |
          | requirement_type    | (select from query_variants)     |
          | run_id              | comma separated integers         |
          | run_product_version | String                           |
          | run_status          | 1: RUNNING 0: STOPPED            |
          | tags                | String                           |
          | tags_type           | (select from tag_variants)       |
          | testedby            | A bugzilla login (email address) |
          | testedby_type       | (select from email_variants)     |
          +--------------------------------------------------------+

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

          +----------------------------------------------------+
          |                 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 cases are retuned in a list of hashes.

`lookup_status_name_by_id`

       Params:      $id - Integer: ID of the case status to return

       Returns:     String: the status name.

`lookup_status_id_by_name`

       Params:      $name - String: the status name.

       Returns:     Integer: ID of the case status.

`update($caserun_ids, $values)`

       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/String |
                            | environment        | Integer/String |
                            | assignee           | Integer/String |
                            | status             | String         |
                            | notes              | String         |
                            | sortkey            | Integer        |
                            | update_bugs        | Boolean        | 1: Reopen bugs on FAILED 0: Don't change bug status
                            +--------------------+----------------+

       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.

`update($run_id, $case_id, $build_id, $environment_id, $values)`

       Description: Updates the fields of the selected case-run.

       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.

                    $values - Hash of keys matching TestCaseRun fields and the new values
                    to set each field to. See above.

       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.

# SEE ALSO

the Bugzilla::Testopia::TestCaseRun manpage the Bugzilla::Webservice manpage

# AUTHOR

Greg Hendricks <ghendricks@novell.com>