How To Run NeoLoad Test Run Using Command Line

Executing NeoLoad tests via the command line interface automates performance validation by bypassing the graphical user interface, allowing seamless integration into continuous integration pipelines. By leveraging the NeoLoad Controller and command-line runner executable, performance engineers can programmatically pass project paths, specify load generators, and generate standardized reporting artifacts.

Prerequisites and Environment Configuration for CLI Execution

Transitioning from the graphical user interface of NeoLoad to headless command-line execution requires specific architectural readiness. The host machine or build agent must house the NeoLoad Controller and Load Generator software binaries. Furthermore, licensing considerations dictate whether the command-line interface communicates with a standalone controller, a floating license manager, or a cloud-based reservation platform. Performance teams must ensure network accessibility across ports used by the controller and load generators, typically utilizing port 7100 by default.

• Essential Software and Tools: NeoLoad Controller installation, command-line runner executable (NeoloadCmd), valid enterprise or lease license key, and compiled NeoLoad project archive.
• Mandatory Prerequisite Knowledge: Familiarity with basic shell scripting, environment variable configuration, absolute file path structures, and XML or JSON result formatting standards.
• Operational Benchmarks: Execution setup time typically requires 15 to 30 minutes, with target test durations varying based on system under test capacity and script complexity.

Step-by-Step Guide to Executing NeoLoad Tests via Command Line

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

Navigate to the installation directory of NeoLoad on your operating system to locate the command-line utility binary. On Windows systems, this executable typically resides in the application program files directory under the NeoLoad bin folder as NeoloadCmd.exe, while Linux installations place the binary in the designatedopt or bin paths. Verify the installation integrity by opening your terminal or command prompt, invoking the executable with the version flag, and confirming that the system recognizes the path environment variables.

Pro-Tip: Add the NeoLoad bin directory to your operating system system path environmental variables to execute tests from any working directory without typing absolute file paths.

Step 2: Construct the Basic Command Syntax and Parameters

Assemble the core command structure by calling the executable followed by mandatory arguments specifying the project action. The standard syntax requires the project path flag pointing to your zipped or unzipped NeoLoad project file, alongside the run identifier command. You must also designate the results folder destination to ensure test metrics are properly saved for post-processing analysis.

Warning: Avoid utilizing spaces within unquoted file paths inside command-line arguments, as this causes parser errors and premature execution termination; always wrap directory paths containing spaces in double quotation marks.

Step 3: Configure Load Generators and Infrastructure Mapping

Define the load generation infrastructure within your command string by passing parameters that allocate specific load generator machines. If your test relies on static infrastructure, supply the IP addresses or hostnames of the remote load generators using the designated load generator flags. For dynamic test environments, integrate your cloud platform credentials or API tokens to automatically provision and decommission load generators on demand before the execution phase begins.

Step 4: Execute the Test Run and Monitor Real-Time Output

Initiate the performance test by pressing enter on the fully constructed command line string. The terminal window will stream real-time execution logs, indicating the phase transitions from project loading and infrastructure reservation to ramp-up, steady-state load application, and ramp-down. Monitor the standard output for any connection errors, licensing faults, or script assertions that fail during the initialization phase.

Step 5: Export and Parse Post-Test Reports Automatically

Configure post-processing arguments within your command execution string to automatically generate analytical reports immediately following test completion. Instruct the command-line runner to export performance metrics into PDF, XML, or JUnit formats for automated ingestion by quality gates or dashboarding tools like SonarQube or Grafana. Ensure your CI/CD pipeline script captures the exit codes returned by the NeoLoad command-line tool to pass or fail the build based on your defined Service Level Agreements.

Comparative Overview of NeoLoad Execution Methods

Troubleshooting Common Command-Line Execution Failures

• Root Cause: The command-line utility fails to initialize due to an unassigned or expired license token on the controller machine. Actionable Fix: Verify license availability by launching the GUI once to refresh the lease or pass valid license server credentials explicitly within the command arguments using the designated licensing parameters.

• Root Cause: Remote load generators cannot establish communication sockets with the controller during the startup phase. Actionable Fix: Inspect firewall configurations on both the controller and load generator hosts to ensure TCP port 7100 and associated dynamic port ranges remain open and unblocked by network security policies.

• Root Cause: The execution script halts prematurely with a file-not-found exception regarding the target project zip file. Actionable Fix: Convert relative file paths to absolute file paths in your command string and verify that the user profile executing the command possesses read and write permissions for the target directories.

• Root Cause: Continuous integration build steps fail because the command-line tool exits with a non-zero status code despite test completion. Actionable Fix: Review the SLA evaluation thresholds configured inside your NeoLoad project, as failing SLA metrics intentionally trigger error exit codes to halt failing deployment pipelines.

Frequently Asked Questions

Can I run a NeoLoad command-line test without opening the GUI?

Yes, the command-line interface is engineered for completely headless execution, meaning you can run, monitor, and report on performance tests on servers without graphical desktop environments installed.

How do I pass runtime variables from a CI/CD pipeline into the NeoLoad CLI?

You can inject dynamic parameters, such as iteration counts, user loads, or target server URLs, by passing variable flags directly into the command string using the specific variable override syntax supported by the NeoLoad runner.

What exit codes does the NeoLoad command-line runner return?

The executable typically returns zero upon successful test completion that meets all SLA criteria, while non-zero exit codes signify configuration errors, licensing failures, or breached performance thresholds during the run.

Is it possible to execute multiple test scenarios in parallel using the CLI?

Yes, by provisioning separate controller instances and distinct port configurations, you can invoke multiple parallel command-line runner processes from separate shell terminals or distinct build agent nodes.

Where are the generated result files stored after a CLI test run?

Result files are automatically written to the directory specified by the results path argument in your command string, outputting standard NeoLoad result archives that can be opened later or parsed into external tools.

Elevate your performance engineering efficiency by embedding automated NeoLoad command-line executions into your continuous delivery pipelines today. Implement these precise scripts to guarantee robust application scalability under heavy enterprise workloads.