Module: Endpoints

Included in:
TestRail::APIClient
Defined in:
lib/endpoints.rb

Instance Method Summary collapse

Instance Method Details

#add_case(section_id, opts = {}) ⇒ Object

Note:

For more information about custom fields, see guroc docs

Creates a new test case

Examples:

Code Example

@client.add_case(1, {"title":"testCaseName", "type_id":1})

Endpoint Example

index.php?/api/v2/add_case/1&title="foo"&type_id=1

Parameters:

  • section_id (int)

    The ID of the section the test case should be added to

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :title (string)

    The title of the test case (required)

  • :template_id (int)

    The ID of the template (field layout) (requires TestRail 5.2 or later)

  • :type_id (int)

    The ID of the case type

  • :priority_id (int)

    The ID of the case priority

  • :estimate (timespan)

    The estimate, e.g. “30s” or “1m 45s”

  • :milestone_id (int)

    The ID of the milestone to link to the test case

  • :refs (string)

    A comma-separated list of references/requirements

  • :custom_fields (varies)

    Custom fields are supported as well and must be submitted with their system name, prefixed with ‘custom_’

See Also:



97
98
99
# File 'lib/endpoints.rb', line 97

def add_case(section_id, opts = {})
  send_post("add_case/#{section_id.to_s}", opts)
end

#add_milestone(project_id, opts = {}) ⇒ Object

Add milestone to project id

Examples:

Endpoint

index.php?/api/v2/add_milestone/1

Code

client.add_milestone(1, {"name": "Release 2.0", "due_on": 1394596385})

Request

{"name": "Release 2.0", "due_on": 1394596385}

Return

If successful, this method returns the updated section using the same response format as get_section.

Parameters:

  • project_id (int)
  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • name (string)
  • description (string)
  • due_on (timestamp)
  • parent_id (int)
  • start_on (timestamp)

See Also:



412
413
414
# File 'lib/endpoints.rb', line 412

def add_milestone(project_id, opts = {})
  send_post("add_milestone/#{project_id.to_s}", opts)
end

#add_plan(project_id, opts = {}) ⇒ Object

Creates a new test plan.

Examples:

Endpoint

POST index.php?/api/v2/add_plan/1

Code

client.add_plan(1, {"name": "foo", "description": "bar"})

Request (plain)

{
  "name": "System test",
  "entries": [
    {
      "suite_id": 1,
      "name": "Custom run name",
      "assignedto_id": 1
    },
    {
      "suite_id": 1,
      "include_all": false,
      "case_ids": [1,2,3,5]
    }
  ]
}

Request (With configurations. See gurock docs for more info)

{
   "name": "System test",
   "entries": [
     {
       "suite_id": 1,
       "include_all": true,
       "config_ids": [1, 2, 4, 5, 6],
       "runs": [
         {
           "include_all": false,
           "case_ids": [1, 2, 3],
           "assignedto_id": 1,
           "config_ids": [2, 5]
         },
         {
           "include_all": false,
           "case_ids": [1, 2, 3, 5, 8],
           "assignedto_id": 2,
           "config_ids": [2, 6]
         }
        ..
       ]
     },
    ..
  ]
 }

Return

If successful, this method returns the updated section using the same response format as get_section.

Parameters:

  • project_id (Int)
  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • name (string)
  • description (string)
  • milestone_id (int)
  • entries (array)

See Also:



625
626
627
# File 'lib/endpoints.rb', line 625

def add_plan(project_id, opts = {})
  send_post("add_plan/#{project_id.to_s}", opts)
end

#add_plan_entry(plan_id, opts = {}) ⇒ Object

Add plan entries by plan id

Examples:

Endpoint

index.php?/api/v2/add_plan_entry/1

Code

options =
 {
   "suite_id": 1,
   "assignedto_id": 1,           // Default assignee
   "include_all": true,          // Default selection
   "config_ids": [1, 2, 4, 5, 6],
   "runs": [
     {
       "include_all": false, // Override selection
       "case_ids": [1, 2, 3],
       "config_ids": [2, 5]
     },
     {
       "include_all": false, // Override selection
       "case_ids": [1, 2, 3, 5, 8],
       "assignedto_id": 2,   // Override assignee
       "config_ids": [2, 6]
     }
    ..
   ]
 }
client.add_plan_entry(1, options)

Request

{
  "suite_id": 1,
  "assignedto_id": 1,           // Default assignee
  "include_all": true,          // Default selection
  "config_ids": [1, 2, 4, 5, 6],
  "runs": [
    {
      "include_all": false, // Override selection
      "case_ids": [1, 2, 3],
      "config_ids": [2, 5]
    },
    {
      "include_all": false, // Override selection
      "case_ids": [1, 2, 3, 5, 8],
      "assignedto_id": 2,   // Override assignee
      "config_ids": [2, 6]
    }
   ..
  ]
}

Return

If successful, this method returns the new test plan entry including test runs using the same response format as the entries field of get_plan, but for a single entry instead of a list of entries.

Parameters:

  • plan_id (Int)
  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • suite_id (int)
  • name (string)
  • description (string)
  • assignedto_id (int)
  • include_all (bool)
  • case_ids (array)
  • config_ids (array)
  • runs (array)

See Also:



690
691
692
# File 'lib/endpoints.rb', line 690

