> ## 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.

# New Test

> Create and run performance tests against your APIs

The New Test wizard guides you through configuring and launching load tests. The wizard has four steps: Scenario, Load, Thresholds, and Location.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Virtual Users (VUs)" icon="users">
    Simulated concurrent users making requests. More VUs = higher load on your system.
  </Card>

  <Card title="Load Patterns" icon="chart-line">
    How load is applied over time: constant, ramping up/down, fixed iterations, or arrival rate.
  </Card>

  <Card title="Thresholds" icon="bullseye">
    Pass/fail criteria based on response times, error rates, or throughput.
  </Card>

  <Card title="Test Location" icon="globe">
    Geographic origin of the load test, affecting network latency to your servers.
  </Card>
</CardGroup>

## How to Create a Single Request Test

Test a single API endpoint with configurable load.

<Steps>
  <Step title="Select Single Request Mode">
    On the Scenario step, ensure **Single Request** is selected (default).
  </Step>

  <Step title="Configure the Request">
    * Select the HTTP method (GET, POST, PUT, PATCH, DELETE)
    * Enter the target URL (e.g., `https://api.example.com/users`)
    * Click **Settings** to add headers, query params, request body, or authentication
  </Step>

  <Step title="Choose a Load Pattern">
    Select one of the four load patterns:

    * **Constant VUs**: Fixed number of users for a set duration
    * **Ramping VUs**: Gradually increase/decrease users over stages
    * **Per VU Iterations**: Each user runs a fixed number of requests
    * **Constant Arrival Rate**: Maintain a fixed request rate regardless of response time
  </Step>

  <Step title="Configure Load Settings">
    Click **Next** and configure the specific parameters for your chosen pattern.
  </Step>

  <Step title="Set Thresholds (Optional)">
    Define pass/fail criteria like "p95 latency must be under 500ms".
  </Step>

  <Step title="Select Location">
    Choose the geographic location from the world map.
  </Step>

  <Step title="Launch Test">
    Click **Launch Test**. The test execution panel shows real-time progress.
  </Step>
</Steps>

## How to Create a Multi-Step Test

Chain multiple API requests to test user flows (login → fetch data → submit form).

<Steps>
  <Step title="Select Multi-Step Mode">
    On the Scenario step, click **Multi-Step** to switch modes.
  </Step>

  <Step title="Add Steps">
    Click **Add Step** to create each request in the flow. For each step:

    * **Name**: Descriptive name (e.g., "Login", "Get User Profile")
    * **URL**: The endpoint URL
    * **Method**: HTTP method
    * **Headers/Body**: Request configuration
  </Step>

  <Step title="Configure Variable Extractors">
    Extract values from responses to use in subsequent steps:

    * **Source**: body, header, or status
    * **Path**: JSONPath expression (e.g., `$.data.token`)
    * **Variable Name**: Reference in later steps as `{{variableName}}`
  </Step>

  <Step title="Add Assertions">
    Validate each step's response:

    * Status code equals 200
    * Body contains specific value
    * Response time under threshold
  </Step>

  <Step title="Continue with Load, Thresholds, and Location">
    Complete the remaining wizard steps as with single request tests.
  </Step>
</Steps>

<Info>
  In multi-step mode, each virtual user executes all steps in sequence. The total iteration duration includes all steps plus any configured think time between them.
</Info>

## Load Pattern Reference

### Constant VUs

Runs a fixed number of virtual users continuously for the specified duration.

| Parameter | Description                | Example     |
| --------- | -------------------------- | ----------- |
| VUs       | Number of concurrent users | 10          |
| Duration  | How long to run            | 30s, 5m, 1h |

**Use case**: Baseline performance testing, sustained load simulation, capacity planning.

### Ramping VUs

Gradually increases or decreases load through defined stages.

| Parameter | Description                          | Example               |
| --------- | ------------------------------------ | --------------------- |
| Stages    | List of (duration, target VUs) pairs | 10s→10, 20s→50, 10s→0 |

**Quick Templates**:

* **Linear Ramp**: Gradual load increase
* **Spike Test**: Sudden load spike then recovery
* **Stress Test**: Progressive overload to find breaking point

**Use case**: Stress testing, finding breaking points, warm-up scenarios.

### Per VU Iterations

Each virtual user executes the test script a fixed number of times.

| Parameter  | Description                | Example |
| ---------- | -------------------------- | ------- |
| VUs        | Number of concurrent users | 5       |
| Iterations | Requests per user          | 100     |

Total requests = VUs × Iterations. Test ends when all users complete their iterations.

**Use case**: Batch processing tests, finite workload simulation.

### Constant Arrival Rate

Maintains a constant rate of new requests regardless of response time.

| Parameter | Description              | Example |
| --------- | ------------------------ | ------- |
| Rate      | Requests per time unit   | 50      |
| Time Unit | Per second or per minute | 1s      |
| Duration  | Total test duration      | 2m      |

**Use case**: SLA validation, throughput testing, rate-limited API testing.

## How to Configure Request Settings

Click the **Settings** button to open the configuration drawer.

### Query Parameters

Add URL query parameters:

1. Click **Add Parameter**
2. Enter key and value
3. Parameters are appended to the URL automatically

