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

# Test Plans

> Save, organize, and rerun load test configurations

Test Plans allow you to save load test configurations for reuse. Instead of configuring tests from scratch each time, save your settings as a plan and run it whenever needed.

## Key Benefits

<CardGroup cols={2}>
  <Card title="Reusable Configurations" icon="rotate">
    Save test configurations once and run them multiple times with consistent settings.
  </Card>

  <Card title="Execution History" icon="clock-rotate-left">
    Track all test runs for each plan with full metrics and comparison capabilities.
  </Card>

  <Card title="Wizard & Script Modes" icon="wand-magic-sparkles">
    Configure tests via UI wizard or write custom K6 scripts directly.
  </Card>

  <Card title="CI/CD Integration" icon="code-branch">
    Run plans programmatically via API for automated performance testing.
  </Card>
</CardGroup>

## Page Layout

The Test Plans page uses a split-panel layout:

* **Left Panel**: List of all test plans (searchable, resizable)
* **Right Panel**: Test execution history for the selected plan

Select a plan from the left to view its configuration and execution history on the right.

## How to Create a Test Plan

Test plans are created automatically when you run a test from the [New Test](/guide/load-testing/new-test) wizard.

<Steps>
  <Step title="Configure a New Test">
    Go to **New Test** and configure your test settings (URL, method, load pattern, thresholds, location).
  </Step>

  <Step title="Run the Test">
    Click **Launch Test**. The configuration is automatically saved as a test plan.
  </Step>

  <Step title="Find Your Plan">
    Navigate to **Test Plans**. Your new plan appears in the list with a generated name based on the target URL.
  </Step>
</Steps>

<Info>
  Test plans are named automatically using the format: `hostname-METHOD-YYYYMMDD-HHMM` (e.g., `api.example.com-GET-20240115-1430`).
</Info>

## How to Run a Test from a Plan

<Steps>
  <Step title="Select the Plan">
    Click on a test plan from the left panel to select it.
  </Step>

  <Step title="Click Run">
    Click the **Run** button in the right panel header.
  </Step>

  <Step title="Monitor Execution">
    A dialog shows real-time test progress. Results appear in the execution history when complete.
  </Step>
</Steps>

## How to Edit a Test Plan

Modify any aspect of a saved test plan using the settings drawer.

<Steps>
  <Step title="Select the Plan">
    Click on the plan you want to edit.
  </Step>

  <Step title="Open Settings">
    Click the **More** menu (three dots) and select **Edit Settings**.
  </Step>

  <Step title="Modify Settings">
    Use the tabbed interface to edit different aspects of the plan.
  </Step>

  <Step title="Save Changes">
    Click **Save Changes** to update the plan.
  </Step>
</Steps>

### Settings Tabs

| Tab            | Settings                                                       |
| -------------- | -------------------------------------------------------------- |
| **Base**       | Name, URL, HTTP method, location, executor type, VUs, duration |
| **Params**     | URL query parameters                                           |
| **Headers**    | Custom HTTP headers                                            |
| **Body**       | Request body (JSON, XML, or text)                              |
| **Auth**       | Authentication (Bearer, Basic, API Key)                        |
| **Steps**      | Multi-step scenario configuration                              |
| **Thresholds** | Performance pass/fail criteria                                 |
| **Settings**   | Follow redirects, HTTP/2, timeout                              |

## How to Clone a Test Plan

Create a copy of an existing plan for variations or A/B testing.

<Steps>
  <Step title="Select the Plan">
    Click on the plan you want to clone.
  </Step>

  <Step title="Clone">
    Click the **More** menu and select **Clone**.
  </Step>

  <Step title="Edit the Clone">
    The new plan appears in the list. Edit its settings to differentiate it from the original.
  </Step>
</Steps>

<Tip>
  Clone plans to create variations for testing different endpoints, load levels, or configurations while preserving the original.
</Tip>

## How to Delete a Test Plan

