How to Run Performance Tests with HyperExecute

HyperExecute supports portal workflows for JMeter and Gatling, and CLI/YAML workflows for repeatable execution from a terminal or CI pipeline. For a one-off test, upload the project through the portal. For pipeline-triggered runs, prepare the project and configuration for the HyperExecute CLI, then inspect the job logs and uploaded reports.

The key planning detail is the load model: a thread or user count in a test plan may be applied on each machine or region. Work out the aggregate load and verify the distribution before starting a test.

1. Choose the execution route

Route	Use it when	What you configure
Portal	You want to upload and launch a JMeter or Gatling test without setting up a YAML job.	Project and test file, workload type, users or arrival rate, duration, ramp-up where applicable, regions, machines, and test data.
CLI with YAML	You need a terminal-driven run or a pipeline trigger that can be repeated with a checked-in configuration.	CLI version, credentials, project files, runner and test command, configuration, and report artifacts.

You do not need YAML for the documented JMeter and Gatling portal flows. The CLI route is for teams that want execution driven from a terminal or pipeline. HyperExecute documentation also categorizes k6 as a performance-testing framework, but that does not mean it has the same portal upload flow as JMeter and Gatling.

2. Run a JMeter test in the portal

1. Prepare and save your test plan as a .jmx file in JMeter. Make sure its data files and any external dependencies are available to the project.
2. Open the HyperExecute Projects dashboard and create a project.
3. Upload the JMeter plan, then select it in the project.
4. Configure the load: users, test duration, ramp-up, distribution across regions, machine count, and CSV splitting if the plan uses CSV data.
5. Check the selected regions and their percentages. The vendor guide describes East US as a default region; verify the current setting rather than assuming it matches your target users.
6. Review whether user counts are per machine or aggregate for the configured distribution. Set any distribution overrides needed to reach your intended total.
7. Choose Run Test. When the job finishes, inspect its status, logs, reports, and artifacts.

Plan the aggregate load before launch

Do not assume the JMeter thread count is the total across the whole job. The vendor guide gives this example: a 250-user plan replicated on three machines across two regions can produce 1,500 concurrent users (250 × 3 × 2) without load-distribution overrides. Verify the effective per-generator and aggregate counts in the current configuration.

Ramp-up controls how quickly the configured users start. Duration controls how long the run continues. Region percentages and machine count determine where and how widely the load is generated. CSV splitting matters when each generator must receive a distinct subset of test data; check that the split and row counts fit the plan’s data needs.

3. Run a Gatling test in the portal

1. Create a project in HyperExecute and choose Gatling.
2. Upload the simulation files required by the current vendor guide. Include the project structure and dependencies the simulation expects.
3. Select the simulation and choose a test type: Capacity, Stress, or Soak.
4. Configure the workload and distribution for that mode, including duration and the relevant user-arrival or injected-user values.
5. Check the region and machine configuration, then launch the run.
6. After completion, review job status, logs, Gatling reports, and uploaded artifacts.

Mode	Workload described by the guide	Question it helps answer
Capacity	Duration plus initial and final user-arrival rates.	How does the system scale as arrival rate increases, and where are its limits?
Stress	Duration plus total injected users.	How does the system behave under peaks, and how does it recover?
Soak	Duration plus a constant arrival rate.	Does sustained load expose memory leaks or performance degradation?

Choose the mode based on the question you need to answer. A short peak test does not establish sustained-load behavior, and a steady soak does not by itself identify the system’s breaking point.

4. Set up a repeatable CLI/YAML run

CLI details, supported features, and YAML schema can change. Use the current HyperExecute guide and a compatible CLI version for the exact command and configuration keys. The sequence below shows what to prepare without assuming a particular schema.

1. Prepare the project. Keep the test source, dependencies, required data, and report output locations together. For Gatling, identify the simulation and the Maven project setup.
2. Check the current CLI and schema. Install or select the HyperExecute CLI version supported by the account and guide you are following. Confirm the YAML format for that version before committing it to a pipeline.
3. Provide credentials securely. Set the account credentials using the environment-variable names required by the current vendor instructions. Store secrets in your CI secret manager; do not put access keys in the YAML file or source control.
4. Configure the runner. In hyperexecute.yaml, follow the current guide to specify the runner, project setup, test command, and artifacts. For the documented Gatling example, the guide covers Maven dependency resolution, mvn gatling:test, and report artifact upload.
5. Validate locally where supported. Check that the project builds and the test command can find its simulation and data before submitting a distributed job.
6. Invoke the CLI. Use the run command and flags documented for the installed CLI version, pointing it to the prepared YAML configuration. Do not copy a command from a different CLI release without checking its help output and current documentation.
7. Wire it into the pipeline. Trigger the same versioned configuration from the desired branch, schedule, or pipeline stage. Keep workload size and target environment explicit so a routine build does not accidentally launch a large load test.
8. Review the job. Check status and logs in HyperExecute, then retrieve the uploaded report artifacts and inspect the performance data produced by JMeter or Gatling.

# Example Gatling test command documented in the vendor guide
mvn gatling:test

