> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qa.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Test plans

> Test Plans allow you to organize and manage groups of test cases that can be executed together as a single unit.

## Overview

Test Plans are collections of test cases that you want to run together regularly. This feature provides flexibility in running tests through multiple methods: API triggers, scheduled runs, or manual execution through the UI.

Test plans help streamline your testing process by:

* Organizing related test cases into logical groups
* Enabling automated execution on schedules
* Supporting API-driven test automation
* Managing test dependencies efficiently

## Creating a Test Plan

1. Navigate to the Test Plans section
2. Click the "Create Test Plan" button in the top right
3. Provide the following information:
   * Name: A clear, descriptive name for your test plan
   * Description (optional): Additional context about the test plan's purpose
   * Owner (optional): Assign a team member responsible for this test plan. See [Ownership](/core-concepts/ownership)
4. Click "Save" to create your test plan

## Adding Test Cases to a Test Plan

When adding test cases to a test plan, keep in mind:

* Dependencies will be automatically included in runs, even if not visible in the UI
* Consider creating separate plans for:
  * Frequently run core tests
  * Less frequent tests that run on a schedule

## Execution Methods

### CI/CD Integration

Test Plans are the primary way to run tests from CI/CD pipelines. You can trigger test plans programmatically via the QA.tech REST API from any CI/CD system. See [CI/CD Integration](/configuration/ci-cd-integration) for an overview of integration options and platform-specific guides.

**How it works:**

1. Create a test plan and add test cases to it
2. Get the test plan's **Test Plan Short ID** ([prefixed ID](/configuration/gitlab#finding-your-test-plan-short-id) visible in the test plan URL)
3. Trigger the test plan via API from your CI/CD pipeline

**Should work with any CI/CD system** - Since QA.tech uses a standard REST API, you can integrate from any CI/CD platform that can make HTTP requests (using curl, HTTP libraries, or built-in HTTP steps). Examples include:

* GitLab CI/CD
* GitHub Actions
* Bitbucket Pipelines
* Azure DevOps
* CircleCI
* Jenkins
* Any other CI/CD system with HTTP request capabilities

### GitHub Actions Integration

You can automate test execution by integrating Test Plans with your GitHub workflows. This integration allows you to:

* Trigger tests automatically after deployments
* Run tests on pull requests
* Execute tests on any GitHub event

Read more about setting up [GitHub Actions](/configuration/github-actions).

### API Execution

Test Plans can be triggered programmatically through the API. For detailed information about available endpoints and parameters, refer to the [API reference documentation](/api-reference/start-run).

**Example:**

```bash theme={null}
curl -X POST https://api.qa.tech/v1/run \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "testPlanShortId": "pln_abc123"
  }'
```