<Steps>
  <Step title="Select the Plan">
    Click on the plan you want to delete.
  </Step>

  <Step title="Delete">
    Click the **More** menu and select **Delete**.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. This action cannot be undone.
  </Step>
</Steps>

<Warning>
  Deleting a test plan does not delete its execution history. Past test results remain accessible from the Test Results page.
</Warning>

## Wizard Mode vs Custom Script Mode

Test plans support two configuration modes:

### Wizard Mode (Default)

Configure tests using the UI without writing code. Best for:

* Standard API testing scenarios
* Quick configuration changes
* Users unfamiliar with K6 scripting

### Custom Script Mode

Write K6 scripts directly for advanced scenarios. Best for:

* Complex test logic (loops, conditions, data-driven tests)
* Custom metrics and checks
* Scenarios not supported by the wizard

<Steps>
  <Step title="Open Plan Settings">
    Edit the test plan settings.
  </Step>

  <Step title="Switch Mode">
    Click **Custom** in the mode toggle at the top of the drawer.
  </Step>

  <Step title="Edit Script">
    The **Script** tab appears. Edit the K6 JavaScript code directly.
  </Step>

  <Step title="Save">
    Click **Save Changes**. The plan now uses your custom script.
  </Step>
</Steps>

<Info>
  When switching to Custom mode, the system generates an initial script from your wizard configuration. You can then modify it as needed.
</Info>

## Execution History

Each test plan tracks all its executions in a table showing:

| Column           | Description                           |
| ---------------- | ------------------------------------- |
| **Test ID**      | Unique identifier for the execution   |
| **Status**       | PENDING, RUNNING, SUCCESS, or FAILED  |
| **Latency**      | Average response time in milliseconds |
| **Success Rate** | Percentage of successful requests     |
| **Requests**     | Total number of requests made         |
| **Location**     | Geographic origin of the test         |

Click any row to view detailed results for that execution.

## CI/CD Integration

Run test plans programmatically using the API for automated performance testing in pipelines.

```bash theme={null}
# Run a test plan via API
curl -X POST "https://api.shiftlabs.dev/api/v1/loadtest/plans/{planId}/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

The API returns a `testId` that you can use to poll for results or configure webhooks for completion notifications.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Plan not appearing in list" icon="circle-question">
    * Refresh the page or click the refresh button
    * Check if you have read permission for Load Testing
    * Verify you're viewing the correct project
  </Accordion>

  <Accordion title="Cannot edit plan settings" icon="circle-question">
    * You need write permission for Load Testing
    * The plan may be running a test; wait for completion
  </Accordion>

  <Accordion title="Run button disabled" icon="circle-question">
    * You need execute permission for Load Testing
    * Another test may already be running from this plan
  </Accordion>

  <Accordion title="Custom script not saving" icon="circle-question">
    * Ensure the script is valid JavaScript
    * Check for syntax errors in the script editor
    * The script must export a default function
  </Accordion>

  <Accordion title="Execution history not updating" icon="circle-question">
    * Click the refresh button in the toolbar
    * Tests may take time to complete and appear
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can I schedule test plans to run automatically?">
    Direct scheduling is not available in the UI. Use CI/CD pipelines with cron triggers to schedule recurring tests via the API.
  </Accordion>

  <Accordion title="How many test plans can I create?">
    There is no limit to the number of test plans. Create as many as needed for your testing scenarios.
  </Accordion>

  <Accordion title="Can I share test plans between projects?">
    Test plans are project-scoped. To use a plan in another project, clone it and manually recreate in the target project.
  </Accordion>

  <Accordion title="What happens to plans when I change the target URL?">
    Changing the URL updates the plan configuration. Future runs use the new URL. Past executions retain their original URLs.
  </Accordion>

  <Accordion title="Can I export test plans?">
    Test plans can be exported as K6 scripts using Custom Script mode. Copy the generated script for use outside the platform.
  </Accordion>

  <Accordion title="How do I compare results across different plans?">
    Use the [Test Results](/guide/load-testing/test-results) page to compare any two test executions, regardless of which plan they belong to.
  </Accordion>
</AccordionGroup>