def add_plan_entry(plan_id, opts = {})
  send_post("add_plan_entry/#{plan_id.to_s}", opts)
end

#add_project(opts = {}) ⇒ Object

Creates a new project (admin status required)

Examples:

Endpoint Example

POST index.php?/api/v2/add_project

Code

client.add_project({"name": "foo", "announcement": "bar", "show_announcement": true, "suite_mode": 1})

Request

{"name": "foo", "announcement": "bar", "show_announcement": true, "suite_mode": 1}

Response

see get_project

Parameters:

  • opts (Hash) (defaults to: {})
  • [string] (Hash)

    a customizable set of options

  • [bool] (Hash)

    a customizable set of options

  • [int] (Hash)

    a customizable set of options

See Also:



827
828
829
# File 'lib/endpoints.rb', line 827

def add_project(opts = {})
  send_post("add_project", opts)
end

#add_result(test_id, opts = {}) ⇒ Object

Adds a new test result, comment or assigns a test. It’s recommended to use add_results instead if you plan to add results for multiple tests.

Examples:

Endpoint Example

POST index.php?/api/v2/add_result/1

Code

options = json
client.add_result(1, options)

Request

{
  "status_id": 5,
  "comment": "This test failed",
  "elapsed": "15s",
  "defects": "TR-7",
  "version": "1.0 RC1 build 3724",
  "custom_step_results": [
    {
      "content": "Step 1",
      "expected": "Expected Result 1",
      "actual": "Actual Result 1",
      "status_id": 1
    },
    {
      "content": "Step 2",
      "expected": "Expected Result 2",
      "actual": "Actual Result 2",
      "status_id": 2
    },
  ]
}

Return

see get_results

Parameters:

  • test_id (int)
  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • status_id (int)
  • comment (string)
  • version (string)
  • elapsed (timespan)
  • defects (string)
  • assignedto_id (int)
  • custom_checkbox (bool)
  • custom_dropdown (string)
  • custom_integer (int)
  • custom_milestone (int)
  • custom_multi-select (int)
  • custom_step_results (array)
  • custom_string (array)
  • custom_text (string)
  • custom_url (string)
  • custom_user (string)

See Also:



983
984
985
# File 'lib/endpoints.rb', line 983

def add_result(test_id, opts = {})
  send_post("add_result/#{test_id.to_s}", opts)
end

#add_result_for_case(run_id, case_id, opts = {}) ⇒ Object

Adds a new test result, comment or assigns a test (for a test run and case combination)

Examples:

Endpoint Example

POST index.php?/api/v2/add_result_for_case/1/1

Code

options = json
client.add_result(1, 1, options)

Request

{
  "status_id": 5,
  "comment": "This test failed",
  "elapsed": "15s",
  "defects": "TR-7",
  "version": "1.0 RC1 build 3724",
  "custom_step_results": [
    {
      "content": "Step 1",
      "expected": "Expected Result 1",
      "actual": "Actual Result 1",
      "status_id": 1
    },
    {
      "content": "Step 2",
      "expected": "Expected Result 2",
      "actual": "Actual Result 2",
      "status_id": 2
    },
  ]
}

Return

see get_results

Parameters:

  • run_id (int)
  • case_id (int)
  • opts (Hash) (defaults to: {})

    see add_result for options

See Also:



1022
1023
1024
# File 'lib/endpoints.rb', line 1022

def add_result_for_case(run_id, case_id, opts = {})
  send_post("add_result_for_case/#{run_id.to_s}/#{case_id.to_s}", opts)
end

#add_results(run_id, opts = {}) ⇒ Object

..

  ]
}

Examples:

Return

see get_results

See Also:



1068
1069
1070
# File 'lib/endpoints.rb', line 1068

def add_results(run_id, opts = {})
  send_post("add_results/#{run_id.to_s}", opts)
end

#add_results_for_cases(run_id, opts = {}) ⇒ Object

Adds one or more new test results, comments or assigns one or more tests (using the case IDs)

Examples:

Endpoint Example

index.php?/api/v2/add_results_for_cases/1

Code

opts =
client.add_results_for_cases(1, opts)

Request

Expects case_id instead of test_id
 {
   "results": [
     {
       "case_id": 1,
       "status_id": 5,
       "comment": "This test failed",
       "defects": "TR-7"
     },
     {
       "case_id": 2,
       "status_id": 1,
       "comment": "This test passed",
       "elapsed": "5m",
       "version": "1.0 RC1"
     },
     {
       "case_id": 1,
       "assignedto_id": 5,
       "comment": "Assigned this test to Joe"
     }
   ]
 }

Return

see get_results

Parameters:

  • run_id (int)
  • opts (Hash) (defaults to: {})
  • [varies] (Hash)

    a customizable set of options

See Also:



1109
1110
1111
# File 'lib/endpoints.rb', line 1109

def add_results_for_cases(run_id, opts = {})
  send_post("add_results_for_cases/#{run_id.to_s}", opts)
end

#add_run(project_id, opts = {}) ⇒ Object

Add run by suite id

Examples:

Endpoint Example

POST index.php?/api/v2/add_run/1

Code

opts = json
client.add_run(1, opts)

Request

{
  "suite_id": 1,
  "name": "This is a new test run",
  "assignedto_id": 5,
  "include_all": false,
  "case_ids": [1, 2, 3, 4, 7, 8]
}

