VoltTest PHP SDK

https://github.com/volt-test/php-sdk
Admin
VoltTest PHP SDK is a high-performance PHP performance testing SDK powered by a Golang engine,...
Tokens:6,801
Snippets:32
Trust Score:4.1
License:MIT
Update:9 months ago
Show doc for...
Tokens:
Raw
### HTTP Request Configuration

Source: https://context7.com/volt-test/php-sdk/llms.txt

This section details how to configure various HTTP requests (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) within a scenario, including setting headers, request bodies, response validation, and think times.

```APIDOC
## Step - HTTP Request Configuration

### Description
Configures individual HTTP requests within a scenario, supporting all standard HTTP methods, custom headers, request bodies, response validation, and data extraction.

### Methods
- GET
- POST
- PUT
- PATCH
- DELETE
- HEAD
- OPTIONS

### Endpoints
Examples provided cover:
- `https://api.example.com/users`
- `https://api.example.com/users/{userId}`
- `https://api.example.com/health`

### Parameters
#### Headers
- `Accept` (string) - Example: `application/json`
- `Content-Type` (string) - Example: `application/json`
- `Authorization` (string) - Example: `Bearer {{token}}`

#### Request Body
- **POST**: JSON object for creating a user (e.g., `{"name": "John Doe", "email": "john@example.com"}`)
- **PUT**: JSON object for updating a user (e.g., `{"name": "John Updated"}`)
- **PATCH**: JSON string for partial update (e.g., `"{\"status\": \"active\"}"`) 

### Request Example (POST)
```php
$scenario->step('Create User')
    ->post('https://api.example.com/users', json_encode([
        'name' => 'John Doe',
        'email' => 'john@example.com'
    ]))
    ->header('Content-Type', 'application/json')
    ->header('Authorization', 'Bearer {{token}}')
    ->extractFromJson('userId', 'data.id')
    ->validateStatus('create-success', 201);
```

### Response
#### Success Response Codes
- **GET**: 200
- **POST**: 201
- **PUT**: 200
- **PATCH**: 200
- **DELETE**: 204
- **HEAD**: 200
- **OPTIONS**: 200

### Additional Features
- **Think Time**: `setThinkTime('1s')` - Sets a delay after the step.
- **Data Extraction**: `extractFromJson('key', 'json.path')` - Captures data from the response.
```

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

### Configure and Run Main Test - VoltTest PHP SDK

Source: https://context7.com/volt-test/php-sdk/llms.txt

Demonstrates how to create a new test, configure parameters like virtual users, duration, and ramp-up time, define scenarios, and execute the test using the VoltTest PHP SDK. It also shows how to access and display test results.

```php
<?php

use VoltTest\VoltTest;

// Create a new test with name and description
$test = new VoltTest('API Load Test', 'Testing production API endpoints');

// Configure test parameters
$test
    ->setVirtualUsers(100)      // Number of concurrent virtual users
    ->setDuration('5m')         // Test duration: 5 minutes (supports s/m/h)
    ->setRampUp('30s')          // Gradually start users over 30 seconds
    ->setTarget('60s')          // Idle timeout for connections
    ->setHttpDebug(true);       // Enable HTTP request/response debugging

// Create scenarios and run test
$scenario = $test->scenario('User Flow', 'Simulate typical user journey');
$scenario->step('Homepage')->get('https://api.example.com/');

// Execute test and get results
$result = $test->run(false);  // Set true for streaming output

echo "Duration: " . $result->getDuration() . "\n";
echo "Total Requests: " . $result->getTotalRequests() . "\n";
echo "Success Rate: " . $result->getSuccessRate() . "%\n";
echo "Requests/sec: " . $result->getRequestsPerSecond() . "\n";

```

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

### PHP E-Commerce Load Test with Scenarios

Source: https://context7.com/volt-test/php-sdk/llms.txt

This PHP script sets up and runs a detailed e-commerce load test. It configures virtual users, duration, ramp-up, and defines three distinct user scenarios (Purchase, Browse Only, Health Check) with specific weights and actions. It also includes data extraction and response validation.

```php
<?php

use VoltTest\VoltTest;
use VoltTest\DataSourceConfiguration;

// Initialize test
$test = new VoltTest(
    'E-Commerce Load Test',
    'Full application load test simulating real user behavior'
);

