Simulations
Navigate through simulations.
Managing Simulations
To access the Simulations section, click on Simulations in the navigation bar.
The Simulations view contains all the simulations configured by your organization and the results of their last run.
If you don’t have any simulations configured yet and don’t know where to start, follow the helper that guides you through the creation process:
- Build your simulation in-app: leads you to the in-app simulation builder
- Build a test as code project: leads you to the Get-started guide explaining how you can build a package from sources, upload it, and execute it using Gatling Enterprise
Getting started guide
Depending on which programming language you are using, follow the steps to create your first package. Once this is done, you’re ready to upload it and create you first test-as-code simulation.
If you need to find this guide later on, you can navigate to it using our simulation creation modal
Creating a test-as-code simulation
Use the Create a simulation button (either coming from the Simulations page or the Getting started guide) to open the simulation creation modal:
From here, you can either import a package, select an existing one, or go to the in-app simulation builder.
Once you’ve selected your package, click the Create button to configure your simulation
Step 1: name, package and simulation
In this step, define the simulation’s general parameters.
- Name: the name that will appear on the simulations table.
- Package: the actual package the simulation will run.
- Simulation: the simulation to run in this package.
Step 2: Locations configuration
In this step, configure the Gatling Enterprise load generator locations.
You can either use the managed locations provided by Gatling Enterprise, use your own private locations, or dedicated IP addresses for your load generators.
Managed location load generators have the following specifications:
- 4 cores
- 8GB of RAM
- bandwidth up to 10 Gbit/s
Gatling Enterprise managed locations are available in the following regions:
- AP Pacific (Hong kong)
- AP Pacific (Tokyo)
- AP Pacific (Mumbai)
- AP SouthEast (Sydney)
- Europe (Dublin)
- Europe (Paris)
- SA East (São Paulo)
- US East (N. Virginia)
- US West (N. California)
- US West (Oregon)
If you want to use private locations, please refer to the specific documentation.
To get the best results from your simulation you should select the load generator locations that best match your user base.
- Location: defines the locations to be used when initiating the Gatling Enterprise load generators.
- Number of load generators: number of load generators for this location.
- Weight distribution: by default, every load generator will produce the same load. If enabled, you must set the weight in % for each location (e.g. the first location does 20% of the requests, and the second does 80%). The sum of all weights must be 100%.
You can add several locations with different numbers of load generators to run your simulation.
After this step, you can save the simulation, or continue with optional configurations.
Step 3: Load Generator Parameters Optional
This step allows you to define the Java system properties or JS parameters and environment variables used when running this particular simulation. Properties/variables entered here will add to the defaults, unless you choose to ignore the defaults. If you keep the defaults, and you add a property/variable with the same key as one from the defaults, the simulation’s value will be used (it overrides the default). See the Default Load Generator Parameters section for more information.
sensitive., and environment variables if you prefix them with SENSITIVE_.You can configure the gatling.enterprise.groupedDomains Java System property to group connection stats from multiple subdomains and avoid memory issues when hitting a very large number of subdomains.
For example, setting this property as .foo.com, .bar.com will consolidate stats for sub1.foo.com, sub2.foo.com, sub1.bar.com, sub2.bar.com into *****.foo.com and *****.bar.com.
System properties can be retrieved in your Gatling simulation with System.getProperty("YOUR_PROPERTY_KEY").
Environment variables can be retrieved in your Gatling simulation with System.getEnv("YOUR_ENV_VAR_KEY").
Step 4: Time window Optional
You can configure ramp-up and ramp-down time windows to be excluded from computed assertions. This is typically useful when you know that at the beginning of your test run you expect higher response times than when your system is warm (JIT compiler has kicked in, autoscaling has done its work, caches are filled, etc.) and don’t want them the warm-up time to cause your assertions to fail.
- Ramp Up: the number of seconds you want to exclude at the beginning of the run.
- Ramp Down: the number of seconds you want to exclude at the end of the run.
Step 5: Stop Criteria Optional
In this step, you can configure specific stop criteria to end the run earlier if certain thresholds are exceeded. This is particularly useful for terminating test runs once key performance metrics exceed acceptable limits.
Each stop criterion must include:
- Metric: The metric over which the metric is evaluated. (Mean CPU, Global Error Ratio or Global Response Time)
- Threshold: The value that, when reached or exceeded, will trigger the stop condition. (eg: over 30% / 300ms on 99.9 percentile)
- Timeframe (in seconds): The period during which the metric must exceed the threshold for the entire duration to trigger the stop. (eg: last 60 seconds)
You can base stop criteria on the following metrics:
- Mean CPU Usage: The average CPU usage of the load generators, measured as a percentage.
- Global Error Ratio: The percentage of failed requests across all test scenarios.
- Global Response Time: The response time of all requests, measured at a specific percentile, in milliseconds.
Simulation execution
Using the simulations table, you can control your simulation execution.
Start or stop your run using the respective or buttons.
Lifecycle
Once you have created and started a simulation, your run will go through the following life cycle:
- Building: download the simulation package and prepare the hosts.
- Deploying: deploy the simulation to the load generators.
- Injecting: the simulation is active and can be viewed in Reports.
Logs
By clicking on the Last run column of your simulation, you are redirected to the build logs for your run. There is a limit of 1,000 logs for a run.
Viewing the Logs can also help determine why a run failed and what errors you need to correct to successfully run your simulation.
Useful tips
- You can edit, copy the ID, duplicate and delete the simulation by clicking on the kebab menu icon
- You can search a simulation by its name, or its team name
- You can sort the simulations by any column
- A Delete button will appear on the action bar when you select a simulation, you will be able to delete all the selected simulations
- You can edit default load generator parameters using the corresponding button at the top of the page
Be aware that deleting a simulation will delete all the associated runs.
Default load generator parameters
Default load generator parameters contain every Java system property or JS parameter and environment variable used in your simulations by default. Editing these properties propagates to all simulations. You can access the form by clicking the button in the top right corner of the simulation page.
If you want specific properties for a simulation, you can ignore the default properties by unchecking the Default properties box when creating or editing the simulation:
