Cloud Execution

Run Laravel performance tests on VoltTest Cloud instead of your local machine.

Setup

Add your API key to .env:

VOLTTEST_API_KEY=vt_your_api_key

Three Ways to Enable Cloud Mode

1. CLI Flag

php artisan volttest:run LoginTest --cloud

2. Config File

In .env:

VOLTTEST_CLOUD_ENABLED=true

Or in config/volttest.php:

'cloud' => [
    'enabled' => true,
    'api_key' => env('VOLTTEST_API_KEY'),
],

3. Facade / Programmatic

use VoltTest\Laravel\Facades\VoltTest;

VoltTest::target('https://api.example.com');
VoltTest::cloud();
$result = VoltTest::run();

Staged Load via CLI

php artisan volttest:run LoginTest --cloud --stage=1m:50 --stage=5m:100 --stage=1m:0

Format: --stage=duration:target (repeatable).

Region Distribution

Via CLI

php artisan volttest:run LoginTest --cloud --region=us-east-1:60 --region=eu-west-1:40

Format: --region=region_code:weight (repeatable, weights must sum to 100).

Via Config

In config/volttest.php:

'regions' => [
    'us-east-1' => 60,
    'eu-west-1' => 40,
],

Via Code

use VoltTest\Laravel\Facades\VoltTest;

VoltTest::target('https://api.example.com');
VoltTest::cloud();
VoltTest::regions([
    'us-east-1' => 60,
    'eu-west-1' => 40,
]);
$result = VoltTest::run();

Available Regions

North America

Code	Location
us-east-1	US East (N. Virginia)
us-east-2	US East (Ohio)
us-west-1	US West (N. California)
us-west-2	US West (Oregon)
ca-central-1	Canada (Central)

South America

Code	Location
sa-east-1	South America (São Paulo)

Europe

Code	Location
eu-west-1	Europe (Ireland)
eu-west-2	Europe (London)
eu-west-3	Europe (Paris)
eu-central-1	Europe (Frankfurt)
eu-north-1	Europe (Stockholm)

Asia Pacific

Code	Location
ap-southeast-1	Asia Pacific (Singapore)
ap-southeast-2	Asia Pacific (Sydney)
ap-southeast-3	Asia Pacific (Jakarta)
ap-southeast-4	Asia Pacific (Melbourne)
ap-southeast-5	Asia Pacific (Malaysia)
ap-south-1	Asia Pacific (Mumbai)
ap-south-2	Asia Pacific (Hyderabad)
ap-northeast-1	Asia Pacific (Tokyo)
ap-northeast-2	Asia Pacific (Seoul)
ap-northeast-3	Asia Pacific (Osaka)
ap-east-1	Asia Pacific (Hong Kong)
ap-east-2	Asia Pacific (Taipei)

Africa

Code	Location
af-south-1	Africa (Cape Town)

info

Region availability may change. If a region is temporarily unavailable, the API will return an error with details.

CloudRun Result

In cloud mode, run() returns a CloudRun object:

VoltTest::cloud()->run();

The run ID, dashboard URL, and status are printed automatically. run() also returns a CloudRun object for programmatic access (useful in CI/CD).

Conflict Handling

When a test with the same name already exists, VoltTest prompts interactively (in a terminal) or defaults to updating the most recent test (in non-interactive environments like CI).

For custom logic:

VoltTest::setOnConflictPrompt(function (array $existingTests) {
    return $existingTests[0]['id']; // Update most recent
});

PHPUnit + Cloud

class CloudPerformanceTest extends PerformanceTestCase
{
    public function test_cloud_checkout(): void
    {
        $result = $this->runVoltTest(new CheckoutTest(), [
            'virtual_users' => 500,
            'duration' => '10m',
        ]);

        // CloudRun returned — check dashboard for detailed metrics
        $this->assertTrue($result->isSuccessful());
    }
}

info

When running in cloud mode, assertVT* response time assertions are not available since CloudRun doesn't contain local metrics. Use the dashboard for detailed analysis.

Error Handling

Cloud-specific exceptions are thrown when issues occur. See the Cloud Mode page for the full exception reference.

use VoltTest\Exceptions\AuthenticationException;
use VoltTest\Exceptions\PlanLimitException;

try {
    $result = VoltTest::cloud()->run();
} catch (AuthenticationException $e) {
    // Invalid API key
} catch (PlanLimitException $e) {
    // VU or duration exceeds plan
}