Field Filtering For get_cases Tool - skindyk/testrail-mcp-server GitHub Wiki

Field Filtering Guide

Field Filtering for Large Datasets

Problem Solved: When fetching 250+ test cases, large responses can overwhelm AI context and cause conversation loss.

Solution: Use the fields parameter to specify exactly which data you need.

Basic Usage

Before (Large Response)

// Gets all data (2MB response)
get_cases({ project_id: 1, suite_id: 22 })

After (Optimized Response)

// Gets only what you need (200KB response, 90% reduction)
get_cases({ 
  project_id: 1, 
  suite_id: 22, 
  fields: "id,title,custom_field1,custom_field2,priority_id" 
})

Natural Language Examples

Basic Field Filtering

Get 10 test cases from project 1 suite 22. Use field filtering and return only the following fields: id, title, priority_id, custom_field1

Advanced Filtering with Custom Fields

Get test cases from project 5 where priority is Critical. Return only id, title, refs, custom_business_priority, custom_test_type

Performance-Focused Query

Fetch 100 test cases from project 2 suite 15. Use field filtering to get only essential fields: id, title, section_id, priority_id

Available Field Types

Standard Fields

  • id - Test case ID
  • title - Test case title
  • refs - External references
  • priority_id - Priority level
  • created_on - Creation timestamp
  • updated_on - Last update timestamp
  • created_by - Creator user ID
  • updated_by - Last updater user ID
  • section_id - Parent section ID
  • template_id - Template ID
  • type_id - Test case type ID
  • milestone_id - Associated milestone ID
  • estimate - Time estimate
  • estimate_forecast - Forecasted estimate
  • suite_id - Parent suite ID
  • display_order - Display order
  • is_deleted - Deletion status
  • case_assignedto_id - Assigned user ID
  • comments - Comments count
  • labels - Associated labels

Custom Fields

  • Any custom_* fields configured in your TestRail instance
  • Examples: custom_business_priority, custom_test_type, custom_automation_status
  • Custom fields are automatically detected per project
  • Invalid custom fields will return helpful error messages

Performance Benefits

Size Reduction Examples

Scenario Full Response Filtered Response Reduction
50 test cases 500KB 50KB 90%
100 test cases 1.2MB 120KB 90%
250 test cases 3MB 300KB 90%
500 test cases 6MB 600KB 90%

Speed Improvements

  • ✅ Faster API responses due to smaller payloads
  • ✅ Reduced network transfer time
  • ✅ Lower memory usage in MCP clients
  • ✅ Prevents AI context overflow with large datasets

Field Filtering Strategies

Essential Fields Only

For basic test case listing:

fields: "id,title,priority_id,section_id"

Reporting Fields

For test case reports:

fields: "id,title,refs,priority_id,created_on,updated_on,custom_business_priority"

Automation Fields

For automation status tracking:

fields: "id,title,custom_automation_status,custom_test_type,priority_id"

Traceability Fields

For requirements traceability:

fields: "id,title,refs,milestone_id,custom_requirement_id,custom_feature_area"

Best Practices

When to Use Field Filtering

  • ✅ Fetching 50+ test cases
  • ✅ Working with large test suites
  • ✅ Generating reports or summaries
  • ✅ Bulk operations on test cases
  • ✅ Performance-critical integrations

When NOT to Use Field Filtering

  • ❌ Fetching single test cases
  • ❌ Need complete test case data
  • ❌ Working with small datasets (<20 cases)
  • ❌ Detailed test case analysis

Field Selection Tips

  1. Start minimal: Include only absolutely necessary fields
  2. Add incrementally: Add fields as needed for your use case
  3. Test performance: Compare response times with/without filtering
  4. Document patterns: Create reusable field sets for common operations

Error Handling

Invalid Field Names

{
  "error": "Invalid field name 'custom_nonexistent_field'. Available custom fields: custom_business_priority, custom_test_type, custom_automation_status"
}

Field Validation

  • Standard fields are validated against TestRail API schema
  • Custom fields are validated against your project configuration
  • Helpful error messages suggest available alternatives
  • Case-sensitive field names (use exact spelling)

Advanced Usage

Combining with Other Filters

get_cases({
  project_id: 1,
  suite_id: 22,
  priority_id: [1, 2], // Critical and High priority
  created_after: 1640995200, // After Jan 1, 2022
  fields: "id,title,priority_id,created_on,custom_business_priority"
})

Dynamic Field Selection

// For different use cases
const reportFields = "id,title,refs,priority_id,created_on,updated_on";
const automationFields = "id,title,custom_automation_status,custom_test_type";
const traceabilityFields = "id,title,refs,milestone_id,custom_requirement_id";

get_cases({ 
  project_id: 1, 
  fields: reportFields 
})