The `testPlanShortId` is the [prefixed Test Plan Short ID](/configuration/gitlab#finding-your-test-plan-short-id) visible in your test plan settings (e.g., `pln_abc123`).

### Scheduled Execution

You can configure Test Plans to run automatically at specific times or intervals:

<Steps>
  <Step title="Navigate to Test Plans">
    Go to [Test Plans](https://app.qa.tech/current-project/test-plans) in your
    project dashboard.
  </Step>

  <Step title="Select Test Plan">
    Click on the test plan you want to schedule.
  </Step>

  <Step title="Manage Schedules">
    Click on **Manage Schedules** within the test plan.
  </Step>

  <Step title="Add Schedule">
    Add your cron schedule expression and a description, then click **Add
    Schedule**.
  </Step>
</Steps>

### UI Execution

To run a Test Plan manually:

1. Navigate to the Test Plans section
2. Locate your Test Plan
3. Click the "Run Tests" button

## Performance & Parallel Execution

QA.tech automatically runs tests in parallel to minimize total execution time when executing test plans:

* **Automatic parallelization**: Tests run concurrently by default when executing a test plan, significantly reducing the time required to complete a full test suite
* **Dependency-aware**: Parallel execution respects the dependency graph, ensuring dependent tests run in the correct order while maximizing parallelization opportunities
* **Auto-scaling**: The system automatically scales up to approximately 100 concurrent agents based on demand, with no manual configuration required
* **Intelligent scheduling**: Independent tests execute simultaneously while dependent tests wait for their prerequisites to complete

This means that while a single test case may take several minutes to execute, running a test plan with multiple independent test cases will complete much faster than running them sequentially. For example, 20 independent tests that each take 3 minutes would complete in approximately 3 minutes when run as a test plan, rather than 60 minutes if run sequentially.

<Tip>
  To maximize parallel execution benefits, organize your test cases to minimize
  dependencies between tests. The more independent tests in your test plan, the
  more parallelization can occur. Learn more about [Test
  Dependencies](/core-concepts/dependencies) and [Creating
  Tests](/best-practices/creating-tests).
</Tip>

## Best Practices

1. **Optimize Test Organization**:
   * Group related test cases together
   * Create separate plans for different testing frequencies
   * Keep plans focused and maintainable

2. **Dependency Management**:
   * Be aware that dependent test cases will be included automatically
   * Review dependencies when setting up new test plans

3. **Schedule and Workflow Optimization**:
   * Schedule less frequent tests during off-peak hours
   * Configure GitHub workflows to run tests at key points in your development process (deployments, PRs, merges)

4. **Managing Different Versions and Releases**:
   * Use Test Scenarios to define the specific test cases to run for a given version or release
   * The same Test Plan can be reused across different environments by overriding environment URLs via API (see [Start Run API](/api-reference/start-run)) or updating test plan parameters in the UI
   * **Note:** Both environment and device preset overrides are supported via API. See [Start Run API](/api-reference/start-run) for details on using `applications` overrides.

5. **Notification Configuration**:
   * Configure email, Slack, and Microsoft Teams notifications at the test plan level
   * Override the project's default Slack channel for test plan-specific routing
   * Add organization members as email recipients to ensure stakeholders receive run completion notifications
   * See [Notifications](/core-concepts/notifications) for detailed setup instructions

## Test Plan Parameters

Test plan parameters let you configure environment and device preset settings per application. When a test plan runs, each test uses the environment configured for its application.

### Configuration Levels

Parameters follow a precedence hierarchy where later settings override earlier ones:

```
Project Settings (defaults for all runs)
└── Test Plan Parameters (override per test plan)
    └── Per-Run API (override per individual run)
```

### Configuring Parameters in the UI

Navigate to your test plan and expand the **Parameters** section. You'll see a card for each application that has test cases in the plan.

| Setting           | How to Configure                                                  | Can Clear?             |
| ----------------- | ----------------------------------------------------------------- | ---------------------- |
| **Environment**   | Select from dropdown                                              | No - always required   |
| **Device Preset** | Select from dropdown, or choose "Default" to use project defaults | Yes - select "Default" |

<Note>
  Applications only appear in the Parameters section if they have test cases included in the test plan.
</Note>

### How Tests Execute with Multiple Applications

Each test case belongs to **one application** and runs **once** using that application's configured environment. Tests do not run across multiple applications.

**Example:**

* Test Plan contains: Test A (App 1), Test B (App 1), Test C (App 2)
* Parameters: App 1 → Production, App 2 → Staging
* Execution:
  * Test A runs on Production (App 1's environment)
  * Test B runs on Production (App 1's environment)
  * Test C runs on Staging (App 2's environment)

This means different tests in the same test plan can run against different environments based on their application assignment.

### API Overrides

You can override parameters at runtime via the [Start Run API](/api-reference/start-run). API overrides take highest precedence:

```json theme={null}
{
  "testPlanShortId": "pln_abc123",
  "applications": [
    {
      "applicationShortId": "app_gXeBl2",
      "environment": { "url": "https://preview.example.com" },
      "devicePresetShortId": "preset_abc123"
    }
  ]
}
```

See [Start Run API](/api-reference/start-run) for full details on the `applications` override format.