Load Testing

Overview

The load-testing suite uses Gherkin for creating human-readable test scenarios that validate network behavior under load. Tests are located in the load-testing/ directory and use YAML manifests to define network configurations.

⚡ Quick Start

Get started with the default LocalNet single supplier configuration.

1

Ensure LocalNet is running

Start LocalNet as described in the LocalNet docs: https://dev.poktroll.com/develop/networks/localnet

2

Run the default load test

Run default single supplier load test

make test_load_relays_stress_localnet_single_supplier

🧪 Test Types

🎯 Default Load Test (Single Supplier)

Recommended starting point.

Configuration:

• Initial: 4 applications, 1 gateway, 1 supplier

• Scaling: Adds 4 applications every 10 blocks up to 12 total

• Rate: 1 relay request per second per application

Command:

Default single supplier

make test_load_relays_stress_localnet_single_supplier

🌐 Multi-Supplier Load Test

Tests the network with multiple suppliers and gateways scaling together.

Configuration:

• Initial: 4 applications, 1 gateway, 1 supplier

• Scaling: All actors scale together up to 3 suppliers and 3 gateways

• Rate: 1 relay request per second per application

Command:

Multi-supplier

make test_load_relays_stress_localnet

🔄 Claim Settlement Stability Test

Maintains a high constant load to validate network stability during claim settlement periods.

What this test validates:

• Session lifetime caching optimization that prevents relay serving freezes by:

  • Clearing cache only at the end of each session (instead of every block)

  • Reducing requests to full nodes during busy claim-settlement blocks

• Ensures no relay failures or timeouts during critical claim settlement periods

Configuration:

• Constant load: 50 applications, 50 gateways, 50 suppliers (no scaling)

• Rate: 2 relay requests per second per application

• Focus: Ensure no timeouts and stable relay success rates during claim settlement

Key validation points:

• No timeout spikes during claim settlement blocks

• Consistent relay success rates despite full node unresponsiveness

This test uses significantly more resources than other tests due to the high number of concurrent actors and relay rate.

📋 Test Manifests

Load test manifests are YAML files that define network configurations for different testing scenarios.

Available manifest files:

• loadtest_manifest_localnet_single_supplier.yaml - Default single supplier configuration

• loadtest_manifest_localnet.yaml - Multi-supplier configuration

• loadtest_manifest_example.yaml - Template for custom networks

🏃 Running Tests

⚠️ Prerequisites

Before running load tests, ensure your environment is properly configured:

• LocalNet must be running

• Run make acc_initialize_pubkeys to initialize blockchain public keys

🔧 LocalNet Setup

Proper LocalNet configuration is essential for successful load testing.

1

Configure localnet_config.yaml

Set:

• gateways.count and relayminers.count to match your test requirements

• For single supplier tests: relayminers.count = 1

• For multi-supplier tests: relayminers.count = 3

2

Start LocalNet and run tests

Start LocalNet and then run the make commands shown in the Test Types / Quick Start sections.

🌍 Custom Network Testing

You can run load tests against external networks (testnets or custom deployments) by modifying the test manifest.

Steps:

1. Copy loadtest_manifest_example.yaml and modify it for your network

2. Update account addresses, RPC endpoints, and actor configurations

3. Run with a custom manifest:

Run with custom manifest

LOAD_TEST_CUSTOM_MANIFEST=your_manifest.yaml make test_load_relays_stress_custom

📊 Monitoring Results

🖥️ Test Output

Load tests provide detailed output about test execution and results.

Result interpretation:

• PASS indicates successful test completion

• FAIL shows failures with error details

• Monitor relay success/failure rates in the output

📈 Grafana Dashboards (LocalNet)

LocalNet provides observability through Grafana dashboards for real-time monitoring during load tests.

Access observability at: http://localhost:3003

• Stress Test Dashboard: http://localhost:3003/d/ddkakqetrti4gb/protocol-stress-test?orgId=1&refresh=5s

• Load Testing Dashboard: http://localhost:3003/d/fdjwb9u9t9ts0e/protocol-load-testing?orgId=1

📝 Test Features Example

Load tests are written using Gherkin syntax. Example:

feature: load testing (Gherkin)

Feature: Loading gateway server with relays

  Scenario: Incrementing the number of relays and actors
    Given localnet is running
    And a rate of "1" relay requests per second is sent per application
    And the following initial actors are staked:
      | actor       | count |
      | application | 4     |
      | gateway     | 1     |
      | supplier    | 1     |
    And more actors are staked as follows:
      | actor       | actor inc amount | blocks per inc | max actors |
      | application | 4                | 10             | 12         |
      | gateway     | 1                | 10             | 1          |
      | supplier    | 1                | 10             | 1          |
    When a load of concurrent relay requests are sent from the applications
    Then the number of failed relay requests is "0"

🎯 Available Commands

Command	Purpose
make test_load_relays_stress_localnet_single_supplier	Default single supplier load test
make test_load_relays_stress_localnet	Multi-supplier load test
make test_load_relays_stress_custom	Custom manifest load test