// Configure test parameters
$test
    ->setVirtualUsers(200)    // 200 concurrent users
    ->setDuration('10m')      // 10 minute test
    ->setRampUp('2m')         // Ramp up over 2 minutes
    ->setTarget('30s');       // 30 second idle timeout

// Scenario 1: Browse and Purchase (60% of traffic)
$purchaseFlow = $test->scenario('Purchase Flow', 'Complete purchase journey')
    ->setWeight(60)
    ->setThinkTime('3s')
    ->autoHandleCookies();

$purchaseFlow->step('Homepage')
    ->get('https://shop.example.com/')
    ->extractFromHtml('csrfToken', 'meta[name="csrf-token"]', 'content')
    ->validateStatus('homepage', 200);

$purchaseFlow->step('Login')
    ->post('https://shop.example.com/api/auth', json_encode([
        'email' => 'test@example.com',
        'password' => 'password123'
    ]))
    ->header('Content-Type', 'application/json')
    ->header('X-CSRF-Token', '{{csrfToken}}')
    ->extractFromJson('accessToken', 'token')
    ->extractFromJson('userId', 'user.id')
    ->validateStatus('login', 200)
    ->setThinkTime('2s');

$purchaseFlow->step('Browse Products')
    ->get('https://shop.example.com/api/products?category=electronics')
    ->header('Authorization', 'Bearer {{accessToken}}')
    ->extractFromJson('productId', 'products[0].id')
    ->validateStatus('browse', 200);

$purchaseFlow->step('Add to Cart')
    ->post('https://shop.example.com/api/cart', json_encode([
        'product_id' => '{{productId}}',
        'quantity' => 1
    ]))
    ->header('Content-Type', 'application/json')
    ->header('Authorization', 'Bearer {{accessToken}}')
    ->extractFromJson('cartId', 'cart.id')
    ->validateStatus('add-cart', 201);

$purchaseFlow->step('Checkout')
    ->post('https://shop.example.com/api/checkout', json_encode([
        'cart_id' => '{{cartId}}',
        'payment_method' => 'credit_card'
    ]))
    ->header('Content-Type', 'application/json')
    ->header('Authorization', 'Bearer {{accessToken}}')
    ->validateStatus('checkout', 200);

// Scenario 2: Browse Only (30% of traffic)
$browseFlow = $test->scenario('Browse Only', 'Users just browsing')
    ->setWeight(30)
    ->setThinkTime('5s');

$browseFlow->step('Homepage')
    ->get('https://shop.example.com/')
    ->validateStatus('home', 200);

$browseFlow->step('Category Page')
    ->get('https://shop.example.com/category/electronics')
    ->validateStatus('category', 200);

$browseFlow->step('Product Details')
    ->get('https://shop.example.com/product/12345')
    ->validateStatus('product', 200);

// Scenario 3: API Health Check (10% of traffic)
$healthCheck = $test->scenario('Health Check', 'API monitoring')
    ->setWeight(10);

$healthCheck->step('Health')
    ->get('https://shop.example.com/api/health')
    ->validateStatus('health', 200);

$healthCheck->step('Status')
    ->get('https://shop.example.com/api/status')
    ->extractFromJson('version', 'version')
    ->validateStatus('status', 200);

// Execute test
echo "Starting load test...\n";
$result = $test->run(true);  // Stream output

// Display results
echo "\n=== Test Results ===\n";
echo "Duration: " . $result->getDuration() . "\n";
echo "Total Requests: " . $result->getTotalRequests() . "\n";
echo "Success Rate: " . $result->getSuccessRate() . "%\n";
echo "Throughput: " . $result->getRequestsPerSecond() . " req/sec\n";
echo "\nResponse Times:\n";
echo "  Average: " . $result->getAvgResponseTime() . "\n";
echo "  P95: " . $result->getP95ResponseTime() . "\n";
echo "  P99: " . $result->getP99ResponseTime() . "\n";

// Save detailed metrics
$metrics = $result->getAllMetrics();
file_put_contents('test-results.json', json_encode($metrics, JSON_PRETTY_PRINT));

```

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

### Define Test Scenarios with Data Sources - VoltTest PHP SDK

Source: https://context7.com/volt-test/php-sdk/llms.txt

Illustrates how to define complex test scenarios within the VoltTest PHP SDK, including setting weights, think times, automatic cookie handling, and integrating external data sources like CSV files for dynamic parameterization. It also shows how to define steps with HTTP requests, headers, data extraction, and status validation.

```php
<?php

use VoltTest\VoltTest;
use VoltTest\DataSourceConfiguration;

$test = new VoltTest('E-Commerce Test', 'Shopping flow simulation');
$test->setVirtualUsers(50)->setDuration('2m');

// Create scenario with configuration
$scenario = $test->scenario('Purchase Flow', 'Complete purchase journey')
    ->setWeight(70)              // 70% of traffic goes to this scenario
    ->setThinkTime('2s')         // Wait 2 seconds between steps
    ->autoHandleCookies();       // Automatically manage session cookies

// Add data source for dynamic test data (CSV file)
$dataConfig = new DataSourceConfiguration(
    '/path/to/users.csv',        // CSV file path
    'random',                    // Mode: 'sequential', 'random', or 'unique'
    true                         // Has header row
);
$scenario->setDataSourceConfiguration($dataConfig);

// Define steps in the scenario
$scenario->step('Login')
    ->post('https://api.example.com/auth/login', '{"email": "{{email}}", "password": "{{password}}"}')
    ->header('Content-Type', 'application/json')
    ->extractFromJson('authToken', 'data.token')
    ->validateStatus('login-success', 200);

$scenario->step('Add to Cart')
    ->post('https://api.example.com/cart', '{"product_id": 123, "quantity": 1}')
    ->header('Authorization', 'Bearer {{authToken}}')
    ->header('Content-Type', 'application/json')
    ->validateStatus('cart-success', 201);

// Second scenario with lower weight
$browseScenario = $test->scenario('Browse Products', 'Product browsing')
    ->setWeight(30);             // 30% of traffic

$browseScenario->step('List Products')
    ->get('https://api.example.com/products')
    ->validateStatus('products-success', 200);

$result = $test->run();

```

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

### Configure HTTP Requests with Step Class in PHP

Source: https://context7.com/volt-test/php-sdk/llms.txt

The Step class in the VoltTest PHP SDK allows configuration of individual HTTP requests within a scenario. It supports various HTTP methods, custom headers, request bodies, response validation, and data extraction. Dependencies include the VoltTest class.

```php
<?php

use VoltTest\VoltTest;

$test = new VoltTest('API Test', 'REST API testing');
$test->setVirtualUsers(10)->setDuration('1m');

$scenario = $test->scenario('CRUD Operations', 'Test all endpoints');

// GET request
$scenario->step('Get Users')
    ->get('https://api.example.com/users')
    ->header('Accept', 'application/json')
    ->validateStatus('get-success', 200)
    ->setThinkTime('1s');        // Wait 1 second after this step

// POST request with JSON body
$scenario->step('Create User')
    ->post('https://api.example.com/users', json_encode([
        'name' => 'John Doe',
        'email' => 'john@example.com'
    ]))
    ->header('Content-Type', 'application/json')
    ->header('Authorization', 'Bearer {{token}}')
    ->extractFromJson('userId', 'data.id')
    ->validateStatus('create-success', 201);

// PUT request for update
$scenario->step('Update User')
    ->put('https://api.example.com/users/{{userId}}', json_encode([
        'name' => 'John Updated'
    ]))
    ->header('Content-Type', 'application/json')
    ->header('Authorization', 'Bearer {{token}}')
    ->validateStatus('update-success', 200);

// PATCH request for partial update
$scenario->step('Patch User')
    ->patch('https://api.example.com/users/{{userId}}', '{"status": "active"}')
    ->header('Content-Type', 'application/json')
    ->validateStatus('patch-success', 200);

// DELETE request
$scenario->step('Delete User')
    ->delete('https://api.example.com/users/{{userId}}')
    ->header('Authorization', 'Bearer {{token}}')
    ->validateStatus('delete-success', 204);

// HEAD request for checking resource
$scenario->step('Check Resource')
    ->head('https://api.example.com/health')
    ->validateStatus('health-check', 200);

// OPTIONS request for CORS preflight
$scenario->step('Preflight')
    ->options('https://api.example.com/users')
    ->validateStatus('options-success', 200);

$result = $test->run();

```

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

### Configure External Data Sources for Tests in PHP

Source: https://context7.com/volt-test/php-sdk/llms.txt

The DataSourceConfiguration class in the VoltTest PHP SDK allows loading test data from CSV files to parameterize requests. This enables data-driven testing with realistic user data, credentials, or product IDs. It supports sequential, random, and unique data fetching modes, and can interpret CSV headers.

```php
<?php

