Test Cases API

The Test Cases API allows you to programmatically manage test cases, including creation, updates, and bulk operations.

Endpoints

List Test Cases

Retrieve test cases for a project

GET /test-cases?project_id=proj_abc123&limit=50

Parameters:

Parameter	Type	Required	Description
`project_id`	string	Yes	Project ID
`test_plan_id`	string	No	Filter by test plan
`limit`	integer	No	Results per page (default: 50, max: 500)
`offset`	integer	No	Pagination offset (default: 0)
`search`	string	No	Search by test name
`status`	string	No	Filter by status: active, archived

Example Request:

curl "https://api.bugbrain.tech/api/v1/test-cases?project_id=proj_abc123&limit=20" \
  -H "Authorization: Bearer $API_KEY"

Response:

{
  "data": [
    {
      "id": "test_abc123",
      "project_id": "proj_abc123",
      "name": "User Login Flow",
      "description": "Test valid login with email and password",
      "status": "active",
      "steps": [
        {
          "step_id": "step_1",
          "description": "Navigate to login page",
          "action": "navigate",
          "value": "/login"
        },
        {
          "step_id": "step_2",
          "description": "Enter email",
          "action": "fill",
          "selector": "#email",
          "value": "user@example.com"
        },
        {
          "step_id": "step_3",
          "description": "Click login button",
          "action": "click",
          "selector": ".btn-login"
        }
      ],
      "created_at": "2025-03-01T10:00:00Z",
      "updated_at": "2025-03-08T10:00:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 150
  }
}

Create Test Case

Create a new test case

POST /test-cases

Request Body:

{
  "project_id": "proj_abc123",
  "name": "Checkout Flow",
  "description": "Complete purchase from cart to confirmation",
  "steps": [
    {
      "description": "Add product to cart",
      "action": "click",
      "selector": ".add-to-cart"
    },
    {
      "description": "Proceed to checkout",
      "action": "click",
      "selector": ".checkout-btn"
    },
    {
      "description": "Fill shipping address",
      "action": "fill",
      "selector": "#shipping-address",
      "value": "123 Main St"
    },
    {
      "description": "Select payment method",
      "action": "select",
      "selector": "#payment-method",
      "value": "credit_card"
    }
  ],
  "tags": ["e-commerce", "payment"]
}

Parameters:

Parameter	Type	Required	Description
`project_id`	string	Yes	Project ID
`name`	string	Yes	Test case name
`description`	string	No	Test description
`steps`	array	Yes	Array of test steps (minimum 1)
`tags`	array	No	Tags for organization

Step Actions:

Action	Parameters	Description
`navigate`	`value`: URL path	Navigate to URL
`click`	`selector`: CSS selector	Click element
`fill`	`selector`, `value`	Fill text input
`type`	`selector`, `value`	Type text (with delay)
`select`	`selector`, `value`	Select dropdown option
`check`	`selector`	Check checkbox
`uncheck`	`selector`	Uncheck checkbox
`hover`	`selector`	Hover over element
`screenshot`	Optional `selector`	Take screenshot
`wait`	`selector`, `timeout`	Wait for element
`assert_visible`	`selector`	Assert element visible
`assert_text`	`selector`, `value`	Assert element text
`assert_value`	`selector`, `value`	Assert input value

Example Request:

curl -X POST https://api.bugbrain.tech/api/v1/test-cases \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_abc123",
    "name": "Login Flow",
    "description": "Valid user login",
    "steps": [
      {"action": "navigate", "value": "/login"},
      {"action": "fill", "selector": "#email", "value": "user@test.com"},
      {"action": "fill", "selector": "#password", "value": "password123"},
      {"action": "click", "selector": ".btn-login"},
      {"action": "assert_visible", "selector": ".dashboard"}
    ]
  }'

Response:

{
  "id": "test_xyz789",
  "project_id": "proj_abc123",
  "name": "Login Flow",
  "description": "Valid user login",
  "status": "active",
  "steps": [...],
  "created_at": "2025-03-08T10:30:00Z",
  "updated_at": "2025-03-08T10:30:00Z"
}

Get Test Case

Retrieve a specific test case

GET /test-cases/{test_case_id}

Example Request:

curl https://api.bugbrain.tech/api/v1/test-cases/test_abc123 \
  -H "Authorization: Bearer $API_KEY"

Response: See create response above.

Update Test Case

Modify an existing test case

PUT /test-cases/{test_case_id}

Request Body: (any fields can be updated)

