Ranorex Integration with NeoLoad...Neotys How-To – Ranorex Integration with NeoLoad Global Configuration Four global modes exist: DESIGN, RUNTIME, END_USER_EXPERIENCE and NO_API

©Neotys. All Rights Reserved.

Neotys How-To – Ranorex Integration with NeoLoad

Ranorex Integration with NeoLoad

A Neotys How-To

©Neotys. All Rights Reserved 2


Table of Contents

Overview .......................................................................................................................................... 3

Setting up the NeoLoad Ranorex Plugin .................................................................................... 4

Global Configuration ................................................................................................................... 6

NeoLoad Module Definitions ........................................................................................................... 8

Tutorials ..................................................................................................................................... 15

About Neotys ................................................................................................................................. 26



Overview

C# extensions to integrate Ranorex with NeoLoad for Script maintenance and End User Experience measurement. It allows you to interact with the NeoLoad API:

• Design API to convert Ranorex script to NeoLoad, update an existing User Path, start/stop recording, open/close/save/create NeoLoad project,

• Runtime API to start/stop a test, start/stop Virtual Users, • DataExchange API to send End User Experience measurement to NeoLoad during

the load test execution.

Property Value

Maturity Experimental

Author Ranorex

License BSD 2-Clause "Simplified"

NeoLoad Licensing

License FREE edition, or Enterprise edition, or Professional with Integration & Advanced Usage

Ranorex Licensing

Ranorex license or a free 30-day trial

Supported versions

Tested with Ranorex version 8.1.1 and NeoLoad version 6.4.0

Supported Browsers

Internet Explorer, Google Chrome

Download Binaries

See the latest release

https://www.ranorex.com/https://www.neotys.com/neoload/overviewhttps://www.neotys.com/documents/doc/neoload/latest/en/html/#11265.htmhttps://www.neotys.com/documents/doc/neoload/latest/en/html/#18727.htmhttps://www.neotys.com/documents/doc/neoload/latest/en/html/#7676.htmhttps://github.com/Neotys-Labs/Ranorex/blob/master/LICENSEhttps://www.ranorex.com/prices/https://www.ranorex.com/free-trial/https://info.ranorex.com/e/428272/download-zip-Ranorex-8-1-1/9xvs1r/871610304https://www.neotys.com/support/download-neoloadhttps://www.nuget.org/packages/Neoload.Ranorex/



Setting up the NeoLoad Ranorex Plugin

On Ranorex Studio, add the latest version of the NeoLoad Ranorex Plugin from NuGet:

• Right-click on the References node in the Ranorex Projects view.

• Select Manage Packages...:



Search for NeoLoad in nuget.org and add the NeoLoad Ranorex Plugin package:

This will automatically add the necessary libraries to the Ranorex project. The following modules will now appear in the module browser:



Global Configuration

Four global modes exist: DESIGN, RUNTIME, END_USER_EXPERIENCE and NO_API. The mode can be set as an environment variable (in this case a Ranorex Studio restart is mandatory) or as a global parameter of the test suite. The variable key to set is nl.ranorex.neoload.mode . To set a Ranorex test suite global parameter open Global parameters window:

Then add the key and the value of the parameter:



If defined, the Ranorex test suite global parameter will overwrite the System environment variable. Default mode is NO_API.

No API Mode

All NeoLoad Modules are disabled. This mode is used to start only functional recording.

Design Mode

Used for NeoLoad recording modules.

Runtime Mode

Used for NeoLoad runtime modules as StartTest and StopTest.

End User Experience Mode

Used to send measured timer to Data Exchange API.



NeoLoad Module Definitions

Module NL_ConnectToDesignAPI

This module establishes a connection to the NeoLoad Design API. Parameters:

• DesignApiUri: The Uniform Resource Identifier (URI) of the NeoLoad REST service.

• ApiKey: API Key specified in NeoLoad project when identification is required. If no identification is required, this variable can be left blank.

To access these values, go to the NeoLoad Preferences, then the Project settings tab, then select the REST API category.



Module NL_CreateProject

This module creates a new NeoLoad project. Enabled only in DESIGN mode. Parameters:

• projectName: The name of the NeoLoad project

• directoryPath: The location of the project. By default, projects are created in NeoLoad projects folder

• overwriteExisting: Default value is false. If set to true, an existing project with the same name and location is deleted

Module NL_OpenProject

This module opens a NeoLoad project. Parameters:

• filePath: The path to the NLP file

Module NL_CloseProject

This module closes a NeoLoad project. Parameters:

• saveProject: Boolean. Default value is true. If set to false, current project is not saved

• forceStop: Boolean. Default value is false. If set to true, running tests and recordings are stopped

Module NL_SaveProject

This module saves a NeoLoad project. Enabled only in DESIGN mode. Two optional

parameters:

• Timeout: The maximum amount of time (in hh:mm:ss) given to Ranorex to accomplish the save action (default value: 00:05:00)

• Interval: The time interval (in hh:mm:ss) after which Ranorex retries to save project (default value: 00:00:20)

Module NL_StartRecording

This module starts a recording. Enabled only in DESIGN mode. Parameters:

• Timeout: The maximum amount of time (in hh:mm:ss) given to Ranorex to start the recording (recommended value: 00:01:00).



• Interval: The time interval (in hh:mm:ss) after which Ranorex retries to start a recording (recommended value: 00:00:10)

• UpdateUserPath: Boolean. Default value is true. Update existing user path. If set to false the existing user path will not be updated and and error will be thrown

• userPath: The name of the User Path to create (the default value is "UserPath"). If the name is already used and UpdateUserPath is true, then it is automatically renamed using a “X” suffix, where X is an integer. If the name has invalid characters then they will be escaped as an underscore () and no error is thrown

Module NL_StartRecording_Extended

This module is starts recording with more parameters. Enabled only in DESIGN mode.

• Timeout: The maximum amount of time (in hh:mm:ss) given to Ranorex to start the recording (recommended value: 00:01:00).

• Interval: The time interval (in hh:mm:ss) after which Ranorex retries to start a recording (recommended value: 00:00:10).

• UpdateUserPath: Boolean. Default value is true. Update existing user path. If set to false the existing user path will not be updated and an error will be thrown.

• userPath: The name of the User Path to create (the default value is "UserPath"). If the name is already used and UpdateUserPath is true, then it is automatically renamed using a “X” suffix, where X is an integer. If the name has invalid characters then they will be escaped as an underscore () and no error is thrown.

• userAgentString: Used to specify the user agent.

• isWebSocketProtocol: Boolean. Default value is false.

• isHttp2Protocol: Boolean. Default value is false.

• isAdobeRTMPProtocol: Boolean. Default value is false.

• addressToExclude: List of addresses separated by a semicolon. Requests and responses through these addresses will not be taken into account by Neoload when recording (For example: 10.0.0.5:7400;10.3.1.15;localhost:9100)

Module NL_StopRecording

This module stops a recording. Enabled only in DESIGN mode. Parameter:



• nl_timeout: Integer. Default value is 1200 seconds. Set the timeout in seconds to wait for the end of the post record process.

Module NL_StopRecording_Extended

This module is stops recording with more parameters. These are enabled only in DESIGN mode.

• nl_timeout: Integer. Default value is 1200 seconds. Set the timeout in seconds to wait for the end of the post record process

• frameworkParameterSearch: Boolean. Default value is true

• genericParameterSearch: Boolean. Default value is true

• deleteExistingRecording: Boolean. Default value is false

• includeVariablesInUserpathMerge: Boolean. Default value is true

• updateSharedContainers: Boolean. Default value is false

• matchingThreshold: Integer. Default value is 60

Module NL_ConnectToRuntimeAPI

This module establishes a connection to the NeoLoad Runtime API. Enabled only in RUNTIME mode. Parameters:

• RuntimeApiUri: The Uniform Resource Identifier (URI) of the NeoLoad REST service

• ApiKey: API Key specified in NeoLoad project when identification is required. If no identification is required, this variable can be left blank

To access these values, go to the NeoLoad Preferences, then the Project settings tab, then

select the REST API category.



Module NL_StartTest

