Test Plans

The plans endpoints allow you to create and manage test plans in your project. A test plan is a collection of test runs that are organized and executed together, typically for a specific milestone or release. Write operations (create/update/delete) can only be performed by users with role test runner or with higher privileges.

Test Plan Overview

A test plan consists of:

• Title and Description: Basic information about the plan
• Milestone: Optional association with a project milestone
• Runs: One or more test runs, each containing a set of test cases

Each run within a plan:

• Has its own title
• Can be assigned to a specific user
• Can be associated with a configuration
• Contains exactly one query plan that specifies the test cases to include

Create New Test Plan

POST/api/public/v0/project/{project_id}/plan

Creates a new test plan in the project with one or more test runs.

Authentication

Requires an API key with at least Test Runner role permissions. See Authentication for more details.

Request Body

{
  title: string                  // Required: Plan title (max 255 characters)
  description?: html             // Optional: Plan description
  milestoneId?: number           // Optional: Associated milestone
  runs: Array<{                  // Required: List of runs in the plan
    title: string                // Required: Run title (max 255 characters)
    assignmentId?: number        // Optional: Assigned user ID
    configurationId?: string     // Optional: Configuration ID
    queryPlans: Array<{          // Required: Exactly one query plan per run
      tcaseIds: Array<string>    // Required: Test case IDs to include
    }>
  }>
}

Field Constraints

• title: Must be 1-255 characters long and unique within the milestone (or among plans without milestones)
• description: HTML content that will be sanitized
• milestoneId: The milestone must belong to the project and must not be archived
• runs: Must contain at least one run
• Each run must have exactly one query plan
• tcaseIds: Must be valid test case IDs belonging to the project
• assignmentId: Must be an active user with permissions above Viewer role
• Test case IDs must be standalone or filled types (not templates)

Response

Status: 201 Created

{
  "id": 5
}

The response contains the ID of the newly created test plan.

Error Responses

Status Code	Description
400	Invalid request data or validation errors
401	Invalid or missing API key
403	Insufficient permissions (requires Test Runner role)
404	Project not found
409	Conflict - Plan title already exists in milestone
500	Internal server error

Common Use Cases

Cross-Browser Testing

Create a test plan to run the same test suite across different browsers:

{
  "title": "Release 3.0 Browser Compatibility",
  "description": "<p>Browser compatibility testing for Release 3.0</p>",
  "milestoneId": 15,
  "runs": [
    {
      "title": "Chrome Tests",
      "configurationId": "chrome_latest",
      "assignmentId": 3,
      "queryPlans": [
        {
          "tcaseIds": [
            "1CEPaUhgH_Tvt2LZygwVRQa",
            "1CAPaUhgH_Tvt2LZygwVRTb",
            "1DAPaUhgH_Tvt2LZygwVRSc",
            "1EEPaUhgH_Tvt2LZygwVRLm",
            "1FEPaUhgH_Tvt2LZygwVRNn"
          ]
        }
      ]
    },
    {
      "title": "Firefox Tests",
      "configurationId": "firefox_latest",
      "assignmentId": 3,
      "queryPlans": [
        {
          "tcaseIds": [
            "1CEPaUhgH_Tvt2LZygwVRQa",
            "1CAPaUhgH_Tvt2LZygwVRTb",
            "1DAPaUhgH_Tvt2LZygwVRSc",
            "1EEPaUhgH_Tvt2LZygwVRLm",
            "1FEPaUhgH_Tvt2LZygwVRNn"
          ]
        }
      ]
    },
    {
      "title": "Safari Tests",
      "configurationId": "safari_latest",
      "assignmentId": 3,
      "queryPlans": [
        {
          "tcaseIds": [
            "1CEPaUhgH_Tvt2LZygwVRQa",
            "1CAPaUhgH_Tvt2LZygwVRTb",
            "1DAPaUhgH_Tvt2LZygwVRSc",
            "1EEPaUhgH_Tvt2LZygwVRLm",
            "1FEPaUhgH_Tvt2LZygwVRNn"
          ]
        }
      ]
    },
    {
      "title": "Edge Tests",
      "configurationId": "edge_latest",
      "assignmentId": 3,
      "queryPlans": [
        {
          "tcaseIds": [
            "1CEPaUhgH_Tvt2LZygwVRQa",
            "1CAPaUhgH_Tvt2LZygwVRTb",
            "1DAPaUhgH_Tvt2LZygwVRSc",
            "1EEPaUhgH_Tvt2LZygwVRLm",
            "1FEPaUhgH_Tvt2LZygwVRNn"
          ]
        }
      ]
    }
  ]
}

Multi-Platform Testing

Test the same application across different platforms and devices:

{
  "title": "Mobile App Platform Testing",
  "description": "<p>Testing mobile app across different platforms</p>",
  "runs": [
    {
      "title": "iOS 17 - iPhone 15",
      "configurationId": "ios17_iphone15",
      "assignmentId": 4,
      "queryPlans": [
        {
          "tcaseIds": [
            "1GEPaUhgH_Tvt2LZygwVROo",
            "1HEPaUhgH_Tvt2LZygwVRPp",
            "1IEPaUhgH_Tvt2LZygwVRQq",
            "1JEPaUhgH_Tvt2LZygwVRRr",
            "1KEPaUhgH_Tvt2LZygwVRSs"
          ]
        }
      ]
    },
    {
      "title": "iOS 17 - iPad Pro",
      "configurationId": "ios17_ipad_pro",
      "assignmentId": 4,
      "queryPlans": [
        {
          "tcaseIds": [
            "1GEPaUhgH_Tvt2LZygwVROo",
            "1HEPaUhgH_Tvt2LZygwVRPp",
            "1IEPaUhgH_Tvt2LZygwVRQq",
            "1JEPaUhgH_Tvt2LZygwVRRr",
            "1KEPaUhgH_Tvt2LZygwVRSs"
          ]
        }
      ]
    },
    {
      "title": "Android 14 - Pixel 8",
      "configurationId": "android14_pixel8",
      "assignmentId": 5,
      "queryPlans": [
        {
          "tcaseIds": [
            "1GEPaUhgH_Tvt2LZygwVROo",
            "1HEPaUhgH_Tvt2LZygwVRPp",
            "1IEPaUhgH_Tvt2LZygwVRQq",
            "1JEPaUhgH_Tvt2LZygwVRRr",
            "1KEPaUhgH_Tvt2LZygwVRSs"
          ]
        }
      ]
    },
    {
      "title": "Android 14 - Samsung Galaxy",
      "configurationId": "android14_galaxy",
      "assignmentId": 5,
      "queryPlans": [
        {
          "tcaseIds": [
            "1GEPaUhgH_Tvt2LZygwVROo",
            "1HEPaUhgH_Tvt2LZygwVRPp",
            "1IEPaUhgH_Tvt2LZygwVRQq",
            "1JEPaUhgH_Tvt2LZygwVRRr",
            "1KEPaUhgH_Tvt2LZygwVRSs"
          ]
        }
      ]
    }
  ]
}

Regression Testing Across Environments

Run regression tests across different deployment environments:

{
  "title": "Regression Test Suite - All Environments",
  "description": "<p>Full regression testing across staging and production-like environments</p>",
  "runs": [
    {
      "title": "Regression Tests - Staging US",
      "configurationId": "staging_us_east",
      "assignmentId": 3,
      "queryPlans": [
        {
          "tcaseIds": [
            "1LEPaUhgH_Tvt2LZygwVRTt",
            "1MEPaUhgH_Tvt2LZygwVRUu",
            "1NEPaUhgH_Tvt2LZygwVRVv",
            "1OEPaUhgH_Tvt2LZygwVRWw",
            "1PEPaUhgH_Tvt2LZygwVRXx",
            "1QEPaUhgH_Tvt2LZygwVRYy"
          ]
        }
      ]
    },
    {
      "title": "Regression Tests - Staging EU",
      "configurationId": "staging_eu_west",
      "assignmentId": 4,
      "queryPlans": [
        {
          "tcaseIds": [
            "1LEPaUhgH_Tvt2LZygwVRTt",
            "1MEPaUhgH_Tvt2LZygwVRUu",
            "1NEPaUhgH_Tvt2LZygwVRVv",
            "1OEPaUhgH_Tvt2LZygwVRWw",
            "1PEPaUhgH_Tvt2LZygwVRXx",
            "1QEPaUhgH_Tvt2LZygwVRYy"
          ]
        }
      ]
    },
    {
      "title": "Regression Tests - Staging APAC",
      "configurationId": "staging_apac",
      "assignmentId": 5,
      "queryPlans": [
        {
          "tcaseIds": [
            "1LEPaUhgH_Tvt2LZygwVRTt",
            "1MEPaUhgH_Tvt2LZygwVRUu",
            "1NEPaUhgH_Tvt2LZygwVRVv",
            "1OEPaUhgH_Tvt2LZygwVRWw",
            "1PEPaUhgH_Tvt2LZygwVRXx",
            "1QEPaUhgH_Tvt2LZygwVRYy"
          ]
        }
      ]
    }
  ]
}

Component-Based Testing

Create test plans with different test cases for distinct components or modules:

{
  "title": "Sprint 23 Feature Test Plan",
  "description": "<p>Test plan for different components developed in Sprint 23</p>",
  "runs": [
    {
      "title": "User Authentication Module",
      "assignmentId": 3,
      "queryPlans": [{ "tcaseIds": ["1CEPaUhgH_Tvt2LZygwVRQa", "1CAPaUhgH_Tvt2LZygwVRTb"] }]
    },
    {
      "title": "Payment Processing Module",
      "assignmentId": 4,
      "queryPlans": [{ "tcaseIds": ["1EEPaUhgH_Tvt2LZygwVRLm", "1FEPaUhgH_Tvt2LZygwVRNn"] }]
    },
    {
      "title": "Notification Service",
      "assignmentId": 5,
      "queryPlans": [{ "tcaseIds": ["1GEPaUhgH_Tvt2LZygwVROo", "1HEPaUhgH_Tvt2LZygwVRPp"] }]
    }
  ]
}

Best Practices

• Configuration-Based Runs: Most test plans will have runs with similar titles and identical test cases, differing only in configurations (e.g., browsers, devices, environments)
• Consistent Naming: Use a consistent naming pattern for runs testing the same functionality across configurations (e.g., "Feature X - Chrome", "Feature X - Firefox")
• Same Test Cases: Reuse the same test case IDs across runs when testing across different configurations
• Assign by Expertise: When testing across platforms, assign runs based on platform expertise rather than feature expertise
• Link to Milestones: Associate plans with milestones for better release tracking
• Exception Cases: Only create runs with different test cases when testing distinct components or modules

Limitations

• Each run must have exactly one query plan
• Only User selection test runs are supported (tcaseIds must be specified). See Types of Runs for more details.
• Dynamic folder/tag-based selection is not available for plans
• Test plans cannot be cloned via the public API (planned for future release)
• Updating test plans is not yet available via the public API

Related Resources

• Runs - Learn about individual test runs
• Test Cases - Manage test cases
• Milestones - Work with project milestones
• Results - Add results to test cases in runs