Laravel Performance Testing

https://github.com/volt-test/laravel-performance-testing
Admin
A Laravel package for performance and load testing with VoltTest, featuring automatic route...
Tokens:26,910
Snippets:273
Trust Score:4.1
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Troubleshoot Server Startup with Preferred Port

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

If the server fails to start, try assigning a different port by setting the `$preferredPort` static property. Ensure the 'ext-pcntl' extension is installed and check environment variables.

```php
protected static ?int $preferredPort = 9000; // Use different port
```

--------------------------------

### Example CSV Data Source

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Create a CSV file at storage/volttest/data/users.csv to load dynamic test data. This example shows a simple CSV structure.

```csv
name,email,password
John Doe,user1@example.com,password123
Jane Smith,user2@example.com,password456
Bob Wilson,user3@example.com,password789
```

--------------------------------

### Install Laravel Performance Testing Package

Source: https://context7.com/volt-test/laravel-performance-testing/llms.txt

Install the package using Composer and publish its configuration file using Artisan.

```bash
composer require volt-test/laravel-performance-testing --dev
```

```bash
php artisan vendor:publish --tag=volttest-config
```

--------------------------------

### Install Laravel Performance Testing Package

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Install the package using Composer. It will automatically register its service provider.

```bash
composer require volt-test/laravel-performance-testing --dev
```

--------------------------------

### Volt.test Scenario HTTP Methods

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Demonstrates basic HTTP methods (GET, POST, PUT, PATCH, DELETE) for defining steps within a Volt.test scenario. Includes examples with and without request data.

```php
// HTTP Methods
$scenario->step('Step Name')
    ->get('/path')
    ->post('/path', $data)
    ->put('/path', $data)
    ->patch('/path', $data)
    ->delete('/path);
```

```php
// HTTP Methods with headers parameter for automatic content type detection
$scenario->step('Step Name')
    ->get('/path', ['Accept' => 'application/json'])
    ->post('/path', $data, ['Content-Type' => 'application/json']) // Array will be automatically converted to JSON
    ->put('/path', $data, ['Content-Type' => 'application/json'])  // Array will be automatically converted to JSON
    ->patch('/path', $data, ['Content-Type' => 'application/json']) // Array will be automatically converted to JSON
    ->delete('/path', ['Accept' => 'application/json']);
```

--------------------------------

### Perform HTTP Requests with Headers

Source: https://context7.com/volt-test/laravel-performance-testing/llms.txt

Demonstrates various HTTP methods (GET, POST, PUT, PATCH, DELETE) for API testing. Includes examples of sending headers, JSON data, and extracting data from responses.

```php
<?php

namespace App\VoltTests;

use VoltTest\Laravel\Contracts\VoltTestCase;
use VoltTest\Laravel\VoltTestManager;

class ApiCrudTest implements VoltTestCase
{
    public function define(VoltTestManager $manager): void
    {
        $scenario = $manager->scenario('API CRUD Operations');

        // GET request with headers
        $scenario->step('List Users')
            ->get('/api/users', [
                'Accept' => 'application/json',
                'Authorization' => 'Bearer ${auth_token}'
            ])
            ->expectStatus(200)
            ->extractJson('user_id', 'data.0.id');

        // POST request - array data with JSON content-type automatically encodes to JSON
        $scenario->step('Create User')
            ->post('/api/users', [
                'name' => 'John Doe',
                'email' => 'john@example.com',
                'role' => 'admin'
            ], [
                'Content-Type' => 'application/json',
                'Authorization' => 'Bearer ${auth_token}'
            ])
            ->expectStatus(201)
            ->extractJson('new_user_id', 'data.id');

        // PUT request for full update
        $scenario->step('Update User')
            ->put('/api/users/${new_user_id}', [
                'name' => 'John Updated',
                'email' => 'john.updated@example.com',
                'role' => 'user'
            ], [
                'Content-Type' => 'application/json',
                'Authorization' => 'Bearer ${auth_token}'
            ])
            ->expectStatus(200);

        // PATCH request for partial update
        $scenario->step('Patch User Role')
            ->patch('/api/users/${new_user_id}', [
                'role' => 'moderator'
            ], [
                'Content-Type' => 'application/json',
                'Authorization' => 'Bearer ${auth_token}'
            ])
            ->expectStatus(200);

        // DELETE request
        $scenario->step('Delete User')
            ->delete('/api/users/${new_user_id}', [
                'Authorization' => 'Bearer ${auth_token}'
            ])
            ->expectStatus(204);
    }
}
```

--------------------------------

### Data Source Already Set Error Example

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/CSV_DATA_SOURCE.md

Example of a 'Data source configuration already set' error message. This indicates an attempt to configure a data source for a scenario that already has one, advising the creation of separate scenarios.

```text
Data source configuration already set
```

--------------------------------

### Running PHPUnit Tests

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Execute your PHPUnit tests using the command line. Examples include running all tests, a specific performance test file, or a dedicated performance test suite.

```bash
# Run all tests
./vendor/bin/phpunit
```

```bash
# Run specific performance test
./vendor/bin/phpunit tests/Performance/HomePagePerformanceTest.php
```

```bash
# Run performance test suite
./vendor/bin/phpunit --testsuite=Performance
```

--------------------------------

### Direct URL Testing - GET Request

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Command to perform a simple GET request to a specified URL with custom user and duration settings.

```bash
# Simple GET request
php artisan volttest:run https://example.com --users=10 --duration=1m
```

--------------------------------