Return

see get_run

Parameters:

  • project_id (int)
  • opts (Hash) (defaults to: {})
  • [int] (Hash)

    a customizable set of options

  • [string] (Hash)

    a customizable set of options

  • [bool] (Hash)

    a customizable set of options

  • [array] (Hash)

    a customizable set of options

See Also:



1245
1246
1247
# File 'lib/endpoints.rb', line 1245

def add_run(project_id, opts = {})
  send_post("add_run/#{project_id.to_s}", opts)
end

#add_section(project_id, opts = {}) ⇒ Object

Add section to suite

Examples:

Endpoint

POST index.php?/api/v2/add_section/1

Code

@client.add_section(1, {"suite_id": 2, "name": "Name of new section.", "parent_id": 1})

Request

{
  "name": "Name of new section.",
  "suite_id": 2,
  "parent_id": 1
}

Return

If successful, this method returns the updated section using the same response format as get_section.

Parameters:

  • project_id (int)
  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • suite_id (Int)
  • name (String)
  • parent_id (Int)

See Also:



313
314
315
# File 'lib/endpoints.rb', line 313

def add_section(project_id, opts = {})
  send_post("add_section/#{project_id.to_s}", opts)
end

#add_suite(project_id, opts = {}) ⇒ Object

Add a test suite

Examples:

Code

client.add_suite(1, {"name": "suite name", "description": "description text"})

Endpoint

index.php?/api/v2/add_suite/1

Request Body

{"name":"suite name","description": "description of test suite"}

Response

{ "name": "suite name",
  "description": "description text"
}

Parameters:

  • project_id (int)

    The id of the project containing suites

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :name (string)

    Name of new suite

  • :description (string)

    Description of new suite

See Also:



197
198
199
# File 'lib/endpoints.rb', line 197

def add_suite(project_id, opts = {})
  send_post("add_suite/#{project_id.to_s}", opts)
end

#close_plan(plan_id, opts = {}) ⇒ Object

Closes an existing test plan and archives its test runs & results. WARNING: This can not be undone.

Examples:

Endpoint

POST index.php?/api/v2/close_plan/1

Code

client.close_plan(1)

Response

If successful, this method returns the closed test plan using the same response format as get_plan.

Parameters:

  • plan_id (int)

See Also:



741
742
743
# File 'lib/endpoints.rb', line 741

def close_plan(plan_id, opts = {})
  send_post("close_plan/#{plan_id.to_s}", opts)
end

#close_run(run_id, opts = {}) ⇒ Object

Closes an existing test run and archives its tests & results

Examples:

Endpoint Example

POST index.php?/api/v2/close_run/1

Code

client.close_run(1)

Parameters:

  • run_id (int)

See Also:



1281
1282
1283
# File 'lib/endpoints.rb', line 1281

def close_run(run_id, opts = {})
  send_post("close_run/#{run_id.to_s}", opts)
end

#delete_case(case_id, opts = {}) ⇒ Object

Delete test case by case id

Examples:

Code Example

client.delete_case(1, {"title": "testCaseName", "type_id": 1})

Endpoint Example

index.php?/api/v2/delete_case/1

Body Example