use VoltTest\VoltTest;
use VoltTest\DataSourceConfiguration;

// Example CSV file (users.csv):
// username,password,email
// john_doe,secret123,john@example.com
// jane_doe,pass456,jane@example.com
// bob_smith,mypass789,bob@example.com

$test = new VoltTest('Data-Driven Test', 'Test with external data');
$test->setVirtualUsers(100)->setDuration('5m');

$scenario = $test->scenario('User Login', 'Login with multiple users');

// Configure data source
$dataSource = new DataSourceConfiguration(
    __DIR__ . '/testdata/users.csv',  // Absolute path to CSV file
    'sequential',                      // Mode options:
                                       //   'sequential' - read rows in order
                                       //   'random' - read rows randomly
                                       //   'unique' - each VU gets unique row
    true                               // true = first row is header
);

$scenario->setDataSourceConfiguration($dataSource);

// Use CSV columns as variables: {{column_name}}
$scenario->step('Login')
    ->post('https://api.example.com/auth/login', json_encode([
        'username' => '{{username}}',
        'password' => '{{password}}'
    ]))
    ->header('Content-Type', 'application/json')
    ->extractFromJson('token', 'data.token')
    ->validateStatus('login-success', 200);

$scenario->step('Get Profile')
    ->get('https://api.example.com/users/me')
    ->header('Authorization', 'Bearer {{token}}')
    ->validateStatus('profile-success', 200);

$result = $test->run();

echo "Success Rate: " . $result->getSuccessRate() . "%\n";

```

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

### Data Extraction

Source: https://context7.com/volt-test/php-sdk/llms.txt

This section explains how to extract dynamic values from HTTP responses using various methods like JSON path, CSS selectors, regex, headers, and cookies, enabling chained API calls.

```APIDOC
## Data Extraction - Capturing Response Values

### Description
Provides methods to capture values from HTTP responses for use in subsequent requests. Supported extraction types include JSON path, HTML selectors, regex patterns, headers, and cookies.

### Extraction Methods
- **JSON Path**: `extractFromJson('variableName', 'json.path')`
- **HTML Selector**: `extractFromHtml('variableName', 'css.selector', 'attribute')`
- **Regex**: `extractFromRegex('variableName', 'regex.pattern')`
- **Header**: `extractFromHeader('variableName', 'header.name.regex')`
- **Cookie**: `extractFromCookie('variableName', 'cookie.name.regex')`

### Request Example (JSON Path Extraction)
```php
// For response: {"data": {"token": "abc123", "user": {"id": 42}}}
$scenario->step('Login')
    ->post('https://api.example.com/login', '{"email": "test@test.com", "password": "secret"}')
    ->header('Content-Type', 'application/json')
    ->extractFromJson('token', 'data.token')           // Extracts "abc123"
    ->extractFromJson('userId', 'data.user.id')        // Extracts 42
    ->validateStatus('login-ok', 200);
```

### Request Example (Using Extracted Values)
```php
// Uses previously extracted 'token' and 'userId'
$scenario->step('GetUserProfile')
    ->get('https://api.example.com/users/{{userId}}')
    ->header('Authorization', 'Bearer {{token}}')
    ->validateStatus('profile-ok', 200);
```

### Response
Extracted values are stored as variables and can be referenced in subsequent requests using double curly braces (e.g., `{{variableName}}`).

### Error Handling
- If extraction fails, the variable will not be set, and subsequent requests using it may fail or behave unexpectedly.
```

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

### Extract Response Data with VoltTest PHP SDK

Source: https://context7.com/volt-test/php-sdk/llms.txt

The VoltTest PHP SDK offers various extractors to capture values from HTTP responses, including JSON path, CSS selectors, regex patterns, headers, and cookies. These extracted values can be used in subsequent requests. Dependencies include the VoltTest class.

```php
<?php

use VoltTest\VoltTest;

$test = new VoltTest('Extraction Test', 'Test data extraction');
$test->setVirtualUsers(5)->setDuration('30s');

$scenario = $test->scenario('API Chain', 'Chained requests with extraction');