### PHPUnit Integration for VoltTest Scenarios

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Run your VoltTest scenarios within PHPUnit for integrated performance testing. This example shows how to instantiate a VoltTest class and run it with specific parameters.

```php
<?php

namespace Tests\Performance;

use App\VoltTests\RegistrationTest;
use VoltTest\Laravel\Testing\PerformanceTestCase;

class RegistrationPerformanceTest extends PerformanceTestCase
{
    protected static bool $enableServerManagement = true;

    public function test_registration_flow_performance(): void
    {
        $test = new RegistrationTest();

        $result = $this->runVoltTest($test, [
            'virtual_users' => 50,
            'duration' => '2m',
        ]);

        $this->assertVTSuccessful($result, 95.0);
        $this->assertVTP95ResponseTime($result, 1500);
        $this->assertVTAverageResponseTime($result, 800);
    }
}
```

--------------------------------

### File Not Found Error Example

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/CSV_DATA_SOURCE.md

Example of a 'File not found' error message related to CSV data sources. It advises checking file paths, permissions, configuration, and existence before test execution.

```text
CSV data source file '/path/to/file.csv' does not exist
```

--------------------------------

### PerformanceTestCase Basic Usage

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Demonstrates the basic setup and usage of the PerformanceTestCase for running API endpoint performance tests with assertions.

```APIDOC
## PerformanceTestCase Basic Usage

### Description
This example shows how to extend `PerformanceTestCase` to test an API endpoint, including setting test options and asserting performance metrics.

### Method
N/A (This is a class extension example)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```php
<?php

namespace Tests\Performance;

use VoltTest\Laravel\Testing\PerformanceTestCase;

class MyPerformanceTest extends PerformanceTestCase
{
    public function test_api_endpoint(): void
    {
        $result = $this->loadTestApi('/api/data', 'GET', [], [
            'virtual_users' => 15,
            'duration' => '1m',
        ]);

        $this->assertVTSuccessful($result); // Default 95% success rate
        $this->assertVTP95ResponseTime($result, 400); // 95% of requests within 400ms
    }
}
```

### Response
#### Success Response (200)
N/A (The `$result` variable contains performance metrics)

#### Response Example
N/A
```

--------------------------------

### Example Saved Report JSON

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Reports are automatically saved as JSON files in storage/volttest/reports/. This is an example structure of a saved report.

```json
{
  "timestamp": "2025-06-23 21:22:39",
  "metadata": {
    "generator": "VoltTest Laravel Package"
  },
  "summary": {
    "duration": "5.521942656s",
    "total_requests": 100,
    "success_rate": 48,
    "requests_per_second": 18.11,
    "success_requests": 48,
    "failed_requests": 52
  },
  "response_times": {
    "min": "22.361918ms",
    "max": "2.061161165s",
    "avg": "343.184136ms",
    "median": "106.130464ms",
    "p95": "1.592337048s",
    "p99": "1.84969821s"
  },
  "metrics": {
    "duration": "5.521942656s",
    "totalRequests": 100,
    "successRate": 48,
    "requestsPerSecond": 18.11,
    "successRequests": 48,
    "failedRequests": 52,
    "responseTime": {
      "min": "22.361918ms",
      "max": "2.061161165s",
      "avg": "343.184136ms",
      "median": "106.130464ms",
      "p95": "1.592337048s",
      "p99": "1.84969821s"
    }
  }
}
```

--------------------------------

### User Performance Test Example

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

A sample performance test class demonstrating defining scenarios, steps, HTTP requests, and assertions. It includes CSRF token extraction for form submissions.

```php
<?php

namespace App	ests;

use VoltTest\Laravel\Contracts\VoltTestCase;
use VoltTest\Laravel\VoltTestManager;

class UserTest implements VoltTestCase
{
    public function define(VoltTestManager $manager): void
    {
        $scenario = $manager->scenario('UserTest');

        // Step 1: Home Page
        $scenario->step('Home Page')
            ->get('/')
            ->expectStatus(200);
            
        // Step 2: Get Registration Page to extract CSRF token
        $scenario->step('Get Registration Page')
            ->get('/register')
            ->expectStatus(200)
            ->extractCsrfToken('csrf_token'); // Extract CSRF token for registration

        // Step 2: User Registration
        $scenario->step('User Registration')
            ->post('/register', [
                '_token' => '${csrf_token}',
                'name' => 'John Doe',
                'email' => 'john@example.com',
                'password' => 'password',
                'password_confirmation' => 'password',
            ] ,
            [
            'Content-Type' => 'application/x-www-form-urlencoded' // Specify content type for form submission
            ])
            ->expectStatus(201);
    }
}
```

--------------------------------

### PHPUnit Performance Test Example

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

This PHP code extends `PerformanceTestCase` to run VoltTest performance tests within PHPUnit. It includes assertions for successful test runs and response times.

```php
<?php

namespace Tests\Performance;

use VoltTest\Laravel\Contracts\VoltTestCase;
use VoltTest\Laravel\Testing\PerformanceTestCase;
use VoltTest\Laravel\VoltTestManager;

class HomePagePerformanceTest extends PerformanceTestCase
{
    protected static bool $enableServerManagement = true;

    public function test_homepage_performance(): void
    {
        $testClass = new class implements VoltTestCase {
            public function define(VoltTestManager $manager): void
            {
                $scenario = $manager->scenario('Homepage Load Test');

                $scenario->step('Load Homepage')
                    ->get('/')
                    ->expectStatus(200);
            }
        };

        $result = $this->runVoltTest($testClass, [
            'virtual_users' => 10,
            'duration' => '30s',
        ]);

        // Assert performance metrics
        $this->assertVTSuccessful($result, 95.0);
        $this->assertVTP95ResponseTime($result, 500);
        $this->assertVTAverageResponseTime($result, 200);
    }
}
```