This module starts a NeoLoad test scenario. You need to define the scenario in NeoLoad before. Enabled only in RUNTIMEmode. Parameters:

• Scenario: The scenario, as defined within the NeoLoad test, that should be started

• Timeout: The maximum amount of time (in hh:mm:ss) given to Ranorex to start a specific test (recommended value: 00:01:00)

• Interval: The time interval (in hh:mm:ss) after which Ranorex retries to start a specific test (recommended value: 00:00:10)

Module NL_StopTest

This module stops the currently running NeoLoad test. Enabled only in RUNTIME mode. Parameters:

• Timeout: The maximum amount of time (in hh:mm:ss) given to Ranorex to start a specific test (recommended value: 00:01:00)

• Interval: The time interval (in hh:mm:ss) after which Ranorex retries to start a specific test (recommended value: 00:00:10)



• forceStop: Boolean. Default value is false

Module NL_AddVirtualUsers

This module adds virtual users to a population, defined in a NeoLoad test scenario. This module can only be used when a test is already running. Enabled only in RUNTIME mode. Parameters:

• Population: The population, as defined in the NeoLoad test scenario, virtual users will be added to

• Amount: Integer. The number of virtual users that should be added to the given population

Module NL_StopVirtualUsers

This module stops virtual users from a population, which is defined in a NeoLoad test scenario. This module can only be used when a test is already running. Enabled only in RUNTIME mode. Parameters:

• Population: The population, as defined in the NeoLoad test, virtual users will be stopped from

• Amount: The number of virtual users specified that will be stopped from the given population

Module NL_ConnectToDataExchangeAPI

This module establishes a connection to the NeoLoad Data Exchange API. Enabled in RUNTIME and END_USER_EXPERIENCEmodes. Parameters:

• DataExchangeApiUri: The Uniform Resource Identifier (URI) of the NeoLoad REST service

• ApiKey: API Key specified in NeoLoad project when identification is required. If no identification is required, this variable can be left blank. To access these values, go to the NeoLoad Preferences, then the Project settings tab, then select the REST API category



• Location: The location, where the functional test is performed (e.g., Graz, London, Office XYZ...)

• Hardware: The hardware used where the functional test is running (e.g., Intel i5-5200u). A string describing the utilized operating system is automatically appended to the string defined

• Software: The software, tested in the functional test. When testing a browser, it is recommended to hand over the browser name. When performing a cross-browser test, it is recommended to bind this variable to the column specifying the browsers



Tutorials

How to Open/Create/Save/Close a NeoLoad Project

Interaction with the NeoLoad Design API allows you to open/create/save/close NeoLoad project from Ranorex module.

• Insert the module NL_ConnectToDesignAPI into the test case

• To open an existing NeoLoad project, insert module NL_OpenProject into the test case

• To create a new NeoLoad project, insert module NL_CreateProject into the test case

• To save a NeoLoad project, insert module NL_SaveProject into the test case



• To close a NeoLoad project, insert module NL_CloseProject into the test case.

How to record/update a Ranorex script into a NeoLoad User Path

Interaction with the NeoLoad Design API allows you to record/update a Ranorex script into NeoLoad.

• Insert the module NL_ConnectToDesignAPI into the test case

• Insert the module NL_StartRecording into the test case, before the recording

• Insert the module NL_StopRecording into the test case, after the recording

• If the application is SSL, make sure the browser used to run the Ranorex script has the NeoLoad Root certificate installed. See NeoLoad documentation for more details

During the execution of the Ranorex test case, if the NeoLoad User Path does not exist, it

will be created. Otherwise, the existing User Path will be updated.

https://www.neotys.com/documents/doc/neoload/latest/en/html/#757.htm



How to Manage Transactions

NeoLoad transactions management can be done by inserting user code actions in the Ranorex recording.

Design Mode

• StartTransaction: Starts a new NeoLoad transaction. A transaction name is mandatory

• StopTransaction: Not used for this mode

End User Experience Mode

A connection to the Data Exchange API is required before invoking these actions.

• StartTransaction: Starts the timer and stops the last running one

• StopTransaction: Stops the timer and send it using Data Exchange API

Using a Ranorex record

Add user code action as steps in the recording



How to Start/Stop a NeoLoad Test

Interaction with the NeoLoad Runtime API allows you to start/stop a NeoLoad test.

• Insert the module NL_ConnectToRuntimeAPI into the test case

• Insert the module NL_StartTest into the test case

• Insert the module NL_StopTest into the test case

How to Add/Stop Virtual Users to a Running NeoLoad Test

Interaction with the NeoLoad Runtime API allows you to add/stop Virtual Users during a NeoLoad test.

• To add Virtual Users, insert the module NL_AddVirtualUsers into the test case

• To stop Virtual Users, insert the module NL_StopVirtualUsers into the test case



How to Send End User Experience Measurements to NeoLoad

Opening a website is related to a certain latency. This latency depends on various factors, such as the network connection or the browser used. It can be measured with the Navigation Timing API, which is offered by all browsers. If you evaluate these timing values, especially when the website is under load, you can localize potential bottlenecks. Eliminating the identified bottlenecks will ultimately improve the end user experience.

The Ranorex SendTimingValues User Code allows you to send End User Experience measurement to NeoLoad. To use that user code:

• Make sure the file was recorded with a browser having the Ranorex plugin up and running

• Right click on the Ranorex recording file, and select Add new action, then User code, and then Select from library



• Then select the user code SendTimingValues and confirm



• Fill column domNode with the DOM node of the element you need a timer



• Fill column transactionName. The timer values will be accessible in the NeoLoad External Data with a category of that transaction name

• Insert the module NL_ConnectToDataExchangeAPI inside the test case. Make sure to insert this module after the test is started, and before executing the SendTimingValues code



About Neotys The success of your digital strategy relies on your ability to deliver fast and reliable software, regularly. Creating great software quickly, using an optimized performance testing process is your competitive advantage – Agile and DevOps are part of the solution.

Neotys has nearly 15 years of development investment into NeoLoad – the performance testing platform designed to accelerate Agile and DevOps processes. It’s built by engineers who recognized that to achieve their Agile adoption objective, they needed to create a product that could facilitate superior load and performance testing continuously.

The result – up to 10x faster test creation and maintenance with NeoLoad

We genuinely believe that the Performance Engineer can become the critical application performance partner providing the best testing coverage while respecting the cadence of the Continuous Delivery process. As performance becomes the responsibility of the wider team, continued delivery of an optimized performance testing platform is what drives our work every day.

For more information about Neotys and NeoLoad visit: www.neotys.com or contact [email protected]

Neotys and NeoLoad are registered trademarks of Neotys SAS in the USA and others countries. All other trademarks are the property of their respective owners. Copyright © Neotys. All rights reserved. No reproduction, in whole or in part, without written permission.

http://www.neotys.com/mailto:[email protected]

Table of ContentsOverviewSetting up the NeoLoad Ranorex PluginGlobal ConfigurationNo API ModeDesign ModeRuntime ModeEnd User Experience Mode

NeoLoad Module DefinitionsModule NL_ConnectToDesignAPIModule NL_CreateProjectModule NL_OpenProjectModule NL_CloseProjectModule NL_SaveProjectModule NL_StartRecordingModule NL_StartRecording_ExtendedModule NL_StopRecordingModule NL_StopRecording_ExtendedModule NL_ConnectToRuntimeAPIModule NL_StartTestModule NL_StopTestModule NL_AddVirtualUsersModule NL_StopVirtualUsersModule NL_ConnectToDataExchangeAPITutorialsHow to Open/Create/Save/Close a NeoLoad ProjectHow to record/update a Ranorex script into a NeoLoad User PathHow to Manage TransactionsDesign ModeEnd User Experience ModeHow to Start/Stop a NeoLoad TestHow to Add/Stop Virtual Users to a Running NeoLoad TestHow to Send End User Experience Measurements to NeoLoad

About Neotys

Documents

Ranorex Integration with NeoLoad...Neotys How-To – Ranorex Integration with NeoLoad Global Configuration Four global modes exist: DESIGN, RUNTIME, END_USER_EXPERIENCE and NO_API