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 to trigger headless test controllers. Leveraging the NeoLoad Controller and Load Generator architecture ensures consistent, repeatable execution within continuous integration pipelines while meeting strict performance thresholds for response time and throughput.

Prerequisites and Environment Setup for Headless Execution

Executing a performance test without the graphical interface requires a well-prepared host machine, proper licensing verification, and correct environmental paths. Transitioning from a manual desktop workflow to an automated command-line execution requires strict attention to file paths, controller configurations, and access permissions.

• Essential Tools and Software: NeoLoad Controller, NeoLoad Load Generator, NeoLoad project archive (.nlp format or extracted workspace), and the NeoLoad Command Line Interface binary (NeoloadCmd).
• Prerequisite Knowledge and Standards: Familiarity with command-line interfaces across Windows, Linux, or macOS, understanding of continuous integration webhooks, and knowledge of JSON or XML result formatting.
• Estimated Setup Duration: Approximately 30 to 45 minutes for initial path configurations and validating headless controller communication ports.

Step-by-Step Command Line Execution Workflow

Step 1: Locate the NeoloadCmd Binary and Verify Environment Variables

Locate the NeoLoad command-line executable on your operating system to begin the execution process. On Windows systems, this binary typically resides in the Program Files directory under the NeoLoad installation path. On Linux environments, it is usually located in the opt directory or designated bin folders. Ensure that the installation directory is added to your system environment variables path to allow execution from any working directory without specifying absolute paths.

Pro-Tip: Run the NeoloadCmd executable with the version flag via your terminal to verify that the licensing server communicates properly with the command-line utility before initiating a full-scale test run.

Step 2: Prepare the Project File and Variable Overrides

Export your fully validated NeoLoad project into a stable workspace directory. If your test scenario requires runtime parameter adjustments, such as modifying ramp-up times, user load distributions, or specific population sizes, prepare an external property file or define command-line variables. Command-line parameters allow you to inject dynamic data, target server URLs, and credentials without altering the core project file manually.

Step 3: Construct the Execution Command Syntax

Build the execution command by combining mandatory and optional arguments within your terminal. The basic syntax requires specifying the project path using the project flag, the scenario name using the scenario flag, and the results folder destination using the results flag. Additional flags allow you to control result publishing, SLA evaluations, and automatic shutdown of load generators upon completion.

Warning: Avoid embedding plaintext credentials or sensitive API tokens directly into the command string within shared terminal histories; instead, utilize environment variables or secure credential vaults.

Step 4: Execute the Test and Monitor Real-Time Logs

Execute the constructed command and observe the standard output stream for initialization logs, controller handshakes, and virtual user ramp-up metrics. The terminal will output real-time transaction success rates, error counts, and overall test health indicators. Ensure that your network monitoring tools remain active to track resource utilization on both the load generators and the target system under test.

Step 5: Evaluate SLA Status and Export Results

Upon test completion, review the exit codes and generated report files to determine whether the execution met your predefined Service Level Agreements. NeoLoad generates XML and PDF reports automatically in the specified results directory, which can be parsed by CI/CD tools or quality gates to pass or fail the deployment build automatically.

Technical Parameters and Command-Line Flags Comparison

Common Command Line Execution Failures and Field Fixes

• License Acquisition Failure:
  
  
  • Root Cause: The command-line utility cannot reach the NeoLoad License Server, or all available virtual user licenses are currently occupied by another active session.
  • Actionable Fix: Verify network connectivity to the license server, check firewall rules on port allocations, and release dangling licenses from previous ungraceful terminations.
• Missing Project Dependencies:
  
  
  • Root Cause: The NeoLoad project references external CSV files, custom JavaScript modules, or variable files using absolute paths that do not exist on the target runner machine.
  • Actionable Fix: Convert all external file dependencies to relative paths within the project workspace before archiving and transferring the project to the execution server.
• Unresolved Scenario Name Error:
  
  
  • Root Cause: A typo exists within the scenario string passed to the execution command, or the specified scenario was deleted or renamed in the latest project revision.
  • Actionable Fix: Open the project file or list available scenarios using the project inspection utility to verify exact naming conventions and capitalization.

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 that includes only the Controller, Load Generator, and Command Line Interface components. This lightweight installation saves disk space and server resources on remote execution nodes and CI/CD agents.

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

You can pass custom variables into your test run by utilizing the command-line argument flag designed for variable injection followed by key-value pairs. These parameters override default values defined in your project variables at runtime.

What exit codes does NeoloadCmd return upon completion?

The NeoloadCmd utility returns specific numeric exit codes where zero typically indicates a successful test run with all SLAs passed. Non-zero exit codes represent various failure states, such as SLA violations, license errors, or unexpected runtime exceptions, which help trigger build failures in pipelines.

Can I automatically generate HTML or PDF reports via the command line?

Yes, you can include export flags in your execution command or configure post-processing commands to automatically compile raw XML result files into executive PDF or detailed HTML summary reports immediately after the test concludes.

Automate your performance testing pipelines today by integrating headless NeoLoad command-line execution into your continuous integration workflows for rapid, reliable validation.