--------------------------------

### PHPUnit PerformanceTestCase Example

Source: https://context7.com/volt-test/laravel-performance-testing/llms.txt

Extend PerformanceTestCase to run VoltTest performance tests within your PHPUnit suite. Enable server management and define test scenarios using VoltTestCase interface.

```php
<?php

namespace Tests\Performance;

use VoltTest\Laravel\Contracts\VoltTestCase;
use VoltTest\Laravel\Testing\PerformanceTestCase;
use VoltTest\Laravel\VoltTestManager;

class HomepagePerformanceTest extends PerformanceTestCase
{
    // Enable automatic PHP development server management
    protected static bool $enableServerManagement = true;
    protected static ?int $preferredPort = 8080;

    public function test_homepage_loads_under_500ms(): void
    {
        $testClass = new class implements VoltTestCase {
            public function define(VoltTestManager $manager): void
            {
                $scenario = $manager->scenario('Homepage Load Test');

                $scenario->step('Load Homepage')
                    ->get('/')
                    ->expectStatus(200);
            }
        };

        $result = $this->runVoltTest($testClass, [
            'virtual_users' => 20,
            'duration' => '30s',
        ]);

        // Assert performance metrics
        $this->assertVTSuccessful($result, 95.0);
        $this->assertVTP95ResponseTime($result, 500);
        $this->assertVTAverageResponseTime($result, 200);
        $this->assertVTMinimumRPS($result, 50.0);
    }

    public function test_api_endpoint_throughput(): void
    {
        // Quick helper for simple URL load test
        $result = $this->loadTestUrl('/api/health', [
            'virtual_users' => 50,
            'duration' => '1m',
        ]);

        $this->assertVTSuccessful($result, 99.0);
        $this->assertVTMaxResponseTime($result, 2000);
        $this->assertVTMinimumRequests($result, 1000);
    }

    public function test_api_post_performance(): void
    {
        // Quick helper for API endpoint testing
        $result = $this->loadTestApi('/api/users', 'POST', [
            'name' => 'Test User',
            'email' => 'test@example.com'
        ], [
            'virtual_users' => 10,
            'duration' => '30s',
        ]);

        $this->assertVTSuccessful($result);
        $this->assertVTMedianResponseTime($result, 300);
    }
}

```

--------------------------------

### User Authentication Test with CSV Data

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/CSV_DATA_SOURCE.md

An example scenario for user authentication using a CSV file for credentials. It uses 'unique' distribution and extracts an authentication token after login.

```php
// CSV: storage/volttest/data/users.csv
// email,password,user_id,role
// admin@test.com,admin123,1,admin
// user1@test.com,pass123,2,user
// user2@test.com,pass456,3,user

$scenario = $manager->scenario('User Authentication')
    ->dataSource('users.csv', 'unique', true);

$scenario->step('Login')
    ->post('/api/login', [
        'email' => '${email}',
        'password' => '${password}'
    ])
    ->expectStatus(200)
    ->extractJson('auth_token', '$.token');

$scenario->step('Access Dashboard')
    ->get('/dashboard')
    ->header('Authorization', 'Bearer ${auth_token}')
    ->expectStatus(200);
```

--------------------------------

### VoltTest Class Definition

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Define complex test scenarios using VoltTest's fluent API. This example shows how to define steps for registration, including data extraction and status expectations.

```php
<?php

namespace App\VoltTests;

use VoltTest\Laravel\Contracts\VoltTestCase;
use VoltTest\Laravel\VoltTestManager;

class RegistrationTest implements VoltTestCase
{
    public function define(VoltTestManager $manager): void
    {
        $scenario = $manager->scenario('RegistrationTest')
            ->dataSource('registration_users.csv', 'sequential');

        $scenario->step('Home')->get('/')->expectStatus(200);
        $scenario->step('Register')->get('/register')->extractCsrfToken('csrf_token')->expectStatus(200);
        $scenario->step('Submit Registration')
            ->post('/register', [
                '_token' => '${csrf_token}',
                'name' => '${name}',
                'email' => '${email}',
                'password' => '${password}',
                'password_confirmation' => '${password}',
            ])
            ->expectStatus(302);
        $scenario->step('Visit Dashboard')->get('/dashboard')->expectStatus(200);
    }
}
```

--------------------------------

### E-commerce Product Test with CSV Data

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/CSV_DATA_SOURCE.md

An example scenario for browsing e-commerce products using a CSV file for product details. It employs 'random' distribution and extracts CSRF tokens for subsequent actions.

```php
// CSV: storage/volttest/data/products.csv
// product_id,sku,name,price
// 1,SKU001,Laptop,999.99
// 2,SKU002,Mouse,29.99
// 3,SKU003,Keyboard,79.99

$scenario = $manager->scenario('Product Browsing')
    ->dataSource('products.csv', 'random', true);

$scenario->step('View Product')
    ->get('/products/${product_id}')
    ->expectStatus(200)
    ->extractHtml('csrf_token', 'input[name="_token"]', 'value');

$scenario->step('Add to Cart')
    ->post('/cart/add', [
        '_token' => '${csrf_token}',
        'product_id' => '${product_id}',
        'quantity' => '1'
    ])
    ->expectStatus(302);
```

