> ## 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/runs/start-test-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
* **Configurable limits**: Set **Maximum Concurrent Tests** on each [environment](/core-concepts/applications-and-environments#maximum-concurrent-tests) to cap parallel runs against staging, production, or other URLs
* **Auto-scaling**: When no limit is set, the system scales up to approximately 100 concurrent agents based on demand
* **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. To protect shared infrastructure, set a
  per-environment concurrency limit. Learn more in [Parallel Test Execution and
  Concurrency Limits](/core-concepts/parallel-test-execution), [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/runs/start-test-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/runs/start-test-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/runs/start-test-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/runs/start-test-run) for full details on the `applications` override format.