The command above is the test invocation, not a complete HyperExecute CLI submission command. Use the current vendor guide for the CLI invocation, YAML keys, credential variable names, and artifact syntax for your CLI version.

5. Interpret results and verify the run

1. Confirm the job completed successfully; distinguish a failed test process from a test that completed and reported poor application performance.
2. Read the job logs for setup, dependency, data-file, and test-run errors.
3. Open the framework report or downloaded artifact. Check that it covers the expected duration and workload.
4. Compare the observed load with the intended aggregate users or arrival rate. Confirm whether distribution was replicated per machine and region.
5. Review latency, throughput, and error behavior in the framework output against your own service objectives. A configured user count alone does not establish achieved throughput.

6. Load planning, reliability, and cost considerations

Validate load distribution

Machine count and regions can multiply a plan’s load if the plan is replicated. The vendor’s 250-user example reaches 1,500 concurrent users with three machines and two regions. Use distribution overrides where appropriate, then verify the resulting per-generator and aggregate values in the current job configuration and results.

Treat capacity guidance as conditional

The vendor guide describes 2,000 users as a ceiling under favorable conditions, not a universal guarantee or independent benchmark. Its guidance depends on factors such as lightweight requests, suitable timeouts, and enough machines and regions. Your application, test design, network behavior, and generator setup affect what a run can sustain.

Make runs repeatable and useful

• Keep the test plan, data assumptions, workload mode, and configuration under version control.
• Use a fixed and documented target environment when comparing runs.
• Separate warm-up behavior from the measurement period where the framework and test design call for it.
• Check request timeouts and test data before scaling up; a generator-side bottleneck or invalid data can make results misleading.
• Start with a workload that can answer the test question, then increase it deliberately. Confirm the aggregate load before each larger run.
• Retain job logs and report artifacts needed to compare runs. The vendor guide documents accessing report artifacts through the HyperExecute logs UI.

Budget for the workload

The supplied documentation does not establish a price or billing model for a particular HyperExecute run. Check the current account plan and job-cost details before scheduling sustained or high-load tests. Keep pipeline triggers scoped so routine commits do not unintentionally launch lengthy or large workloads.

7. Troubleshooting

Symptom	Likely cause	What to check or fix
CLI rejects the YAML file	The configuration uses keys or structure from a different CLI/schema version.	Check the installed CLI version and validate against the matching current guide. Do not assume an old example remains valid.
Authentication fails	Credentials are missing, expired, or set under the wrong environment-variable names.	Follow the current credential setup instructions and CI secret settings. Avoid putting credentials in the YAML or logs.
Gatling cannot find or run the simulation	The project structure, simulation selection, or Maven dependencies do not match the expected setup.	Review the uploaded simulation files and Maven dependency-resolution steps in the current Gatling guide; confirm the documented mvn gatling:test invocation works for the project.
JMeter reports missing data or behaves differently on generators	CSV data was not included, paths differ, or data splitting does not match the plan.	Include the required files, verify their paths, and configure CSV splitting for the intended per-generator data behavior.
Observed user total is higher than expected	Thread counts may be replicated for each machine and region.	Calculate per-generator count × machines × regions, inspect distribution overrides, and confirm the effective aggregate load before rerunning.
Run does not reach the planned rate	Ramp-up, arrival-rate settings, timeouts, machine capacity, or test design may constrain achieved load.	Check the mode-specific configuration and logs. Confirm the generator and request setup can sustain the target; do not treat configured users as proof of achieved throughput.
Report is missing	Artifact upload or report output configuration is absent or points to the wrong location.	Check the test’s report output and the current YAML artifact instructions, then inspect the job logs UI for uploaded artifacts.
Job uses an unexpected region or times out	A default region or a version-sensitive timeout setting may differ from expectations.	Verify the current regional configuration and timeout behavior in the portal and current guide before launch.

8. Or skip the browser setup

If your next step is capturing a page during QA or a test workflow, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns an image or PDF; this is a separate page-capture task from running a JMeter or Gatling load test.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for request options. Cookie banners are accepted and removed before capture, along with known newsletter popups and chat widgets. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.

Learn about ScreenshotNeo, then sign up free for 1,000 screenshots a month with no card.

FAQ

Can I use HyperExecute for k6?

The documentation category includes k6, and the FAQ describes a CLI/YAML guide for it. The supplied research does not establish a JMeter- or Gatling-style portal upload workflow for k6, so check the current k6 guide for its supported route.

Should I use Capacity, Stress, or Soak for a release check?

Choose based on the risk you need to understand: scaling limits, peak and recovery behavior, or sustained-load degradation. A single mode does not answer all three questions.

Does a 2,000-user run guarantee my service can handle 2,000 users?

No. The vendor presents that figure as conditional guidance under favorable conditions, not a guaranteed capacity or independent benchmark. Workload shape, generator setup, regions, timeouts, and the application all matter.

Can I reuse the same configuration for every CLI version?

Do not assume so. CLI commands, supported options, and YAML schema are version-sensitive; check the guide matching the binary used in your pipeline.