{\"title\":\"testCaseName\",\"type_id\":1}

Parameters:

  • case_id (int)

    The id of the test case

  • opts (Hash) (defaults to: {})

See Also:



135
136
137
# File 'lib/endpoints.rb', line 135

def delete_case(case_id, opts = {})
  send_post("delete_case/#{case_id.to_s}", opts)
end

#delete_milestone(milestone_id, opts = {}) ⇒ Object

Add milestone to project id WARNING: Destructive

Examples:

Endpoint

index.php?/api/v2/delete_milestone/1

Code

client.delete_milestone(1)

Parameters:

  • milestone_id (Int)

See Also:



445
446
447
# File 'lib/endpoints.rb', line 445

def delete_milestone(milestone_id, opts = {})
  send_post("delete_milestone/#{milestone_id.to_s}", opts)
end

#delete_plan(plan_id, opts = {}) ⇒ Object

Deletes an existing test plan. WARNING: This can not be undone. Permenantly deletes ALL test runs and results in plan

Examples:

Endpoint

POST index.php?/api/v2/delete_plan/1

Code

client.delete_plan(1)

Response

If successful, this method returns the closed test plan using the same response format as get_plan.

Parameters:

  • plan_id (int)

See Also:



755
756
757
# File 'lib/endpoints.rb', line 755

def delete_plan(plan_id, opts = {})
  send_post("delete_plan/#{plan_id.to_s}", opts)
end

#delete_plan_entry(plan_id, entry_id, opts = {}) ⇒ Object

Deletes one or more existing test runs from a plan. WARNING: Deletes test results

Examples:

Endpoint

POST index.php?/api/v2/delete_plan_entry/1/1

Code

client.delete_plan_entry(1, 1)

Parameters:

  • plan_id (int)
  • entry_id (int)

See Also:



768
769
770
# File 'lib/endpoints.rb', line 768

def delete_plan_entry(plan_id, entry_id, opts = {})
  send_post("delete_plan_entry/#{plan_id.to_s}/#{entry_id.to_s}", opts)
end

#delete_project(project_id, opts = {}) ⇒ Object

Delete an existing project

Examples:

Endpoint Example

POST index.php?/api/v2/delete_project/1

Code

client.delete_project(1)

Parameters:

  • project_id (int)

    The project you want to delete

See Also:



861
862
863
# File 'lib/endpoints.rb', line 861

def delete_project(project_id, opts = {})
  send_post("delete_project/#{project_id.to_s}", opts)
end

#delete_run(run_id, opts = {}) ⇒ Object

Deletes an existing test run.

Examples:

Endpoint Example

POST index.php?/api/v2/delete_run/1

Code

client.delete_run(1)

Parameters:

  • run_id (int)

See Also:



1293
1294
1295
# File 'lib/endpoints.rb', line 1293

def delete_run(run_id, opts = {})
  send_post("delete_run/#{run_id.to_s}", opts)
end

#delete_section(section_id, opts = {}) ⇒ Object

Delete a section WARNING: Destructive

Examples:

Endpoint

POST index.php?/api/v2/delete_section/1

Code

client.delete_section(1)

Parameters:

  • section_id (Int)

See Also:



347
348
349
# File 'lib/endpoints.rb', line 347

def delete_section(section_id, opts = {})
  send_post("delete_section/#{section_id}", opts)
end

#delete_suite(suite_id, opts = {}) ⇒ Object

Delete a test suite

Examples:

Code

client.delete_suite(1)

Endpoint

index.php?/api/v2/delete_suite/1

Parameters:

  • suite_id (int)

    The suite id

See Also:



222
223
224
# File 'lib/endpoints.rb', line 222

def delete_suite(suite_id, opts = {})
  send_post("delete_suite/#{suite_id.to_s}", opts)
end

#get_case(case_id) ⇒ Object

Returns an existing test case

Examples:

Code

@client.get_case(1)

Endpoint

GET index.php?/api/v2/get_case/1

Response

{
  "created_by": 5,s
  "created_on": 1392300984,
  "custom_expected": "..",
  "custom_preconds": "..",
  "custom_steps": "..",
  "custom_steps_separated": [
      {
          "content": "Step 1",
          "expected": "Expected Result 1"
      },
      {
          "content": "Step 2",
          "expected": "Expected Result 2"
     }
  ],
  "estimate": "1m 5s",
  "estimate_forecast": null,
  "id": 1,
  "milestone_id": 7,
  "priority_id": 2,
  "refs": "RF-1, RF-2",
  "section_id": 1,
  "suite_id": 1,
  "title": "Change document attributes (author, title, organization)",
  "type_id": 4,
  "updated_by": 1,
  "updated_on": 1393586511
}

Parameters:

  • case_id (int)

    The id of the test case you want

See Also:



43
44
45
# File 'lib/endpoints.rb', line 43

def get_case(case_id)
  send_get("get_case/#{case_id}")
end

#get_cases(project_id, opts = {}) ⇒ Object

Returns a list of test cases for a test suite or specific section in a test suite.

Examples:

Code Example

@client.get_cases(1, {"suite_id":1, "section_id":1})

Endpoint Example

GET index.php?/api/v2/get_cases/1&suite_id=1&section_id=1

Response Example

[
 { "id": 1, "title": "..", .. },
 { "id": 2, "title": "..", .. },
 ..
]

Parameters:

  • project_id (int)

    The id of the project that contains your tests

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :suite_id (int)

    The ID of the test suite (optional if the project is operating in single suite mode)

  • :section_id (int)

    The ID of the section (optional)

  • :created_after (unix timestamp)

    Only return test cases created after this date (as UNIX timestamp).

  • :created_before (unix timestamp)

    Only return test cases created before this date (as UNIX timestamp).

  • :created_by (int(list))

    A comma-separated list of creators (user IDs) to filter by.

  • :milestone_id (int(list))

    A comma-separated list of milestone IDs to filter by (not available if the milestone field is disabled for the project).

  • :priority_id (int(list))

    A comma-separated list of priority IDs to filter by.

  • :template_id (int(list))

    A comma-separated list of template IDs to filter by (requires TestRail 5.2 or later)

  • :type_id (int(list))

    A comma-separated list of case type IDs to filter by.

  • :updated_after (unix timestamp)

    Only return test cases updated after this date (as UNIX timestamp).

  • :updated_before (unix timestamp)

    Only return test cases updated before this date (as UNIX timestamp).

  • :updated_by (int(list))

    A comma-separated list of users who updated test cases to filter by.

See Also:



74
75
76
77
# File 'lib/endpoints.rb', line 74

def get_cases(project_id, opts = {})
  options = param_stringify(opts)
  send_get("get_cases/#{project_id.to_s}&#{options}")
end

#get_milestone(milestone_id) ⇒ Object

Get milestone by milestone_id

Examples:

Endpoint

GET index.php?/api/v2/get_milestone/1

Code

client.get_milestone(1)

Return

{
   "completed_on": 1389968184,
   "description": "...",
   "due_on": 1391968184,
   "id": 1,
   "is_completed": true,
   "name": "Release 1.5",
   "project_id": 1,
   "url": "http://<server>/testrail/index.php?/milestones/view/1"
}

Parameters:

  • milestone_id (Int)

See Also:



372
373
374
# File 'lib/endpoints.rb', line 372

def get_milestone(milestone_id)
  send_get("get_milestone/#{milestone_id.to_s}")
end

#get_milestones(project_id, opts = {}) ⇒ Object

Get project milestones by project id

Examples:

Endpoint

index.php?/api/v2/get_milestones/1&is_completed=0&is_started=1

Code

client.get_milestones(1, {"is_completed": 0, "is_started": 1})

Return

[{ "id": 1, "name": "foo", .. }, { "id": 1, "name": "bar, .. }]

Parameters:

  • project_id (int)
  • opts (Hash) (defaults to: {})

    (optional)

See Also:



389
390
391
392
# File 'lib/endpoints.rb', line 389

def get_milestones(project_id, opts = {})
  options = param_stringify(opts)
  send_get("get_milestones/#{project_id.to_s}&#{options}")
end

#get_plan(plan_id) ⇒ Object

Get plan by id

Examples:

Endpoint

GET index.php?/api/v2/get_plan/1

Code

client.get_plan(1)

Return

{
   "assignedto_id": null,
   "blocked_count": 2,
   "completed_on": null,
   "created_by": 1,
   "created_on": 1393845644,
   "custom_status1_count": 0,
   "custom_status2_count": 0,
   "custom_status3_count": 0,
   "custom_status4_count": 0,
   "custom_status5_count": 0,
   "custom_status6_count": 0,
   "custom_status7_count": 0,
   "description": null,
   "entries": [
   {
     "id": "3933d74b-4282-4c1f-be62-a641ab427063",
     "name": "File Formats",
     "runs": [
     {
       "assignedto_id": 6,
       "blocked_count": 0,
       "completed_on": null,
       "config": "Firefox, Ubuntu 12",
       "config_ids": [
         2,
         6
       ],
       "custom_status1_count": 0,
       "custom_status2_count": 0,
       "custom_status3_count": 0,
       "custom_status4_count": 0,
       "custom_status5_count": 0,
       "custom_status6_count": 0,
       "custom_status7_count": 0,
       "description": null,
       "entry_id": "3933d74b-4282-4c1f-be62-a641ab427063",
       "entry_index": 1,
       "failed_count": 2,
       "id": 81,
       "include_all": false,
       "is_completed": false,
       "milestone_id": 7,
       "name": "File Formats",
       "passed_count": 2,
       "plan_id": 80,
       "project_id": 1,
       "retest_count": 1,
       "suite_id": 4,
       "untested_count": 3,
       "url": "http://<server>/testrail/index.php?/runs/view/81"
     },
     {
       ..
     }
     ],
     "suite_id": 4
   }
   ],
   "failed_count": 2,
   "id": 80,
   "is_completed": false,
   "milestone_id": 7,
   "name": "System test",
   "passed_count": 5,
   "project_id": 1,
   "retest_count": 1,
   "untested_count": 6,
   "url": "http://<server>/testrail/index.php?/plans/view/80"
 }

Parameters:

  • plan_id (Int)

See Also:



530
531
532
# File 'lib/endpoints.rb', line 530

def get_plan(plan_id)
  send_get("get_plan/#{plan_id.to_s}")
end

#get_plans(project_id, opts = {}) ⇒ Object

Get plans in project by project id

Examples:

Endpoint

index.php?/api/v2/get_plans/:project_id

Endpoint

GET index.php?/api/v2/get_plans/1

Code

Request

{"is_completed":1, "milestone_id": 1 }

Return

{

}

Parameters:

  • project_id (int)
  • opts (Hash) (defaults to: {})
  • project_id (Int)
  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • created_after (timestamp)
  • created_before (timestamp)
  • created_by (string)
  • is_completed (bool)
  • limit (int)
  • offset (int)
  • milestone_id (int(list))

See Also:



561
562
563
564
565
# File 'lib/endpoints.rb', line 561

def get_plans(project_id, opts = {})
  options = param_stringify(opts)
  puts options
  send_get("get_plans/#{project_id.to_s}&#{options}")
end

#get_project(project_id, opts = {}) ⇒ Object

Get project by project id

Examples:

Endpoint Example

GET index.php?/api/v2/get_project/1

Code

client.get_project(1)

Parameters:

  • project_id (int)

See Also:



782
783
784
785
# File 'lib/endpoints.rb', line 782

def get_project(project_id, opts = {})
  options = param_stringify(opts)
  send_get("get_project/#{project_id.to_s}&#{options}")
end

#get_projects(opts = {}) ⇒ Object

Get all projects

Examples:

Endpoint Example

GET index.php?/api/v2/get_projects

Code Example [get all projects]

client.get_projects

Code Example [get active projects]

client.get_projects({'is_completed':0})

Code Example [get completed projects]

client.get_projects({'is_completed':1})

Response Example

[
 { "id": 1, "name": "Project1", ... },
 { "id": 2, "name": "Project2", ... },
 ..
]

Parameters:

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :is_completed (bool)

    1 == completed projects, 2 == active projects

See Also:



806
807
808
809
# File 'lib/endpoints.rb', line 806

def get_projects(opts = {})
  options = param_stringify(opts)
  send_get("get_projects&#{options}")
end

#get_results(test_id, opts = {}) ⇒ Object

Returns a list of test results for a test

Examples:

Endpoint Example

GET index.php?/api/v2/get_results/1&status_id=4,5&limit=10

Code

client.get_results(1, {"status_id": 4, "limit": 10})

Request

{"status_id": 4, "limit": 10}

Return

Parameters:

  • test_id (int)
  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • limit (int)
  • offset (int)
  • status_id (int(list))

See Also:



882
883
884
885
# File 'lib/endpoints.rb', line 882

def get_results(test_id, opts = {})
  options = param_stringify(opts)
  send_get("get_results/#{test_id.to_s}&#{options}")
end

#get_results_for_case(run_id, case_id, opts = {}) ⇒ Object

Returns a list of test results for a test run and case combination

Examples:

Endpoint Example

GET index.php?/api/v2/get_results_for_case/1/2

Code

client.get_results_for_case(1, 2, {"status_id": 4, "limit": 10})

Request

{"status_id": 4, "limit": 10}

Return

see get_results

Parameters:

  • run_id (int)
  • case_id (int)
  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • limit (int)
  • offset (int)
  • status_id (int(list))

See Also:



904
905
906
907
# File 'lib/endpoints.rb', line 904

def get_results_for_case(run_id, case_id, opts = {})
  options = param_stringify(opts)
  send_get("get_results_for_case/#{run_id.to_s}/#{case_id.to_s}&#{options}")
end

#get_results_for_run(run_id, opts = {}) ⇒ Object

Returns a list of test results for a test run

Examples:

Endpoint Example

GET index.php?/api/v2/get_results_for_run/1

Code

client.get_results_for_run(1, {"created_after": 12345, "created_before": 12345, "created_by": 1, "limit": 5, "status_id": 1})

Request

{"created_after": 12345, "created_before": 12345, "created_by": 1, "limit": 5, "status_id": 1}

Return

see get_results

Parameters:

  • run_id (int)
  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • created_after (timestamp)
  • created_before (timestamp)
  • created_by (int(list))
  • limit (int)
  • offset (int)
  • status_id (int(list))

See Also:



928
929
930
931
# File 'lib/endpoints.rb', line 928

def get_results_for_run(run_id, opts = {})
  options = param_stringify(opts)
  send_get("get_results_for_run/#{run_id.to_s}&#{options}")
end

#get_run(run_id) ⇒ Object

Get run by run id

Examples:

Endpoint Example

GET index.php?/api/v2/get_run/1

Code

client.get_run(1)

Return

{
  "assignedto_id": 6,
  "blocked_count": 0,
  "completed_on": null,
  "config": "Firefox, Ubuntu 12",
  "config_ids": [
    2,
    6
  ],
  "created_by": 1,
  "created_on": 1393845644,
  "custom_status1_count": 0,
  "custom_status2_count": 0,
  "custom_status3_count": 0,
  "custom_status4_count": 0,
  "custom_status5_count": 0,
  "custom_status6_count": 0,
  "custom_status7_count": 0,
  "description": null,
  "failed_count": 2,
  "id": 81,
  "include_all": false,
  "is_completed": false,
  "milestone_id": 7,
  "name": "File Formats",
  "passed_count": 2,
  "plan_id": 80,
  "project_id": 1,
  "retest_count": 1,
  "suite_id": 4,
  "untested_count": 3,
  "url": "http://<server>/testrail/index.php?/runs/view/81"
}

Parameters:

  • run_id (int)

See Also:



1157
1158
1159
# File 'lib/endpoints.rb', line 1157

def get_run(run_id)
  send_get("get_run/#{run_id.to_s}")
end

#get_runs(project_id, opts = {}) ⇒ Object

Get runs by project id

Examples:

Endpoint Example

index.php?/api/v2/get_runs/1

Code

opts = json
client.get_runs(1, opts)

Return

{
  "assignedto_id": 6,
  "blocked_count": 0,
  "completed_on": null,
  "config": "Firefox, Ubuntu 12",
  "config_ids": [
    2,
    6
  ],
  "created_by": 1,
  "created_on": 1393845644,
  "custom_status1_count": 0,
  "custom_status2_count": 0,
  "custom_status3_count": 0,
  "custom_status4_count": 0,
  "custom_status5_count": 0,
  "custom_status6_count": 0,
  "custom_status7_count": 0,
  "description": null,
  "failed_count": 2,
  "id": 81,
  "include_all": false,
  "is_completed": false,
  "milestone_id": 7,
  "name": "File Formats",
  "passed_count": 2,
  "plan_id": 80,
  "project_id": 1,
  "retest_count": 1,
  "suite_id": 4,
  "untested_count": 3,
  "url": "http://<server>/testrail/index.php?/runs/view/81"
}

Parameters:

  • run_id (int)
  • opts (hash) (defaults to: {})
  • [timestamp] (Hash)

    a customizable set of options

  • [int(list)] (Hash)

    a customizable set of options

  • [bool] (Hash)

    a customizable set of options

  • [int] (Hash)

    a customizable set of options

See Also:



1213
1214
1215
1216
# File 'lib/endpoints.rb', line 1213

def get_runs(project_id, opts = {})
  options = param_stringify(opts)
  send_get("get_runs/#{project_id.to_s}&#{options}")
end

#get_section(section_id) ⇒ Object

Return section by id

Examples:

Endpoint

GET index.php?/api/v2/get_section/1

Code

client.get_section(2)

Return

{
  "depth": 0,
  "description": null,
  "display_order": 1,
  "id": 1,
  "name": "section name",
  "parent_id": 1,
  "suite_id": 2
}

Parameters:

  • section_id (int)

See Also:



246
247
248
# File 'lib/endpoints.rb', line 246

def get_section(section_id)
  send_get("get_section/#{section_id.to_s}")
end

#get_sections(project_id, opts = {}) ⇒ Object

Get sections for suite

Examples:

Endpoint

GET index.php?/api/v2/get_sections/1&suite_id=2

Code

client.get_sections(1, {"suite_id":2})

Return

[
  {
    "depth": 0,
    "display_order": 1,
    "id": 1,
    "name": "Prerequisites",
    "parent_id": null,
    "suite_id": 1
  },
  {
    "depth": 0,
    "display_order": 2,
    "id": 2,
    "name": "Documentation & Help",
    "parent_id": null,
    "suite_id": 1
  },
  {
    "depth": 1, // A child section
    "display_order": 3,
    "id": 3,
    "name": "Licensing & Terms",
    "parent_id": 2, // Points to the parent section
    "suite_id": 1
  },
  ..
]

Parameters:

  • project_id (int)
  • opts (Hash) (defaults to: {})

See Also:



288
289
290
291
# File 'lib/endpoints.rb', line 288

def get_sections(project_id, opts = {})
  options = param_stringify(opts)
  send_get("get_sections/#{project_id.to_s}&#{options}")
end

#get_suite(suite_id) ⇒ Object

Return suite by suite id

Examples:

Code

client.get_suit(1)

Endpoint

index.php?/api/v2/get_suite/1

Response

{
  "description": "..",
  "id": 1,
  "name": "Setup & Installation",
  "project_id": 1,
  "url": "http://<server>/testrail/index.php?/suites/view/1"
}

Parameters:

  • suite_id (int)

    The suite id

  • opts (Hash)

See Also:



158
159
160
# File 'lib/endpoints.rb', line 158

def get_suite(suite_id)
  send_get("get_suite/#{suite_id.to_s}")
end

#get_suites(project_id) ⇒ Object

Return all suites in project by project id

Examples:

Code

client.get_suites(1)

Endpoint

index.php?/api/v2/get_suites/:project_id

Response

[
  { "id": 1, "name": "Setup & Installation", .. },
  { "id": 2, "name": "Document Editing", .. }
]

Parameters:

  • opts (Hash)
  • project_id (int)

    The id of the project that contains your tests

See Also:



176
177
178
# File 'lib/endpoints.rb', line 176

def get_suites(project_id)
  send_get("get_suites/#{project_id.to_s}")
end

#get_test(test_id) ⇒ Object

Returns an existing test

Examples:

Endpoint Example

GET index.php?/api/v2/get_test/1

Code

client.get_test(1)

Return

{
  "assignedto_id": 1,
  "case_id": 1,
  "custom_expected": "..",
  "custom_preconds": "..",
  "custom_steps_separated": [
    {
      "content": "Step 1",
      "expected": "Expected Result 1"
    },
    {
      "content": "Step 2",
      "expected": "Expected Result 2"
    }
  ],
  "estimate": "1m 5s",
  "estimate_forecast": null,
  "id": 100,
  "priority_id": 2,
  "run_id": 1,
  "status_id": 5,
  "title": "Verify line spacing on multi-page document",
  "type_id": 4
}

Parameters:

  • test_id (int)

See Also:



1332
1333
1334
# File 'lib/endpoints.rb', line 1332

def get_test(test_id)
  send_get("get_test/#{test_id.to_s}")
end

#get_tests(run_id, opts = {}) ⇒ Object

Returns an existing test

Examples:

Endpoint Example

GET index.php?/api/v2/get_tests/1

Code

client.get_tests(1, {"status_id": 1})

Return

[
  {
    "id": 1,
    "title": "Test conditional formatting with basic value range",
  },
  {
    "id": 2,
    "title": "Verify line spacing on multi-page document",
  },
]

Parameters:

  • run_id (int)
  • opts (hash) (defaults to: {})
  • [int(list)] (Hash)

    a customizable set of options

See Also:



1357
1358
1359
1360
# File 'lib/endpoints.rb', line 1357

def get_tests(run_id, opts = {})
  options = param_stringify(opts)
  send_get("get_tests/#{run_id.to_s}&#{options}")
end

#update_case(case_id, opts = {}) ⇒ Object

Update test result by case id

Examples:

Code

client.update_case(1, {"title": "testCaseName", "type_id": 1})

Endpoint

index.php?/api/v2/update_case/1

Body

{\"title\":\"testCaseName\",\"type_id\":1}

Parameters:

  • case_id (int)

    The id of the test case

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :title (string)

    The title of the test case (required)

  • :template_id (int)

    The ID of the template (field layout) (requires TestRail 5.2 or later)

  • :type_id (int)

    The ID of the case type

  • :priority_id (int)

    The ID of the case priority

  • :estimate (timespan)

    The estimate, e.g. “30s” or “1m 45s”

  • :milestone_id (int)

    The ID of the milestone to link to the test case

  • :refs (string)

    A comma-separated list of references/requirements

  • :custom_fields (varies)

    Custom fields are supported as well and must be submitted with their system name, prefixed with ‘custom_’

See Also:



120
121
122
# File 'lib/endpoints.rb', line 120

def update_case(case_id, opts = {})
  send_post("update_case/#{case_id.to_s}", opts)
end

#update_milestone(milestone_id, opts = {}) ⇒ Object

Add milestone to project id

Examples:

Endpoint

index.php?/api/v2/update_milestone/:milestone_id

Code

client.update_milestone(1, {"is_completed": false, "is_started": false, "parent_id": 1, "start_on": 1394596385})

Request

{"is_completed": false, "is_started": false, "parent_id": 1, "start_on": 1394596385}

Return

If successful, this method returns the updated section using the same response format as get_section.

Parameters:

  • milestone_id (Int)
  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • is_completed (bool)
  • is_started (bool)
  • parent_id (int)
  • start_on (timestamp)

See Also:



433
434
435
# File 'lib/endpoints.rb', line 433

def update_milestone(milestone_id, opts = {})
  send_post("update_milestone/#{milestone_id.to_s}", opts)
end

#update_plan(plan_id, opts = {}) ⇒ Object

Updates an existing test plan (partial updates are supported, i.e. you can submit and update specific fields only).

Examples:

Endpoint

POST index.php?/api/v2/update_plan/1

Code

client.update_plan(1, {"name": "foo", "description": "bar"})

Return

If successful, this method returns the updated test plan using the same response format as get_plan.

Parameters:

  • plan_id (Int)
  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • name (string)
  • description (string)
  • milestone_id (int)

See Also:



708
709
710
# File 'lib/endpoints.rb', line 708

def update_plan(plan_id, opts = {})
  send_post("update_plan/#{plan_id.to_s}", opts)
end

#update_plan_entry(plan_id, entry_id, opts = {}) ⇒ Object

Updates one or more existing test runs in a plan (partial updates are supported, i.e. you can submit and update specific fields only).

Examples:

Endpoint

POST index.php?/api/v2/update_plan_entry/1/1

Code

client.update_plan_entry(1, 1, {"name": "foo", "description": "bar"})

Parameters:

  • plan_id (int)
  • entry_id (int)
  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • name (string)
  • description (string)
  • assignedto_id (int)
  • include_all (bool)
  • case_ids (array)

See Also:



727
728
729
# File 'lib/endpoints.rb', line 727

def update_plan_entry(plan_id, entry_id, opts = {})
  send_post("update_plan_entry/#{plan_id.to_s}/#{entry_id.to_s}", opts)
end

#update_project(project_id, opts = {}) ⇒ Object

Updates an existing project (admin status required; partial updates are supported, i.e. you can submit and update specific fields only).

Examples:

Endpoint Example

POST index.php?/api/v2/update_project/:project_id

Code

client.update_project(1, {"name": "foo", "announcement": "bar", "show_announcement": true, "suite_mode": 1, "is_completed": true})

Request

{"name": "foo", "announcement": "bar", "show_announcement": true, "suite_mode": 1, "is_completed": true}

Response

see get_project

Parameters:

  • project_id (int)

    ID of project to update

  • opts (Hash) (defaults to: {})
  • [string] (Hash)

    a customizable set of options

  • [bool] (Hash)

    a customizable set of options

  • [int] (Hash)

    a customizable set of options

See Also:



849
850
851
# File 'lib/endpoints.rb', line 849

def update_project(project_id, opts = {})
  send_post("update_project/#{project_id.to_s}", opts)
end

#update_run(run_id, opts = {}) ⇒ Object

Updates existing test run

Examples:

Endpoint Example

POST index.php?/api/v2/update_run/1

Code

opts = json
client.update_run(1, opts)

Request

{
  "name": "This is a test run",
  "include_all": false
}

Parameters:

  • run_id (int)
  • opts (Hash) (defaults to: {})
  • [string] (Hash)

    a customizable set of options

  • [int] (Hash)

    a customizable set of options

  • [bool] (Hash)

    a customizable set of options

  • [array] (Hash)

    a customizable set of options

See Also:



1269
1270
1271
# File 'lib/endpoints.rb', line 1269

def update_run(run_id, opts = {})
  send_post("update_run/#{run_id.to_s}", opts)
end

#update_section(section_id, opts = {}) ⇒ Object

Update a section

Examples:

Endpoint

POST index.php?/api/v2/update_section/1

Code

index.php?/api/v2/update_section/1

Request

{
  "name": "updated section name",
  "description": "updated description"
}

Return

If successful, this method returns the updated section using the same response format as get_section.

Parameters:

  • section_id (Int)
  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • description (string)
  • name (string)

See Also:



335
336
337
# File 'lib/endpoints.rb', line 335

def update_section(section_id, opts = {})
  send_post("update_section/#{section_id.to_s}", opts)
end

#update_suite(suite_id, opts = {}) ⇒ Object

update a test suite

Examples:

Endpoint Example

index.php?/api/v2/update_suite/:suite_id

Parameters:

  • suite_id (int)

    The suite id

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :name (string)

    Name of new suite

  • :description (string)

    Description of new suite

See Also:



210
211
212
# File 'lib/endpoints.rb', line 210

def update_suite(suite_id, opts = {})
  send_post("update_suite/#{suite_id.to_s}", opts)
end