// Extract from JSON response using JSON path
// For response: {"data": {"token": "abc123", "user": {"id": 42}}}
$scenario->step('Login')
    ->post('https://api.example.com/login', '{"email": "test@test.com", "password": "secret"}')
    ->header('Content-Type', 'application/json')
    ->extractFromJson('token', 'data.token')           // Extracts "abc123"
    ->extractFromJson('userId', 'data.user.id')        // Extracts 42
    ->validateStatus('login-ok', 200);

// Extract from HTML response using CSS selectors
// For response: <input name="csrf" value="xyz789"/>
$scenario->step('Get Form')
    ->get('https://example.com/form')
    ->extractFromHtml('csrfToken', 'input[name="csrf"]', 'value')  // Extracts "xyz789"
    ->validateStatus('form-ok', 200);

// Extract from response headers
// For header: X-Request-Id: req-12345
$scenario->step('API Call')
    ->get('https://api.example.com/data')
    ->header('Authorization', 'Bearer {{token}}')
    ->extractFromHeader('requestId', 'X-Request-Id: (.+)')  // Regex pattern
    ->validateStatus('data-ok', 200);

// Extract from cookies
// For cookie: session=sess_abc123
$scenario->step('Session')
    ->get('https://example.com/start')
    ->extractFromCookie('sessionId', 'session=(.+)')   // Regex pattern
    ->validateStatus('session-ok', 200);

// Extract using regex pattern from response body
// For response: Order #12345 confirmed
$scenario->step('Order')
    ->post('https://api.example.com/orders', '{"items": [1, 2, 3]}')
    ->header('Content-Type', 'application/json')
    ->header('Authorization', 'Bearer {{token}}')
    ->extractFromRegex('orderId', 'Order #(\d+)')      // Extracts "12345"
    ->validateStatus('order-ok', 201);

// Use extracted values in subsequent requests
$scenario->step('Check Order')
    ->get('https://api.example.com/orders/{{orderId}}')
    ->header('Authorization', 'Bearer {{token}}')
    ->header('X-Session', '{{sessionId}}')
    ->validateStatus('check-ok', 200);

$result = $test->run();

```

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

### Analyze Test Results with TestResult in PHP

Source: https://context7.com/volt-test/php-sdk/llms.txt

The TestResult class in the VoltTest PHP SDK allows for parsing and accessing performance test metrics. It provides methods to retrieve overall test duration, request counts, success rates, throughput, and detailed response time percentiles. The raw output and all metrics can also be accessed for custom processing or export.

```php
<?php

use VoltTest\VoltTest;

$test = new VoltTest('Performance Test', 'Measure API performance');
$test->setVirtualUsers(100)->setDuration('5m')->setRampUp('1m');

$scenario = $test->scenario('Load Test', 'Sustained load');
$scenario->step('API Call')
    ->get('https://api.example.com/endpoint')
    ->validateStatus('success', 200);

// Run test and capture results
$result = $test->run(true);  // true = stream output during test

// Access overall metrics
echo "Test Duration: " . $result->getDuration() . "\n";
echo "Total Requests: " . $result->getTotalRequests() . "\n";
echo "Successful Requests: " . $result->getSuccessRequests() . "\n";
echo "Failed Requests: " . $result->getFailedRequests() . "\n";
echo "Success Rate: " . $result->getSuccessRate() . "%\n";
echo "Requests/Second: " . $result->getRequestsPerSecond() . "\n";

// Access response time metrics
echo "\nResponse Time Metrics:\n";
echo "Min: " . $result->getMinResponseTime() . "\n";
echo "Max: " . $result->getMaxResponseTime() . "\n";
echo "Average: " . $result->getAvgResponseTime() . "\n";
echo "Median: " . $result->getMedianResponseTime() . "\n";
echo "P95: " . $result->getP95ResponseTime() . "\n";
echo "P99: " . $result->getP99ResponseTime() . "\n";

// Get raw output for custom parsing
$rawOutput = $result->getRawOutput();

// Get all metrics as array for JSON export or further processing
$allMetrics = $result->getAllMetrics();
// Returns: [
//   'duration' => '5m',
//   'totalRequests' => 30000,
//   'successRate' => 99.5,
//   'requestsPerSecond' => 100.0,
//   'successRequests' => 29850,
//   'failedRequests' => 150,
//   'responseTime' => ['min' => '15ms', 'max' => '850ms', 'avg' => '45ms', ...]
// ]

// Example: Export results to JSON
file_put_contents('results.json', json_encode($allMetrics, JSON_PRETTY_PRINT));

```
Tokens:
Raw