Download the PHP package volt-test/laravel-performance-testing without Composer

Laravel Performance Testing

A Laravel package for performance testing with the VoltTest PHP SDK. Easily create and run load tests for your Laravel applications with built-in route discovery, CSRF handling, and comprehensive reporting.

This package is built on top of the VoltTest PHP SDK and provides a seamless Laravel integration layer with additional Laravel-specific features like automatic route discovery, CSRF token handling, and Artisan commands.

For more information about the core VoltTest functionality, visit php.volt-test.com.

Table of Contents

• About Laravel Performance Testing VoltTest
• Requirements
• Features
• Installation
• Configuration
• Quick Start
• Creating Tests
• API Testing
• Available Methods
• Running Tests
• Reports
• CSV Data Sources
• PHPUnit Integration
• Advanced Configuration
• Testing Tips
• Troubleshooting
• Learn More

About Laravel Performance Testing VoltTest

This Laravel package extends the VoltTest PHP SDK with Laravel-specific functionality. While the core VoltTest PHP SDK provides the foundation for performance testing, this package adds:

• Laravel Integration - Service provider, facades, and configuration
• Artisan Commands - CLI commands for test creation and execution
• Route Discovery - Automatic Laravel route detection and test generation
• Laravel Scenarios - Enhanced scenario class with Laravel-specific methods

For comprehensive documentation about VoltTest core features, load testing concepts, and advanced configuration options, please visit php.volt-test.com.

Requirements

• PHP 8.2+
• VoltTest PHP SDK 1.1.0+

Features

• Easy Laravel Integration - Seamlessly integrates with Laravel applications
• Automatic Route Discovery - Discover and test your application routes automatically
• Comprehensive Reporting - Detailed performance reports with metrics
• URL Load Testing - Direct URL testing without creating test classes
• Artisan Commands - Convenient CLI commands for test creation and execution
• Configurable - Flexible configuration options for different environments
• PHPUnit Integration - Run performance tests within your PHPUnit test suite with automated server management and assertions
• CSV Data Sources - Load dynamic test data from CSV files for realistic performance testing

Installation

You can install the package via Composer:

The package will automatically register its service provider.

Publish the configuration file:

Configuration

The configuration file config/volttest.php contains all the settings for your performance tests:

Quick Start

1. Create Your First Test

Generate a new performance test with route discovery:

This creates a test class at app/VoltTests/UserTest.php:

2. Run Your Test

Execute the performance test:

Or run all tests:

3. Direct URL Testing

Test any URL directly without creating a test class:

Creating Tests

Using Route Discovery

Generate tests with automatic route discovery:

Manual Test Creation

Create a test class manually:

API Testing

Create API-focused tests:

Available Methods

Scenario Methods

Headers Data

Assertions

Extracting Data

Running Tests

Command Syntax

Arguments

• test (optional) - The test class to run OR URL to test

Available Options

Basic Execution

Duration Formats

The --duration option accepts various time formats:

• 30s - 30 seconds
• 5m - 5 minutes
• 2h - 2 hours
• 90s - 90 seconds (1.5 minutes)

Header Formats

The --headers option accepts JSON format:

Body Formats

The --body option supports different formats depending on content type:

Advanced Options

Reports

Console Output

Test results are displayed in the console with metrics including:

• Duration and total requests
• Success rate and requests per second
• Response time statistics (min, max, avg, median, P95, P99)

Saved Reports

Reports are automatically saved as JSON files in storage/volttest/reports/:

CSV Data Sources

Load dynamic test data from CSV files for more realistic and scalable performance testing scenarios.

Quick Example

1. Create a CSV file at storage/volttest/data/users.csv:

2. Use the data in your test:

Distribution Modes

• unique: Each virtual user gets a different CSV row (recommended for user authentication)
• random: Each virtual user gets a random CSV row (good for product browsing)
• sequential: Virtual users cycle through CSV rows in order (predictable patterns)

📖 Complete CSV Documentation

For detailed information including:

• File format requirements and validation
• All distribution modes with use cases
• Configuration options and file paths
• Troubleshooting and performance tips
• Advanced patterns and best practices