--------------------------------

### Register Scenario with CSV Data Source

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/CSV_DATA_SOURCE.md

Demonstrates setting up a registration scenario that uses a CSV file for user data. Ensure 'users.csv' exists with 'name', 'email', and 'password' columns.

```php
use VoltTest\Laravel\Facades\VoltTest;

$manager = VoltTest::manager();

// Create scenario with CSV data source
$scenario = $manager->scenario('RegisterTest')
    ->dataSource('users.csv', 'unique', true);

$scenario->step('Register')
    ->get('/register')
    ->header('Content-Type', 'application/x-www-form-urlencoded')
    ->extractCsrfToken('token')
    ->expectStatus(200);

$scenario->step('Register')
    ->post('/register', [
        '_token' => '${token}',
        'name' => '${name}',           // From CSV column
        'email' => '${email}',         // From CSV column
        'password' => '${password}',   // From CSV column
        'password_confirmation' => '${password}',
    ])
    ->header('Content-Type', 'application/x-www-form-urlencoded')
    ->expectStatus(302);

$scenario->step('Get Dashboard')
    ->get('/dashboard')
    ->header('Content-Type', 'text/html')
    ->expectStatus(200);
```

--------------------------------

### Implement Realistic Load Patterns

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Use the runVoltTest method with gradual ramp-up and realistic virtual user counts for accurate load simulation. Avoid sudden spikes without ramp-up for better performance insights.

```php
// Good: Gradual ramp-up with realistic user count
$result = $this->runVoltTest($testClass, [
    'virtual_users' => 20,
    'duration' => '2m',
    'ramp_up' => '30s',
]);
```

```php
// Avoid: Sudden spike without ramp-up
$result = $this->runVoltTest($testClass, [
    'virtual_users' => 100,
    'duration' => '10s',
]);
```

--------------------------------

### Create Test Scenarios with Weights

Source: https://context7.com/volt-test/laravel-performance-testing/llms.txt

Defines two test scenarios, 'Product Browsing' and 'Product Search', with different traffic weights (70% and 30% respectively). Each scenario includes a single test step.

```php
<?php

namespace App\VoltTests;

use VoltTest\Laravel\Contracts\VoltTestCase;
use VoltTest\Laravel\VoltTestManager;

class MultiScenarioTest implements VoltTestCase
{
    public function define(VoltTestManager $manager): void
    {
        // Create primary scenario with higher weight (70% of traffic)
        $browseScenario = $manager->scenario('Product Browsing')
            ->weight(70);

        $browseScenario->step('Browse Products')
            ->get('/products')
            ->expectStatus(200);

        // Create secondary scenario with lower weight (30% of traffic)
        $searchScenario = $manager->scenario('Product Search')
            ->weight(30);

        $searchScenario->step('Search Products')
            ->get('/products/search?q=laptop')
            ->expectStatus(200);
    }
}
```

--------------------------------

### Invalid Distribution Mode Error Example

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/CSV_DATA_SOURCE.md

Example of an 'Invalid data source mode' error message. It reminds users to use only the supported distribution modes: 'unique', 'random', or 'sequential'.

```text
Invalid data source mode. Use "sequential", "random" or "unique"
```

--------------------------------

### Multiple Scenarios with Different Data Sources

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/CSV_DATA_SOURCE.md

Demonstrates how to create multiple independent scenarios, each with its own data source configuration. This is useful for testing different aspects of an application with distinct datasets.

```php
$userScenario = $manager->scenario('User Actions')
    ->dataSource('users.csv', 'unique');

$productScenario = $manager->scenario('Product Admin')
    ->dataSource('products.csv', 'random');
```

--------------------------------

### Get Current Base URL

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Retrieve the currently configured base URL using the `getBaseUrl` method.

```php
$url = $this->getBaseUrl();
```

--------------------------------

### Combining Multiple Configuration Options

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Multiple configuration options can be combined for comprehensive test execution, including user count, duration, debugging, and output streaming.

```bash
php artisan volttest:run UserTest \
    --users=50 \
    --duration=5m \
    --debug \
    --stream
```

--------------------------------

### Reduce Virtual Users in VoltTest

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Lower the number of virtual users to mitigate memory issues during large tests. Start with a small number.

```php
'virtual_users' => 10, // Start small
```

--------------------------------

### Run All Tests

Source: https://context7.com/volt-test/laravel-performance-testing/llms.txt

Execute all performance tests located in the default test directory using the `volttest:run` Artisan command.

```bash
php artisan volttest:run
```

--------------------------------

### Publish Configuration File

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Publish the configuration file for the package using the Artisan vendor:publish command.

```bash
php artisan vendor:publish --tag=volttest-config
```

--------------------------------

### Set Custom Base URL

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Override the default base URL for testing by implementing `setUp` and calling `setBaseUrl`. This is useful when the test server runs on a different host or port.

```php
protected function setUp(): void
{
    parent::setUp();
    $this->setBaseUrl('http://localhost:8080');
}
```

--------------------------------

### Configure VoltTest Ramp-Up Time

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Add ramp-up time to gradually increase load during tests, leading to more consistent results. Specify the duration in your configuration.

```php
'ramp_up' => '30s', // Gradual load increase
```

--------------------------------

### Quick Load Testing Helpers

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Convenient helper methods `loadTestUrl` and `loadTestApi` for quickly setting up and running performance tests on specific URLs or API endpoints.

