TestCase.pm

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

# NAME

Bugzilla::Testopia::Webservice::TestCase

# EXTENDS

Bugzilla::Webservice

# DESCRIPTION

Provides methods for automated scripts to manipulate Testopia TestCases

# METHODS

`add_component($case_ids, $component_ids)`

       Description: Adds one or more components to the selected test cases.

       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.

                    $component_ids - Integer/Array/String - The component ID, an array of Component IDs,
                        or a comma separated list of component IDs

       Returns:     undef/Array: undef on success or an array of hashes with failure
                    codes if a failure occured.

`add_tag($case_ids, $tags)`

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

       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.

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

`add_to_run($case_ids, $run_ids)`

       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:     undef/Array: undef on success or an array of hashes with failure
                    codes if a failure occured.

`attach_bug($case_ids, $bug_ids)`

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

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

                    $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/Array: undef on success or an array of hashes with failure
                    codes if a failure occured.

`calculate_average_time($case_id)`

       Description: Returns an average time for completion accross all runs.

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

       Returns:     String: Time in "HH:MM:SS" format.

`create($values)`

       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            |
        +-------------------+----------------+-----------+------------------------+
        | status            | Integer/String | Required  | ID or Name of status   |
        | category          | Integer/String | Required  | ID or Name of Category |
        | priority          | Integer/String | Required  | ID or Name of Priority |
        | summary           | String         | Required  |                        |
        | plans             | Array/String   | Required  | List of plan_ids       |
        | default_tester    | Integer/String | Optional  | ID or Login of tester  |
        | estimated_time    | String         | Optional  | HH:MM:SS Format        |
        | isautomated       | Boolean        | Optional  | Defaults to False (0)  |
        | sortkey           | Integer        | Optional  |                        |
        | script            | String         | Optional  |                        |
        | arguments         | String         | Optional  |                        |
        | requirement       | String         | Optional  |                        |
        | alias             | String         | Optional  | Must be unique         |
        | action            | String         | Optional  |                        |
        | effect            | String         | Optional  | ExpectedResult         |
        | setup             | String         | Optional  |                        |
        | breakdown         | String         | Optional  |                        |
        | dependson         | Array/String   | Optional  | String Comma separated |
        | blocks            | Array/String   | Optional  | String Comma separated |
        | tags              | Array/String   | Optional  | String Comma separated |
        | bugs              | Array/String   | Optional  | String Comma separated |
        | plans             | Array/String   | Optional  | String Comma separated |
        | components        | Array/String   | Optional  | String Comma separated |
        +-------------------+----------------+-----------+------------------------+

       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.

`detach_bug($case_id, $bug_id)`

       Description: Remove a bug from a test case.

       Params:      $case_id - Integer/String: An integer or alias 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:     0 on success.

`get($case_id)`

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

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

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

`get_bugs($case_id)`

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

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

       Returns:     Array: An array of bug object hashes.

`get_case_run_history($case_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/String: An integer representing the ID in the database
                          or a string representing the unique alias for this case.

       Returns:     Array: An array of case-run object hashes.

`get_change_history($case_id)`

       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
                          or a string representing the unique alias for this case.

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

`get_components($case_id)`

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

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

       Returns:     Array: An array of component object hashes.

`get_plans($case_id)`

       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
                          or a string representing the unique alias for this case.

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

`get_tags($case_id)`

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

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

       Returns:     Array: An array of tag object hashes.

`get_text($case_id, $version)`

       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
                          or a string representing the unique alias for this case.

                    $version - Integer: (OPTIONAL) The version of the text you want returned.
                          Defaults to the latest.

       Returns:     Hash: Text fields and values.

`link_plan($case_ids, $plan_id)`

       Description: Link test cases to the given plan.

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

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

       Returns:     Array: Array of failure codes or an empty array.

`list($query)`

       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            |
          | andor               | 1: Author AND tester, 0: OR      |
          | author              | A bugzilla login (email address) |
          | author_type         | (select from email_variants)     |
          | case_id             | comma separated integers         |
          | case_status         | String: Status                   |
          | case_status_id      | Integer: Status                  |
          | category            | String: Category Name            |
          | category_id         | Integer                          |
          | component           | String: Component Name           |
          | default_tester      | A bugzilla login (email address) |
          | default_tester_type | (select from email_variants)     |
          | isautomated         | 1: true 0: false                 |
          | plan_id             | comma separated integers         |
          | priority            | String: Priority                 |
          | priority_id         | Integer                          |
          | product             | String: Product Name             |
          | product_id          | Integer                          |
          | requirement         | String: Requirement              |
          | requirement_type    | (select from query_variants)     |
          | run_id              | comma separated integers         |
          | script              | String                           |
          | script_type         | (select from query_variants)     |
          | summary             | String                           |
          | summary_type        | (select from query_variants)     |
          | tags                | String                           |
          | tags_type           | (select from tag_variants)       |
          | tcaction            | String                           |
          | tcaction_type       | (select from query_variants)     |
          | tceffect            | String                           |
          | tceffect_type       | (select from query_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_category_name_by_id` DEPRECATED - CONSIDERED HARMFUL Use Testopia::Product::get_category instead
`lookup_category_id_by_name` DEPRECATED - CONSIDERED HARMFUL Use Testopia::Product::check_category instead
`lookup_priority_name_by_id`

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

       Returns:     String: the status name.

`lookup_priority_id_by_name`

       Params:      $name - String: the status name.

       Returns:     Integer: ID of the case status.

`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.

`remove_component($case_id, $component_id)`

       Description: Removes selected component from the selected test case.

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

                    $component_id - Integer: - The component ID to be removed.

       Returns:     Array: Empty on success.

`remove_tag($case_id, $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 aliases, or a string of comma separated case_ids.

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

       Returns:     Array: Empty on success.

`store_text($case_id, $action, $effect, $setup, $breakdown, [$author_id])`

       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:     Array: Empty on success.

`unlink_plan($case_id, $plan_id)`

       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:     undef/Array: Array of plans still linked if any, undef if not.

`update($ids, $values)`

       Description: Updates the fields of the selected case or cases.

       Params:      $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:     Hash/Array: In the case of a single case it is returned. If a
                    list was passed, it returns 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           |
                            +-------------------+----------------+
                            | status            | Integer/String |
                            | category          | Integer/String |
                            | priority          | Integer/String |
                            | default_tester    | Integer/String |
                            | estimated_time    | String         |
                            | isautomated       | Boolean        |
                            | sortkey           | Integer        |
                            | script            | String         |
                            | arguments         | String         |
                            | summary           | String         |
                            | requirement       | String         |
                            | alias             | String         |
                            | dependson         | Array/String   |
                            | blocks            | Array/String   |
                            +-------------------+----------------+

# SEE ALSO

the Bugzilla::Testopia::TestCase manpage the Bugzilla::Webservice manpage

# AUTHOR

Greg Hendricks <ghendricks@novell.com>