docs
MCP Integration
Tool Reference

MCP Tool Reference

Complete technical reference for all Testr MCP tools, including parameters, responses, and usage examples.

Overview

Testr provides 5 MCP tools that enable comprehensive test management through natural language:

ToolPurposeCredit Impact
list-test-definitionsView test templatesNone
get-test-definitionGet specific test detailsNone
create-test-definitionCreate reusable test templatesNone
start-test-runExecute tests from templatesConsumes credits
get-test-run-statusMonitor test executionNone

Tool Specifications

1. list-test-definitions

List all test definitions for the authenticated user with optional filtering and pagination.

Input Schema

{
  page?: number;        // Page number (default: 1)
  pageSize?: number;    // Items per page (default: 10)
  search?: string;      // Search term for filtering by name
}

Example Usage

{
  "name": "list-test-definitions",
  "arguments": {
    "page": 1,
    "pageSize": 5,
    "search": "login"
  }
}

Response Format

{
  "content": [{
    "type": "text",
    "text": "{
      \"definitions\": [
        {
          \"id\": \"uuid\",
          \"name\": \"Login Flow Test\",
          \"description\": \"Test user authentication\",
          \"target_url\": \"https://example.com/login\",
          \"test_type\": \"step\",
          \"total_steps\": 5,
          \"created_at\": \"2024-01-01T00:00:00Z\",
          \"updated_at\": \"2024-01-01T00:00:00Z\"
        }
      ],
      \"totalCount\": 25,
      \"page\": 1,
      \"pageSize\": 5
    }"
  }]
}

Use Cases

  • Browse available test templates
  • Search for specific test types
  • Paginate through large test libraries
  • Audit test inventory

2. get-test-definition

Retrieve detailed information about a specific test definition, including all step definitions.

Input Schema

{
  id: string;  // UUID of the test definition (required)
}

Example Usage

{
  "name": "get-test-definition",
  "arguments": {
    "id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Response Format

{
  "content": [{
    "type": "text",
    "text": "{
      \"testDefinition\": {
        \"id\": \"123e4567-e89b-12d3-a456-426614174000\",
        \"name\": \"E-commerce Checkout\",
        \"description\": \"Complete purchase flow test\",
        \"target_url\": \"https://store.example.com\",
        \"test_type\": \"step\",
        \"total_steps\": 8,
        \"is_active\": true,
        \"created_at\": \"2024-01-01T00:00:00Z\"
      },
      \"stepDefinitions\": [
        {
          \"id\": \"step-uuid-1\",
          \"step_number\": 1,
          \"step_text\": \"Navigate to products page\",
          \"step_type\": \"action\"
        }
      ]
    }"
  }]
}

Use Cases

  • Review test template details before execution
  • Analyze test step sequences
  • Debug test definition issues
  • Clone or modify existing tests

3. create-test-definition

Create new reusable test definition templates. Supports both step-by-step and explorer test types.

Input Schema

{
  name: string;                    // Test name (required)
  description?: string;            // Optional description
  targetUrl: string;              // Starting URL (required)
  testType: "step" | "explorer";  // Test mode (required)
  
  // For step-by-step tests:
  steps?: string[];               // Array of step instructions
  
  // For explorer tests:
  explorerPrompt?: string;        // Natural language task description
  maxCreditSpend?: number;        // Credit limit for AI exploration
}

Step-by-Step Example

{
  "name": "create-test-definition",
  "arguments": {
    "name": "User Registration Flow",
    "description": "Test new user signup process",
    "targetUrl": "https://example.com/signup",
    "testType": "step",
    "steps": [
      "Click on 'Sign Up' button",
      "Type 'testuser@example.com' in email field",
      "Type 'SecurePass123' in password field",
      "Click 'Create Account' button",
      "Verify welcome message appears"
    ]
  }
}

Explorer Test Example