```APIDOC
## Quick Load Testing Helpers

### Description
These helper methods simplify the process of running performance tests for single URLs or API endpoints without needing to define a full `VoltTestCase` class for each.

### `loadTestUrl(string $url, array $options = [])`

#### Description
Quick helper to test a single URL.

#### Parameters
- **`$url`** (string) - Required - The URL path to test (e.g., '/').
- **`$options`** (array) - Optional - Configuration options for the test (e.g., `virtual_users`, `duration`).

#### Request Example
```php
public function test_homepage_load(): void
{
    $result = $this->loadTestUrl('/', [
        'virtual_users' => 10,
        'duration' => '30s',
    ]);

    $this->assertVTSuccessful($result);
}
```

### `loadTestApi(string $endpoint, string $method = 'GET', array $data = [], array $options = [])`

#### Description
Quick helper to test API endpoints.

#### Parameters
- **`$endpoint`** (string) - Required - The API endpoint path (e.g., '/api/users').
- **`$method`** (string) - Optional - The HTTP method to use (default: 'GET').
- **`$data`** (array) - Optional - The request payload for methods like POST or PUT.
- **`$options`** (array) - Optional - Configuration options for the test (e.g., `virtual_users`, `duration`).

#### Request Example
```php
public function test_api_performance(): void
{
    $result = $this->loadTestApi('/api/users', 'POST', [
        'name' => 'John Doe',
        'email' => 'john@example.com',
    ], [
        'virtual_users' => 15,
    ]);

    $this->assertVTSuccessful($result);
    $this->assertVTP99ResponseTime($result, 1000);
}
```

### Response
#### Success Response (200)
N/A (The `$result` variable contains performance metrics)

#### Response Example
N/A
```

--------------------------------

### Create a PHPUnit Test Class

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Extend `PerformanceTestCase` to write performance tests. Use `loadTestUrl` to specify the URL and options like virtual users and stream output. Assert performance metrics using methods like `assertVTSuccessful`, `assertVTP95ResponseTime`, and `assertVTAverageResponseTime`.

```php
<?php

namespace Tests\Performance;

use VoltTest\Laravel\Contracts\VoltTestCase;
use VoltTest\Laravel\Testing\PerformanceTestCase;
use VoltTest\Laravel\VoltTestManager;

class HomePagePerformanceTest extends PerformanceTestCase
{
    /**
     * Test homepage performance under load.
     */
    public function test_homepage_performance(): void
    {
        $this->loadTestUrl('/', [
            'virtual_users' => 10,
            'stream' => true, // make output visible in console
        ]);

        // Assert performance metrics
        $this->assertVTSuccessful($result, 95.0); // At least 95% success rate for requests
        $this->assertVTP95ResponseTime($result, 500); // 95% of requests complete within 500ms or less
        $this->assertVTAverageResponseTime($result, 200); // Average response time under 200ms
    }
}
```

--------------------------------

### Basic Volt-Test Command Syntax

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

The `php artisan volttest:run` command is used to execute performance tests. It accepts an optional test name or URL and various options for configuration.

```bash
php artisan volttest:run [test] [options]
```

--------------------------------

### Run Tests with Custom Users and Duration

Source: https://context7.com/volt-test/laravel-performance-testing/llms.txt

Configure the number of virtual users and test duration for performance tests using the `--users` and `--duration` flags.

```bash
php artisan volttest:run UserTest --users=50 --duration=2m
```

--------------------------------

### Enable Automatic Server Management in PHPUnit

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Set the `$enableServerManagement` static property to true to automatically start and stop a PHP development server for your tests. The `$preferredPort` can be used to specify the port.

```php
class MyPerformanceTest extends PerformanceTestCase
{
    protected static bool $enableServerManagement = true;
    protected static ?int $preferredPort = 8000;

    public function test_with_auto_server(): void
    {
        // Server is automatically started before tests
        // and stopped after tests complete
        $result = $this->loadTestUrl('/');
        $this->assertVTSuccessful($result);
    }
}
```

--------------------------------

### Run PHPUnit Performance Tests

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Execute your performance tests using the PHPUnit command. Ensure the path to your test file is correct.

```bash
./vendor/bin/phpunit tests/Performance/HomePagePerformanceTest.php
```

--------------------------------

### Define Test Scenarios with VoltTestCase Interface

Source: https://context7.com/volt-test/laravel-performance-testing/llms.txt

Implement the `VoltTestCase` interface and its `define()` method to configure test scenarios using the `VoltTestManager`. This involves defining steps with HTTP requests, assertions, and think times.

```php
<?php

namespace App\VoltTests;

use VoltTest\Laravel\Contracts\VoltTestCase;
use VoltTest\Laravel\VoltTestManager;

class UserRegistrationTest implements VoltTestCase
{
    public function define(VoltTestManager $manager): void
    {
        $scenario = $manager->scenario('User Registration Flow');

        // Step 1: Load registration page
        $scenario->step('Load Registration Page')
            ->get('/register')
            ->expectStatus(200)
            ->extractCsrfToken('csrf_token');

        // Step 2: Submit registration form
        $scenario->step('Submit Registration')
            ->post('/register', [
                '_token' => '${csrf_token}',
                'name' => 'Test User',
                'email' => 'test@example.com',
                'password' => 'password123',
                'password_confirmation' => 'password123',
            ], [
                'Content-Type' => 'application/x-www-form-urlencoded'
            ])
            ->expectStatus(302)
            ->thinkTime('2s');

        // Step 3: Access dashboard after registration
        $scenario->step('Access Dashboard')
            ->get('/dashboard')
            ->expectStatus(200);
    }
}

```