### Headers

Add custom HTTP headers:

1. Click **Add Header**
2. Enter header name and value (e.g., `Content-Type: application/json`)

### Request Body

For POST, PUT, PATCH requests:

1. Select body type: JSON, XML, or Text
2. Enter the request body content
3. JSON is validated before test execution

### Authentication

Configure request authentication:

| Type             | Parameters                                  |
| ---------------- | ------------------------------------------- |
| **Basic Auth**   | Username, Password                          |
| **Bearer Token** | Token value                                 |
| **API Key**      | Key name, Key value, Pass by (header/query) |

### Options

| Option           | Description                         | Default  |
| ---------------- | ----------------------------------- | -------- |
| Follow Redirects | Automatically follow HTTP redirects | Enabled  |
| Enable HTTP/2    | Use HTTP/2 protocol if supported    | Disabled |
| Timeout          | Request timeout in seconds          | 30       |

## How to Set Performance Thresholds

Thresholds define pass/fail criteria for your test.

<Steps>
  <Step title="Open Thresholds Step">
    Navigate to step 3 (Thresholds) in the wizard.
  </Step>

  <Step title="Add a Threshold">
    Click **Add Threshold** and configure:

    * **Metric**: What to measure (p50, p90, p95, p99, avg, errorRate, throughput)
    * **Operator**: Comparison (less than, greater than, equals)
    * **Value**: Target value
    * **Severity**: Error (fails test) or Warning (flags but passes)
  </Step>

  <Step title="Add More Thresholds">
    Add multiple thresholds to validate different aspects of performance.
  </Step>
</Steps>

**Common threshold examples**:

| Metric     | Condition | Description                         |
| ---------- | --------- | ----------------------------------- |
| p95        | \< 500ms  | 95th percentile latency under 500ms |
| p99        | \< 1000ms | 99th percentile under 1 second      |
| errorRate  | \< 1%     | Less than 1% failed requests        |
| throughput | > 100     | At least 100 requests per second    |

<Warning>
  Without thresholds, tests always pass regardless of performance. Add thresholds to automatically detect regressions.
</Warning>

## How to Select Test Location

Choose where load originates geographically.

<Steps>
  <Step title="View Available Locations">
    The world map shows all available proxy locations as markers.
  </Step>

  <Step title="Select a Location">
    Click a marker on the map or select from the dropdown list.
  </Step>

  <Step title="Consider Proximity">
    The map shows your target server's location (if resolvable). Choose a location that represents your actual users.
  </Step>
</Steps>

<Tip>
  Test from multiple locations using [Multi-Region Tests](/guide/load-testing/multi-region) to understand global performance.
</Tip>

## During Test Execution

After clicking **Launch Test**:

1. **Status Panel**: Shows real-time test progress
2. **Live Metrics**: Requests, latency, success rate update in real-time
3. **Logs**: K6 execution output streams live
4. **Auto-Navigation**: Redirects to detailed results when complete

<Info>
  You can navigate away during execution. Return to New Test page to see the active test panel, or check Test Results for completed tests.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Test fails to start" icon="circle-question">
    * Verify the URL is valid and accessible from the internet
    * Check that authentication credentials are correct
    * Ensure the target server allows requests from proxy IPs
  </Accordion>

  <Accordion title="All requests fail" icon="circle-question">
    * Check the target URL is reachable
    * Verify SSL certificates if using HTTPS
    * Review request headers and body format
    * Check for rate limiting or IP blocking on target server
  </Accordion>

  <Accordion title="Latency higher than expected" icon="circle-question">
    * Consider the geographic distance between test location and server
    * Check if your server is under load from other sources
    * Review if authentication adds overhead
  </Accordion>

  <Accordion title="Cannot add steps in multi-step mode" icon="circle-question">
    * Ensure you've switched to Multi-Step mode
    * Each step requires at minimum a name and URL
  </Accordion>

  <Accordion title="Variable extraction not working" icon="circle-question">
    * Verify the JSONPath expression is correct
    * Ensure the previous step returns the expected response structure
    * Check that variable names don't contain special characters
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="How many VUs can I use?">
    You can configure 1 to 1000 virtual users per test. Higher VU counts generate more load but consume more resources.
  </Accordion>

  <Accordion title="What's the difference between VUs and requests?">
    VUs are concurrent users. Each VU makes multiple requests during the test. Total requests depends on VU count, duration, and response times.
  </Accordion>

  <Accordion title="Can I test internal/private APIs?">
    Load tests run from external proxy servers. Internal APIs must be accessible from the internet. For private APIs, consider VPN or expose via secure gateway.
  </Accordion>

  <Accordion title="How are results stored?">
    Test results are stored permanently and accessible from Test Results page. You can compare tests and set baselines for regression detection.
  </Accordion>

  <Accordion title="Can I schedule recurring tests?">
    Use [Test Plans](/guide/load-testing/test-plans) to save configurations and run them on demand or integrate with CI/CD pipelines.
  </Accordion>

  <Accordion title="What happens if I close the browser during a test?">
    Tests continue running server-side. Return to the New Test page or check Test Results to see status and results.
  </Accordion>
</AccordionGroup>