Read the complete CSV Data Source guide →

PHPUnit Integration

Run VoltTest performance tests within your PHPUnit test suite with automated server management and comprehensive performance assertions.

Configuration

To enable console reporting of performance metrics, you must register the VoltTest extension in your phpunit.xml file:

Quick Example

Key Features

• PerformanceTestCase - Base test class for PHPUnit integration
• Automatic Server Management - Built-in PHP development server lifecycle management
• Performance Assertions - Specialized assertions for response times, success rates, and throughput
• Quick Helpers - Simple methods for common load testing scenarios

Available Assertions

Quick Load Testing Helpers

Reusing Existing VoltTest Classes

You can reuse your existing VoltTest classes in PHPUnit tests for maximum code reuse:

VoltTest Class (app/VoltTests/RegistrationTest.php):

PHPUnit Test (tests/Performance/RegistrationPerformanceTest.php):

Benefits: Define scenarios once, run via Artisan (php artisan volttest:run RegistrationTest) or PHPUnit with assertions.

Running PHPUnit Tests

📖 Complete PHPUnit Documentation

For detailed information including:

• Server management configuration
• All available assertions with examples
• Advanced test patterns and best practices
• Troubleshooting common issues
• Complete working examples

Read the complete PHPUnit Integration guide →

Testing Tips

Best Practices

1. Start Small: Begin with a few virtual users and gradually increase
2. Watch Server Resources: Monitor CPU, memory, and database connections
3. Use Realistic Data: Incorporate CSV data sources for authentic testing
4. Extract and Reuse: Extract tokens and IDs for multi-step scenarios
5. Separate Concerns: Create multiple test classes for different features
6. Include Think Time: Add realistic pauses between user actions
7. Test API and UI: Cover both API endpoints and web interfaces

Optimizing Tests

1. Increase Virtual Users Gradually: Start with 10-20 users and double until performance degrades
2. Add Ramp-up Time: Allow virtual users to start gradually with --ramp-up=30s
3. Use CSV Data Sources: Avoid hard-coding test data by using CSV files
4. Cache CSRF Tokens: Extract tokens once and reuse where possible
5. Focus on Critical Paths: Test your most important user journeys first

Troubleshooting

Common Issues

Connection Errors

• Ensure your application is running and accessible at the configured base_url
• Check firewall settings and network connectivity
• Try running with --debug to see detailed error information

Authentication Failures

• Verify that credentials in your tests are valid
• Check session and cookie handling in your application
• Ensure proper headers are being sent (e.g., Authorization)

CSRF Token Issues

• Make sure your application is generating CSRF tokens
• Check the CSS selector used in extractCsrfToken() matches your form
• Try extracting the token manually with extractHtml('token', 'meta[name="csrf-token"]', 'content')

Content Type Problems

• If JSON or HTML responses aren't parsing correctly, check the content type headers
• Use the header('Content-Type', 'application/json') or header('Accept', 'application/json') methods
• For POST/PUT/PATCH requests with array data, adding a Content-Type: application/json header will automatically convert the array to JSON
• When a response can't be properly parsed, you can use the extractRegex() method as a fallback to extract data using regular expressions

Incorrect Parsing of Response Data

• If extractJson() fails, check if the response is valid JSON using the debug option
• For nested or complex JSON structures, use dot notation to access nested properties
• When HTML doesn't contain the expected selectors, use extractRegex() as an alternative
• If you're unsure about the response format, run with --debug and examine the actual response

Rate Limiting

• If your API enforces rate limiting, reduce the number of virtual users or increase the think time
• Consider adding delays between requests with thinkTime() method

Debug Commands

Learn More

For more information about VoltTest and performance testing with Laravel, check out:

• VoltTest PHP SDK Documentation
• PHPUnit Integration Guide
• CSV Data Sources Guide

If you have questions, suggestions, or need help, please open an issue on our GitHub repository.

License

This Laravel package is open-sourced software licensed under the MIT license.

Changelog

Please see CHANGELOG for more information on what has changed recently.