--------------------------------

### Enable Server Management via Environment Variable

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Alternatively, enable server management by setting the VOLTTEST_ENABLE_SERVER_MANAGEMENT environment variable to true when running PHPUnit.

```bash
VOLTTEST_ENABLE_SERVER_MANAGEMENT=true ./vendor/bin/phpunit
```

--------------------------------

### Perform Quick Load Tests on URLs and APIs

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Use this class to perform quick load tests on specific URLs or API endpoints. Ensure your `PerformanceTestCase` is correctly configured.

```php
<?php

namespace Tests\Performance;

use VoltTest\Laravel\Testing\PerformanceTestCase;

class QuickLoadTests extends PerformanceTestCase
{
    protected static bool $enableServerManagement = true;

    public function test_homepage_quick_load(): void
    {
        $result = $this->loadTestUrl('/');
        $this->assertVTSuccessful($result);
    }

    public function test_api_users_endpoint(): void
    {
        $result = $this->loadTestApi('/api/users', 'GET');
        $this->assertVTSuccessful($result);
        $this->assertVTP95ResponseTime($result, 300);
    }

    public function test_api_create_user(): void
    {
        $result = $this->loadTestApi('/api/users', 'POST', [
            'name' => 'Test User',
            'email' => 'test@example.com',
        ]);

        $this->assertVTSuccessful($result);
    }
}
```

--------------------------------

### Run Tests from Custom Path

Source: https://context7.com/volt-test/laravel-performance-testing/llms.txt

Specify a custom directory for performance tests using the `--path` option with the `volttest:run` command.

```bash
php artisan volttest:run --path=tests/Performance
```

--------------------------------

### Load CSV Data for User Scenarios

Source: https://context7.com/volt-test/laravel-performance-testing/llms.txt

Configure scenarios to load unique, random, or sequential data from CSV files for realistic user simulations. Ensure CSV files are placed in the correct directory.

```php
<?php

namespace App\VoltTests;

use VoltTest\Laravel\Contracts\VoltTestCase;
use VoltTest\Laravel\VoltTestManager;

// CSV file: storage/volttest/data/users.csv
// name,email,password
// John Doe,user1@example.com,password123
// Jane Smith,user2@example.com,password456
// Bob Wilson,user3@example.com,password789

class CsvDataSourceTest implements VoltTestCase
{
    public function define(VoltTestManager $manager): void
    {
        // Unique distribution: each virtual user gets a different row
        $scenario = $manager->scenario('User Registration with CSV')
            ->dataSource('users.csv', 'unique', true);

        $scenario->step('Load Registration')
            ->get('/register')
            ->expectStatus(200)
            ->extractCsrfToken('token');

        $scenario->step('Submit Registration')
            ->post('/register', [
                '_token' => '${token}',
                'name' => '${name}',           // From CSV column
                'email' => '${email}',         // From CSV column
                'password' => '${password}',   // From CSV column
                'password_confirmation' => '${password}',
            ], ['Content-Type' => 'application/x-www-form-urlencoded'])
            ->expectStatus(302);

        // Random distribution example for product browsing
        $productScenario = $manager->scenario('Product Views')
            ->dataSource('products.csv', 'random');

        $productScenario->step('View Product')
            ->get('/products/${product_id}')
            ->expectStatus(200);

        // Sequential distribution for predictable patterns
        $orderScenario = $manager->scenario('Order Processing')
            ->dataSource('orders.csv', 'sequential');

        $orderScenario->step('Process Order')
            ->post('/api/orders', [
                'customer_id' => '${customer_id}',
                'product_ids' => '${product_ids}'
            ], ['Content-Type' => 'application/json'])
            ->expectStatus(201);
    }
}

```

--------------------------------

### Direct Load Testing with a URL

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Use the `--url` option to treat the test argument as a URL for direct load testing, specifying HTTP method, headers, body, and content type.

```bash
php artisan volttest:run --url --method=POST --headers='{"Authorization":"Bearer token"}' --body='{"name":"John"}' --content-type=application/json --code-status=201 --scenario-name="API Load Test"
```

--------------------------------

### Configuration Methods

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Methods for configuring the base URL for performance tests.

```APIDOC
## Configuration Methods

### Description
These methods allow you to customize the base URL used for your performance tests, which is particularly useful when the test server runs on a different host or port than your application.

### `setBaseUrl(string $url)`

#### Description
Set a custom base URL for testing. This is useful if the server is running on a different host/port.

#### Parameters
- **`$url`** (string) - Required - The custom base URL (e.g., 'http://localhost:8080').

#### Request Example
```php
protected function setUp(): void
{
    parent::setUp();
    $this->setBaseUrl('http://localhost:8080');
}
```

### `getBaseUrl()`

#### Description
Get the current base URL that is being used for testing.

#### Parameters
N/A

#### Request Example
```php
$url = $this->getBaseUrl();
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Enable Server Management in VoltTest

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Enable server management to resolve connection refused errors during tests. Ensure this property is set to true in your test class.

```php
protected static bool $enableServerManagement = true;
```

--------------------------------

### VoltTest Quick Load Testing Helpers

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Simplify common load testing tasks with these helper methods. Use `loadTestUrl` for web pages and `loadTestApi` for API endpoints.

```php
$result = $this->loadTestUrl('/');
$this->assertVTSuccessful($result);
```