{
  "name": "Updated Login Flow",
  "description": "Login with email and password validation",
  "steps": [...]  // Replace entire steps array
}

Example Request:

curl -X PUT https://api.bugbrain.tech/api/v1/test-cases/test_abc123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Admin Login Flow",
    "description": "Login with admin credentials"
  }'

Response: Updated test case object.

Delete Test Case

Archive or delete a test case

DELETE /test-cases/{test_case_id}

Parameters:

Parameter	Type	Default	Description
`soft_delete`	boolean	true	Archive instead of delete (recommended)
`force_delete`	boolean	false	Permanently delete test case

Example Request:

# Archive test case (can be restored)
curl -X DELETE https://api.bugbrain.tech/api/v1/test-cases/test_abc123 \
  -H "Authorization: Bearer $API_KEY"
 
# Permanently delete (cannot undo)
curl -X DELETE "https://api.bugbrain.tech/api/v1/test-cases/test_abc123?force_delete=true" \
  -H "Authorization: Bearer $API_KEY"

Response:

{
  "id": "test_abc123",
  "status": "archived",
  "deleted_at": "2025-03-08T10:31:00Z"
}

Bulk Delete

Delete multiple test cases

POST /test-cases/bulk-delete

Request Body:

{
  "test_case_ids": ["test_1", "test_2", "test_3"],
  "soft_delete": true
}

Example Request:

curl -X POST https://api.bugbrain.tech/api/v1/test-cases/bulk-delete \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "test_case_ids": ["test_abc123", "test_def456"],
    "soft_delete": true
  }'

Response:

{
  "deleted": 2,
  "failed": 0,
  "results": [
    {"id": "test_abc123", "status": "archived"},
    {"id": "test_def456", "status": "archived"}
  ]
}

Import Test Cases

Import test cases from CSV or JSON

POST /test-cases/import

Request: (multipart form data)

Content-Type: multipart/form-data

project_id: proj_abc123
file: [CSV or JSON file]

CSV Format:

Name,Description,Step 1,Step 2,Step 3
"Login Flow","Valid login","navigate:/login","fill:#email:user@test.com","click:.btn-login"
"Signup Flow","New user signup","navigate:/signup","fill:#email:new@test.com","click:.btn-signup"

JSON Format:

[
  {
    "name": "Login Flow",
    "description": "Valid login",
    "steps": [
      {"action": "navigate", "value": "/login"},
      {"action": "fill", "selector": "#email", "value": "user@test.com"}
    ]
  }
]

Example Request:

curl -X POST https://api.bugbrain.tech/api/v1/test-cases/import \
  -H "Authorization: Bearer $API_KEY" \
  -F "project_id=proj_abc123" \
  -F "file=@test_cases.csv"

Response:

{
  "imported": 5,
  "failed": 0,
  "results": [
    {"name": "Login Flow", "id": "test_abc123", "status": "imported"},
    {"name": "Signup Flow", "id": "test_def456", "status": "imported"}
  ]
}

Rate Limiting

Test case endpoints are rate-limited:

Plan	Requests/Minute
Starter	30
Growth	60
Pro	120

Bulk operations count as single request but are limited:

Maximum 1000 test cases per bulk operation
Maximum import: 10,000 test cases per file

Example: Create and Run Test Cases

Python:

import requests
import time
 
API_KEY = 'bugbrain_sk_prod_...'
API_URL = 'https://api.bugbrain.tech/api/v1'
 
headers = {'Authorization': f'Bearer {API_KEY}'}
 
# Create test case
create_response = requests.post(
    f'{API_URL}/test-cases',
    headers=headers,
    json={
        'project_id': 'proj_abc123',
        'name': 'New Test Case',
        'steps': [
            {'action': 'navigate', 'value': '/'},
            {'action': 'click', 'selector': '.login-btn'},
            {'action': 'screenshot'}
        ]
    }
)
 
test_case_id = create_response.json()['id']
print(f"Created test case: {test_case_id}")
 
# Add to test plan
requests.post(
    f'{API_URL}/test-plans/tp_prod_xyz/test-cases',
    headers=headers,
    json={'test_case_id': test_case_id}
)
 
# Run the test plan
run_response = requests.post(
    f'{API_URL}/executions',
    headers=headers,
    json={
        'test_plan_id': 'tp_prod_xyz',
        'project_id': 'proj_abc123'
    }
)
 
print(f"Execution results: {run_response.json()}")

Best Practice: Use meaningful test names and descriptions. Include the feature area and user action being tested (e.g., “Login - Valid Credentials” instead of “Test1”).

Executions API Discovery API