How To Run NeoLoad Test Run Using Command Line

Running NeoLoad performance tests through the command line interface is essential for automating test execution within continuous integration pipelines, saving valuable engineering time, and scaling enterprise load testing strategies. By utilizing the NeoLoad Controller and Load Generator command-line tools, performance engineers can bypass the graphical user interface to execute, monitor, and report on complex test scenarios headlessly.

Essential Prerequisites and System Preparation

Executing a NeoLoad test run via the command line requires a solid infrastructure foundation, correct licensing, and precise path configurations on your operating system. Without properly establishing these environmental boundaries, automated test scripts will fail during initialization, halting your continuous delivery pipelines.

To ensure a seamless command-line execution experience, review the following operational checklist before initiating any automated scripts:

• Essential Tools and Software: NeoLoad Controller and Load Generator installed, valid enterprise or community license applied, NeoLoad project file saved locally (.nlp), and the NeoLoad command-line utility (NeoloadCmd) added to your system environment PATH variables.
• Prerequisite Knowledge: Familiarity with basic command-line interface navigation, continuous integration tools such as Jenkins or GitLab CI, XML configuration parsing, and load testing performance metrics including throughput, response time, and error rates.
• Environment Benchmarks: Dedicated execution hardware with a minimum of 8GB RAM and a multi-core processor for the Controller, network ports open for communication (typically port 7100), and test duration scoped for the targeted performance SLA windows.

Step-by-Step NeoLoad Command-Line Execution Workflow

Step 1: Locate and Verify the NeoLoad Command-Line Executable

Navigate to your NeoLoad installation directory using your terminal or command prompt to locate the primary execution binary named NeoloadCmd. On Windows systems, this executable typically resides in the Program Files folder under the NeoLoad installation path, whereas Linux installations place it within the designated opt or bin directories. Verify that the system recognizes the command by typing the executable name followed by the version flag to output the installed build details.

Pro-Tip: Always add the NeoLoad installation directory containing the executable to your operating system's permanent environment variables to allow test execution from any working directory without typing absolute file paths.

Step 2: Construct the Basic Execution Syntax

Build your command-line string by combining the base executable command with mandatory operational arguments, including the path to your project file and the specific scenario name you wish to execute. The basic syntax requires the project flag pointing to your .nlp file and the scenario flag specifying which predefined user load model to trigger. Ensure all directory paths containing spaces are enclosed in quotation marks to prevent syntax parsing errors from the command interpreter.

Warning: Running a test with an incorrect scenario name will cause the command-line utility to abort immediately with an error code, so always verify your scenario names directly inside the NeoLoad GUI project settings prior to automation.

Step 3: Configure Advanced Parameters for Remote Load Generators

Incorporate remote load generator definitions, variable overrides, and monitoring configuration flags into your command line if your test requires distributed infrastructure. Use specific parameter flags to point the Controller to dedicated Load Generator machines, ensuring that all remote engines are pre-configured, reachable via network ping, and running the exact same version of the NeoLoad software. This step guarantees that your high-volume distributed user load is generated accurately across all designated cloud or on-premise nodes.

Step 4: Automate Report Generation Post-Execution

Append reporting parameters to your command-line string to automatically export test results in structured formats such as PDF, XML, or JSON immediately upon test completion. Specifying an output directory and report template via the command line allows post-processing tools, dashboards, and automated email notification systems to parse performance metrics without human intervention. Verify that the destination folder has write permissions enabled for the user running the command-line process.

Command-Line Parameter Reference Matrix

Troubleshooting Common Command-Line Execution Failures

• Root Cause: The command-line utility returns an error stating that the NeoLoad project file cannot be found or parsed.
  
  
  • Actionable Fix: Verify that the file path provided to the project parameter uses the correct directory slash orientation for your operating system and enclose the entire path string in quotation marks if spaces exist in folder names.
• Root Cause: The test execution halts immediately because the designated scenario name does not exist in the project file.
  
  
  • Actionable Fix: Open the NeoLoad GUI, navigate to the Scenarios panel, and confirm the exact spelling, capitalization, and character structure of the target scenario before updating your automation script.
• Root Cause: Remote load generators fail to connect or initialize during the command-line startup phase.
  
  
  • Actionable Fix: Check that the load generator service is running on the remote machines, verify network firewall rules on port 7100, and ensure version parity between the Controller and all Load Generators.
• Root Cause: The command-line script exits with a license validation error despite having a valid active license.
  
  
  • Actionable Fix: Ensure that the user account executing the command-line utility has read permissions to the NeoLoad license repository and that the license has not expired or reached concurrent session limits.

Frequently Asked Questions

Can I run a NeoLoad test from the command line without installing the full GUI?

Yes, you can install a headless version of NeoLoad containing only the Controller and Load Generator components, which is ideal for lightweight build agents and Docker container environments. This approach minimizes resource consumption on remote execution nodes while maintaining full testing fidelity.

How do I pass external dynamic variables into a command-line test run?

You can inject external parameters by utilizing property files or command-line argument flags that override default variable values defined within your NeoLoad project. This capability allows you to dynamically change user counts, ramp-up durations, and target server URLs directly from your continuous integration pipeline configuration.

What exit codes does the NeoLoad command-line utility return upon completion?

The utility returns standard integer exit codes where zero typically indicates a successful test run with no SLA failures, while non-zero codes signify configuration errors, licensing issues, or performance SLA breaches. You can program your CI/CD pipeline to parse these exit codes to automatically pass or fail a software build stage.

Is it possible to stop a running command-line performance test prematurely?

You can safely abort an active command-line test by sending an interrupt signal to the process, such as pressing Ctrl+C in the terminal or issuing a remote kill command from your CI/CD orchestration server. NeoLoad will automatically aggregate the partial results collected up to that point and save them to the designated results directory.

Master Your Performance Testing Workflow Today

Integrating NeoLoad command-line executions into your automated deployment pipelines eliminates manual bottlenecks and guarantees consistent performance validation across every software release cycle. Elevate your engineering capabilities by standardizing your headless test scripts and automated reporting frameworks today.