```php
$result = $this->loadTestApi('/api/users', 'POST', [
    'name' => 'John Doe',
    'email' => 'john@example.com',
]);
$this->assertVTSuccessful($result);
```

--------------------------------

### Enable HTTP Debugging

Source: https://context7.com/volt-test/laravel-performance-testing/llms.txt

Enable detailed HTTP debugging output for troubleshooting by adding the `--debug` flag to the `volttest:run` command.

```bash
php artisan volttest:run ApiTest --debug
```

--------------------------------

### Organize Performance Tests Directory Structure

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Create a dedicated 'tests/Performance' directory to house all your performance test files. This structure helps in organizing tests by type.

```text
tests/
├── Feature/
├── Unit/
└── Performance/
    ├── Api/
    │   ├── AuthenticationTest.php
    │   └── UserApiTest.php
    ├── Web/
    │   ├── HomePageTest.php
    │   └── CheckoutTest.php
```

--------------------------------

### Running Volt-Tests with Custom Configuration

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Configure test runs using options like `--users`, `--duration`, and `--debug` to customize the load and debugging behavior.

```bash
php artisan volttest:run --users=20 --duration=2m --debug
```

--------------------------------

### Create VoltTest Performance Test Classes

Source: https://context7.com/volt-test/laravel-performance-testing/llms.txt

Use the `volttest:make` Artisan command to generate new performance test classes. Options include automatic route discovery, filtering routes by pattern or method, and interactive selection.

```bash
# Create a basic test class
php artisan volttest:make UserTest
```

```bash
# Create with automatic route discovery
php artisan volttest:make ApiTest --routes
```

```bash
# Filter routes by URI pattern
php artisan volttest:make ApiTest --routes --filter="api/*"
```

```bash
# Filter by HTTP method
php artisan volttest:make ApiTest --routes --method=GET
```

```bash
# Only authenticated routes
php artisan volttest:make ApiTest --routes --auth
```

```bash
# Interactive route selection
php artisan volttest:make CheckoutTest --routes --select --filter="checkout/*"
```

--------------------------------

### PHP Test Case with CSV Data Source

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

This PHP code demonstrates how to use a CSV data source within a VoltTest scenario. It configures the data source and uses its columns to populate request parameters.

```php
<?php

namespace App\VoltTests;

use VoltTest\Laravel\Contracts\VoltTestCase;
use VoltTest\Laravel\VoltTestManager;

class RegisterTest implements VoltTestCase
{
    public function define(VoltTestManager $manager): void
    {
        // Configure CSV data source
        $scenario = $manager->scenario('RegisterTest')
            ->dataSource('users.csv');

        // Step 1: Get Register Page
        $scenario->step('Register')
            ->get('/register', [
            'Content-Type' => 'application/x-www-form-urlencoded'
            ])
            ->extractCsrfToken('token')
            ->expectStatus(200);

        // Step 2: Submit Registration
        $scenario->step('Register')
            ->post('/register', [
                '_token' => '${token}',
                'name' => '${name}',           // From CSV column
                'email' => '${email}',         // From CSV column
                'password' => '${password}',   // From CSV column
                'password_confirmation' => '${password}',
            ],[
                'Content-Type' => 'application/x-www-form-urlencoded' // Specify content type for form submission
            ])
            ->expectStatus(302);

        // Step 3: Access Dashboard
        $scenario->step('Get Dashboard')
            ->get('/dashboard', [
            'Content-Type' => 'text/html',
            ])
            ->expectStatus(200);
    }
}
```

--------------------------------

### Run a Reusable VoltTest Class

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Execute a pre-defined `VoltTestCase` using `runVoltTest`. Specify options like `virtual_users`, `duration`, `ramp_up`, `stream`, and `http_debug`.

```php
$result = $this->runVoltTest($testClass, [
    'virtual_users' => 20,
    'duration' => '1m',
    'ramp_up' => '10s',
    'stream' => false,
    'http_debug' => false,
]);
```

--------------------------------

### Combined Testing Options

Source: https://context7.com/volt-test/laravel-performance-testing/llms.txt

Utilize a combination of options for comprehensive performance testing, including test path, users, duration, debugging, and real-time streaming.

```bash
php artisan volttest:run FullFlowTest \
    --users=100 \
    --duration=5m \
    --debug \
    --stream
```

--------------------------------

### Document Baseline Performance Metrics

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Include detailed baseline performance metrics in test case docblocks for future reference and comparison. This helps in tracking performance regressions over time.

```php
/**
 * Baseline performance test for homepage.
 *
 * Baseline metrics (as of 2025-01-15):
 * - P95: 180ms
 * - P99: 250ms
 * - Success rate: 99.5%
 */
public function test_homepage_baseline(): void
{
    $result = $this->loadTestUrl('/');

    $this->assertVTSuccessful($result, 99.0);
    $this->assertVTP95ResponseTime($result, 200);
    $this->assertVTP99ResponseTime($result, 300);
}
```

--------------------------------

### Load Test a Single URL

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Use `loadTestUrl` as a quick helper to test the performance of a specific URL. Configure `virtual_users` and `duration` as needed.

```php
public function test_homepage_load(): void
{
    $result = $this->loadTestUrl('/', [
        'virtual_users' => 10,
        'duration' => '30s',
    ]);

    $this->assertVTSuccessful($result);
}
```

--------------------------------

### PHPUnit Configuration for VoltTest

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Add this XML configuration to your `phpunit.xml` file to enable console reporting of performance metrics via the VoltTest extension.

```xml
<extensions>
    <bootstrap class="VoltTest\Laravel\Testing\VoltTestExtension"/>
</extensions>
```

--------------------------------

### Generate User Test Class

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Command to generate a new performance test class with route discovery enabled. Use `--select` for interactive route selection.

```bash
php artisan volttest:make UserTest --routes --select
```

--------------------------------

### Configure Server Management Properties

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Customize server management behavior by setting static properties like `$enableServerManagement`, `$preferredPort`, and `$enableDebugForServerManagement` in your test class.

```php
protected static bool $enableServerManagement = true;
```

```php
protected static ?int $preferredPort = 9000;
```

```php
protected static bool $enableDebugForServerManagement = true;
```

--------------------------------

### Running VoltTests with runVoltTest

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Utilize the `runVoltTest` method to execute existing VoltTestCase classes with custom options for load testing.

```APIDOC
## Running VoltTests with runVoltTest

### Description
The `runVoltTest` method allows you to execute a specified `VoltTestCase` class, providing flexibility in configuring test parameters like virtual users, duration, and ramp-up time.

### Method
`runVoltTest(VoltTestCase $testClass, array $options = [])`

### Endpoint
N/A

### Parameters
#### Method Parameters
- **`$testClass`** (VoltTestCase) - Required - An instance of the VoltTestCase class to run.
- **`$options`** (array) - Optional - An associative array of options to configure the test run.
  - **`virtual_users`** (int) - Number of concurrent users (default: 5).
  - **`duration`** (string) - Test duration (e.g., '30s', '2m', '1h').
  - **`ramp_up`** (string) - Gradual user ramp-up time (e.g., '10s').
  - **`stream`** (bool) - Stream output to console (default: false).
  - **`http_debug`** (bool) - Enable HTTP debugging (default: false).

### Request Example
```php
$result = $this->runVoltTest($testClass, [
    'virtual_users' => 20,
    'duration' => '1m',
    'ramp_up' => '10s',
    'stream' => false,
    'http_debug' => false,
]);
```

### Response
#### Success Response (200)
N/A (The `$result` variable contains performance metrics)

#### Response Example
N/A
```

--------------------------------

### Set VoltTest Base URL

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Configure the base URL for your tests to match the running server. This is crucial for resolving connection issues.

```php
$this->setBaseUrl('http://localhost:8000');
```

--------------------------------

### Generate API Test with Route Discovery

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Commands to generate test classes using route discovery, with options to include all routes, filter by pattern, method, or authentication status.

```bash
# Include all routes
php artisan volttest:make ApiTest --routes

# Filter by pattern
php artisan volttest:make ApiTest --routes --filter="api/*"

# Filter by HTTP method
php artisan volttest:make ApiTest --routes --method=GET

# Include only authenticated routes
php artisan volttest:make ApiTest --routes --auth

# Interactive route selection
php artisan volttest:make ApiTest --routes --select --filter="api/*"
```

--------------------------------

### Setting Think Time Between Requests

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/README.md

Use the `thinkTime()` method to introduce a pause between requests in a scenario step, simulating realistic user behavior.

```php
$scenario->step('Step Name')
    ->thinkTime('2s');
```

--------------------------------

### URL Testing with POST and JSON Body

Source: https://context7.com/volt-test/laravel-performance-testing/llms.txt

Conduct URL load tests using the POST method with custom headers, JSON body, and specific content type and expected status code.

```bash
php artisan volttest:run https://api.example.com/users \
    --method=POST \
    --headers='{"Authorization":"Bearer token123","Accept":"application/json"}' \
    --body='{"name":"John","email":"john@example.com"}' \
    --content-type="application/json" \
    --code-status=201 \
    --scenario-name="Create User Load Test"
```

--------------------------------

### Set Appropriate Response Time Thresholds

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Define specific thresholds for different endpoints based on their complexity and expected performance. Use assertions like assertVTP95ResponseTime to validate performance.

```php
// Different thresholds for different endpoints
public function test_homepage(): void
{
    $result = $this->loadTestUrl('/');
    $this->assertVTP95ResponseTime($result, 200); // Fast static page
}
```

```php

public function test_complex_report(): void
{
    $result = $this->loadTestUrl('/reports/analytics');
    $this->assertVTP95ResponseTime($result, 2000); // Complex query
}
```

--------------------------------

### Use CSV Data Sources for User Authentication Tests

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Integrate CSV data sources to provide dynamic input for tests, such as user credentials for authentication. This allows for testing with varied data efficiently.

```php
public function test_user_authentication(): void
{
    $testClass = new class implements VoltTestCase {
        public function define(VoltTestManager $manager): void
        {
            $scenario = $manager->scenario('Auth Test')
                ->dataSource('test-users.csv', 'unique');

            $scenario->step('Login')
                ->post('/login', [
                    'email' => '${email}',
                    'password' => '${password}',
                ])
                ->expectStatus(200);
        }
    };

    $result = $this->runVoltTest($testClass);
    $this->assertVTSuccessful($result);
}
```

--------------------------------

### Assert Maximum Requests Per Second (RPS)

Source: https://github.com/volt-test/laravel-performance-testing/blob/main/docs/PHPUNIT_INTEGRATION.md

Use `assertVTMaximumRPS` to assert that the requests per second rate does not exceed a specified maximum, useful for detecting unrealistic performance.

```php
$this->assertVTMaximumRPS($result, 1000.0); // RPS <= 1000
```
Tokens:
Raw