Test Cases - Docs

Create and manage test cases for your products.

Get test case

Retrieve a specific test case by ID.

Endpoint: GET /products/{product_id}/test_cases/{test_case_id}

Parameters:

product_id (number, required) - ID of the Product
test_case_id (number, required) - ID of the Test Case

Example Request:

1curl -X GET "https://api.test.io/customer/v2/products/1/test_cases/123" \
2  -H "Authorization: Token YOUR_API_TOKEN"

Response: 200 OK

Returns the test case object. See the response shape in Create a bulk of test cases below.

List test cases

Returns all visible (non-hidden) test cases for a product.

Endpoint: GET /products/{product_id}/test_cases

Parameters:

product_id (number, required) - ID of the Product

Example Request:

1curl -X GET "https://api.test.io/customer/v2/products/1/test_cases" \
2  -H "Authorization: Token YOUR_API_TOKEN"

Response: 200 OK

Returns an array of test case objects. See the response shape in Create a bulk of test cases below.

Create a bulk of test cases

Create multiple test cases at once.

Endpoint: POST /products/{product_id}/test_cases

Parameters:

product_id (number, required) - ID of the Product

Request Body:

test_cases (array[TestCase], required) - Array of test case objects

TestCase Object:

title (string, required) - Title of the test case
feature_id (number, required) - ID of the Feature the test case belongs to
test_case_steps (array[Step], required) - Array of step objects
target_idx (string, optional) - Reference of the test case in other system

Step Object:

description (string, required) - Description of the step
target_idx (string, optional) - Reference of the test case step in other system

Example Request:

1curl -X POST "https://api.test.io/customer/v2/products/1/test_cases" \
2  -H "Authorization: Token YOUR_API_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "test_cases": [
6      {
7        "title": "Login Test",
8        "feature_id": 123,
9        "test_case_steps": [
10          {
11            "description": "Navigate to login page"
12          },
13          {
14            "description": "Enter credentials"
15          },
16          {
17            "description": "Click login"
18          }
19        ]
20      }
21    ]
22  }'

Response: 201 Created

Returns an array of created test case objects.

In the response, the steps field is returned as steps (not test_case_steps as in the request). Each step object in the response also includes id, test_case_id, and target_idx fields.

Update test case

Updates the top-level fields of a test case, and optionally its test case steps.

Endpoint: PUT /products/{product_id}/test_cases/{test_case_id}

Parameters:

product_id (number, required) - ID of the Product
test_case_id (number, required) - ID of the Test Case

All attributes must be provided inside the root object test_case. All fields are optional — only the fields you provide are updated. feature_id is not accepted by this endpoint, and top-level target_idx cannot be changed once the test case is created.

Request Body:

title (string, optional) - Title of the test case
requirements (string, optional) - Requirements of the test case
test_case_steps (array[Step], optional) - Array of step objects to create, update, or remove

Step Object:

id (number, optional) - ID of an existing step to update or remove. Omit to add a new step.
description (string, optional) - Description of the step
target_idx (string, optional) - Reference of the step in another system. Only used when adding a new step (no id); ignored when editing an existing step.
_destroy (boolean, optional) - Set to true to remove the step identified by id

Example Request:

1curl -X PUT "https://api.test.io/customer/v2/products/1/test_cases/123" \
2  -H "Authorization: Token YOUR_API_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "test_case": {
6      "title": "Login Test (updated)",
7      "test_case_steps": [
8        { "id": 456, "description": "Navigate to login page (updated)" },
9        { "description": "Confirm dashboard is shown", "target_idx": "ext-789" },
10        { "id": 789, "_destroy": true }
11      ]
12    }
13  }'

Response: 200 OK

Returns the updated test case object. See the response shape in Create a bulk of test cases above.

If the test case is already in use by a test cycle, its steps are not edited in place — a hidden shadow copy of the test case is created (or reused) and the step changes are applied there instead, so historical test results tied to the original steps remain intact. In that case the response is the shadow copy: it has a different id from the one in the request URL, and subsequent requests should use that new id. The original test_case_id will then return 404 from Get test case.

Delete test case

Deletes the specified test case from the product.

Endpoint: DELETE /products/{product_id}/test_cases/{test_case_id}

Parameters:

product_id (number, required) - ID of the Product
test_case_id (number, required) - ID of the Test Case

If the test case is already in use by a test cycle, it is not permanently deleted — it is hidden instead so historical test results remain intact. Hidden test cases no longer appear in List test cases, and subsequent GET requests for that test_case_id return 404.

Example Request:

1curl -X DELETE "https://api.test.io/customer/v2/products/1/test_cases/123" \
2  -H "Authorization: Token YOUR_API_TOKEN"

Response: 204 No Content