{
  "name": "create-test-definition",
  "arguments": {
    "name": "Newsletter Subscription",
    "description": "Test newsletter signup flow",
    "targetUrl": "https://example.com",
    "testType": "explorer",
    "explorerPrompt": "Find and subscribe to the newsletter using email test@example.com",
    "maxCreditSpend": 10
  }
}

Response Format

{
  "content": [{
    "type": "text",
    "text": "{
      \"testDefinitionId\": \"new-uuid\",
      \"message\": \"Test definition created successfully\"
    }"
  }]
}

Validation Rules

Required Fields:

  • name: Must be non-empty string
  • targetUrl: Must be valid URL format
  • testType: Must be "step" or "explorer"

Step-by-Step Tests:

  • steps: Required array with at least one non-empty step
  • Steps containing "verify", "check", or "ensure" are marked as verification steps

Explorer Tests:

  • explorerPrompt: Required non-empty string
  • maxCreditSpend: Required positive number

Use Cases

  • Create reusable test templates
  • Build test libraries for team sharing
  • Standardize common test scenarios
  • Prepare tests for batch execution

4. start-test-run

Execute a test from an existing test definition. Automatically validates credit availability and starts background execution.

Input Schema

{
  testDefinitionId: string;  // UUID of test definition to run (required)
}

Example Usage

{
  "name": "start-test-run",
  "arguments": {
    "testDefinitionId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Response Format

{
  "content": [{
    "type": "text",
    "text": "{
      \"testRunId\": \"run-uuid\",
      \"status\": \"running\",
      \"name\": \"User Registration Flow\",
      \"targetUrl\": \"https://example.com/signup\",
      \"testType\": \"step\",
      \"totalSteps\": 5,
      \"message\": \"Test run created and execution started\"
    }"
  }]
}

Pre-execution Validation

The tool automatically validates:

  • Test Definition Exists: Confirms the definition ID is valid and belongs to user
  • Credit Availability: Ensures sufficient credits for estimated execution
  • Test Definition Active: Verifies the definition is not disabled

Credit Requirements

Step-by-Step Tests:

  • Credits required = number of steps in definition
  • Example: 5 steps = 5 credits required

Explorer Tests:

  • Credits required = maxCreditSpend from definition
  • Example: maxCreditSpend of 15 = 15 credits required

Error Responses

Insufficient Credits:

{
  "error": {
    "code": -32602,
    "message": "Insufficient credits. Required: 10, Available: 5"
  }
}

Test Definition Not Found:

{
  "error": {
    "code": -32602,
    "message": "Test definition not found"
  }
}

Use Cases

  • Execute pre-built test scenarios
  • Run regression test suites
  • Validate deployments
  • Perform scheduled testing

5. get-test-run-status

Monitor the execution status of a test run, including real-time progress and detailed results.

Input Schema

{
  testRunId: string;  // UUID of the test run (required)
}

Example Usage

{
  "name": "get-test-run-status",
  "arguments": {
    "testRunId": "run-456-789-012"
  }
}

Response Format

{
  "content": [{
    "type": "text",
    "text": "{
      \"id\": \"run-456-789-012\",
      \"name\": \"User Registration Flow\",
      \"target_url\": \"https://example.com/signup\",
      \"status\": \"completed\",
      \"test_type\": \"step\",
      \"total_steps\": 5,
      \"completed_steps\": 5,
      \"credits_used\": 5,
      \"started_at\": \"2024-01-01T10:00:00Z\",
      \"completed_at\": \"2024-01-01T10:02:30Z\",
      \"gif_url\": \"https://testr.pro/videos/run-456-789-012.gif\",
      \"session_id\": \"browser-session-123\"
    }"
  }]
}

Status Values

StatusDescriptionCreditsVideo
pendingWaiting to startNone usedNone
runningCurrently executingPartialLive screenshots
completedSuccessfully finishedFinal totalFull GIF
failedEncountered errorPartialUp to failure
cancelledManually stoppedPartialUp to cancellation

Extended Response Fields

Execution Metadata:

  • started_at: ISO timestamp of execution start
  • completed_at: ISO timestamp of completion (if finished)
  • session_id: Browser automation session identifier

Media Assets:

  • gif_url: Complete video recording (when available)
  • Live screenshots available via separate endpoint during execution

Progress Tracking:

  • completed_steps: Number of steps successfully executed
  • credits_used: Actual credits consumed so far

Use Cases

  • Monitor long-running tests
  • Check execution results
  • Debug test failures
  • Track credit consumption
  • Access test recordings

Error Handling

Common Error Codes

CodeMeaningCommon Causes
-32600Invalid RequestMalformed JSON or missing required fields
-32601Method Not FoundTool name misspelled or not available
-32602Invalid ParamsMissing required parameters or invalid values
-32603Internal ErrorServer-side issues or database problems

Authentication Errors

Missing API Key:

{
  "error": {
    "code": -32602,
    "message": "Unauthorized: API key required"
  }
}

Invalid API Key:

{
  "error": {
    "code": -32602,
    "message": "Unauthorized: Invalid API key"
  }
}

Session Expired:

{
  "error": {
    "code": -32602,
    "message": "Unauthorized: Session expired",
    "data": {
      "reason": "session_expired",
      "note": "Session expired after 24 hours. Please reconnect."
    }
  }
}

Rate Limiting

Request Limits

  • API Calls: 100 requests per minute per API key
  • Test Executions: Subject to credit availability
  • Concurrent Tests: Maximum 5 simultaneous test runs

Best Practices

  • Batch Operations: Use pagination efficiently
  • Polling Frequency: Check test status every 5-10 seconds, not continuously
  • Error Retry: Wait at least 1 second between retry attempts

Integration Examples

Basic Test Workflow

// 1. List available tests
const tests = await mcpClient.call('list-test-definitions', {
  search: 'login'
});
 
// 2. Get specific test details
const testDetails = await mcpClient.call('get-test-definition', {
  id: tests.definitions[0].id
});
 
// 3. Execute the test
const testRun = await mcpClient.call('start-test-run', {
  testDefinitionId: testDetails.testDefinition.id
});
 
// 4. Monitor progress
const status = await mcpClient.call('get-test-run-status', {
  testRunId: testRun.testRunId
});

Batch Test Creation

// Create multiple related tests
const testTemplates = [
  {
    name: 'Login Test',
    targetUrl: 'https://app.com/login',
    testType: 'explorer',
    explorerPrompt: 'Log in with valid credentials',
    maxCreditSpend: 5
  },
  {
    name: 'Registration Test',
    targetUrl: 'https://app.com/signup',
    testType: 'explorer', 
    explorerPrompt: 'Create new account with test data',
    maxCreditSpend: 8
  }
];
 
for (const template of testTemplates) {
  await mcpClient.call('create-test-definition', template);
}

Advanced Usage

Dynamic Test Creation

Use MCP tools to create tests based on application state or user input:

// Create test based on current feature flags
const features = await getActiveFeatures();
if (features.includes('new-checkout')) {
  await mcpClient.call('create-test-definition', {
    name: 'New Checkout Flow Test',
    targetUrl: 'https://store.com/cart',
    testType: 'explorer',
    explorerPrompt: 'Complete checkout using new UI',
    maxCreditSpend: 12
  });
}

Conditional Test Execution

// Run tests based on environment or conditions
const environment = process.env.NODE_ENV;
if (environment === 'staging') {
  const definitions = await mcpClient.call('list-test-definitions', {
    search: 'staging'
  });
  
  for (const def of definitions.definitions) {
    await mcpClient.call('start-test-run', {
      testDefinitionId: def.id
    });
  }
}

Next Steps

Now that you understand all available MCP tools:

  1. Setup Configuration - Ensure your MCP client is properly configured
  2. Usage Patterns - Learn effective command patterns
  3. Analytics Integration - Use test data for insights and optimization

Start building powerful testing automation with these MCP tools!

Usage GuideAPI Overview