Applications are often not designed to handle slow networks. Network Virtualization (NV) helps you to understand how slow networks affect your application's performance and what you can do to optimize client and server performance in your application.
Do your customers complain that your application works slowly? Are there timeout exceptions? Has your application ever failed when moved to production, even though the application worked perfectly when tested under lab conditions? Does your application suffer from non-reproducible issues?
The NV API lets you test your application behavior under various network conditions, analyze performance results, and view optimization recommendations for improving application performance.
Learn more about NV at http://nvhelp.saas.hpe.com/en/9.10.
This Java library lets you call the NV API in your automated tests (for example, your Selenium tests). You can use this API instead of using the NV Test Manager user interface.
This Readme includes the following topics:
- Prerequisites
- Usage
- Get Started
- Classes:
- TestManager Class
- Test Class
- Transaction Class
- IPRange Class
- Range Class
- Flow Class
- Enums
- Samples:
- Basic Step-by-Step Samples:
- BasicNVTest.java
- BasicAnalyzeNVTest.java
- BasicComparisonWithoutNV.java
- BasicAnalyzeNVTransactions.java
- BasicAnalyze2Scenarios.java
- Advanced Samples:
- AdvAllTestClassMethods.java
- AdvRealtimeUpdate.java
- AdvAllTestManagerClassMethods.java
- AdvMultipleTestsSequential.java
- AdvMultipleTestsConcurrent.java
- Basic Step-by-Step Samples:
- Debugging
- License
- Java 7 installed (http://java.oracle.com) and available in your $PATH
- Apache maven 3.2.2 (or later) installed (http://maven.apache.org/) and available in your $PATH
- NV Test Manager 9.10 or later
- To try the samples, use a Chrome or Firefox browser.
Note: If you are using Chrome, download ChromeDriver (https://sites.google.com/a/chromium.org/chromedriver/) and add it to your $PATH.
-
To try the samples (located in https://github.com/HewlettPackard/hpe-nv-java):
- mvn clean install the pom.xml to create the hpe-nv-java-samples-<version>.jar under the target folder.
- Either run the batch files from the \hpe-nv-java-samples\scripts folder, or run the samples directly from your favorite Java IDE.
- To read more about the samples, go to the "Samples" section below.
-
To create a custom test of your own that calls the NV Java API, create a Maven project and use the following Maven dependency in your project's pom.xml:
<dependency> <groupId>com.hpe.nv</groupId> <artifactId>hpe-nv-java-api</artifactId> <version>1.0.0</version> </dependency>
Try a few basic samples (under the \hpe-nv-java-samples\src\main\java\com\hpe\nv\samples\basic folder). The "Samples" section below describes all of our samples. For example, start with BasicNVTest.java and BasicAnalyzeNVTest.java.
Here's a basic code example that shows how to start a test in NV, run a transaction, stop the transaction, stop the test, and finally analyze the test results. This example shows how to create a home page transaction, but you can create any type of transaction, such as a search transaction.
static TestManager testManager;
static Test siteTest;
static Transaction pageTransaction;
// Create and initialize the TestManager object
public static void initTestManager() throws Exception {
// create a TestManager object
testManager = new TestManager(serverIp, serverPort, username, password);
testManager.setUseSSL(ssl);
// call the init method
testManager.init();
}
// start an NV test with the "3G Busy" network scenario
public static void startBusyTest() throws Exception {
// create an NV test
String testName = "Sample Test";
String networkScenario = "3G Busy";
siteTest = new Test(testManager, testName, networkScenario);
siteTest.setTestMode(Test.Mode.CUSTOM);
// add a flow to the test
Flow flow = new Flow("Flow1", 200, 0.5, 384, 128);
siteTest.addFlow(flow);
// start the test
EmulationResponse emulationResponse = siteTest.start();
System.out.println("New test started. Test token: \"" + emulationResponse.getTestToken() + "\"");
}
// connect the NV test to the transaction manager
public static void connectToTransactionManager() throws Exception {
ConnectResponse connectResult = siteTest.connectToTransactionManager();
System.out.println("Connected to the transaction manager with session ID: \"" + connectResult.getTransactionManagerSessionIdentifier() + "\"");
}
// start the "Home Page" NV transaction
public static void startTransaction() throws Exception {
// create an NV transaction
String transactionName = "Home Page";
pageTransaction = new Transaction(transactionName);
// add the NV transaction to the NV test
TransactionEntity transactionEntity = pageTransaction.addToTest(siteTest);
System.out.println("New transaction added with ID \"" + transactionEntity.getId() + "\"");
// start the NV transaction
TransactionResponse startTransactionResult = pageTransaction.start();
System.out.println("Started transaction named \"" + pageTransaction.getName() + "\" with ID \"" + startTransactionResult.getTransactionIdentifier() + "\"");
}
// navigate to the site's home page using the Selenium WebDriver
public static void seleniumNavigateToPage() {
// insert your Selenium code to navigate to your site's home page
...
}
// stop the "Home Page" NV transaction
public static void stopTransaction() throws Exception {
TransactionResponse stopTransactionResult = pageTransaction.stop();
System.out.println("Transaction with ID \"" + stopTransactionResult.getTransactionIdentifier() + "\" stopped");
}
// stop the NV test
public static void stopTest() throws Exception {
EmulationStopResponse stopTestResult = siteTest.stop();
System.out.println("Test with token \"" + siteTest.getTestToken() + "\" stopped. Path to .shunra file: " + stopTestResult.getAnalysisResourcesLocation().get(siteTest.getTestToken()));
}
// analyze the NV test and retrieve the result as an object
public static void analyzeTest() throws Exception {
ExportableResult analyzeResult = (ExportableResult) siteTest.analyze(analysisPorts);
printNetworkTime(analyzeResult);
}
// print the transaction's network time
public static void printNetworkTime(ExportableResult analyzeResult) {
ArrayList<ExportableSummary> transactionSummaries = analyzeResult.getTransactionSummaries();
ExportableSummary firstTransactionSummary = transactionSummaries.get(0);
DocumentProperties firstTransactionProperties = firstTransactionSummary.getProperties();
System.out.println("\"Home Page\" transaction network time: " + (firstTransactionProperties.getNetworkTime()/1000) + "s");
}
public static void main(String[] args) {
initTestManager();
startBusyTest();
connectToTransactionManager();
startTransaction();
seleniumNavigateToPage();
stopTransaction();
stopTest();
analyzeTest();
printNetworkTime();
}This section describes the library's classes - including their methods, exceptions, and so on.
Note: Methods not described in this section are for internal use only.
This class represents a connection instance to a specific NV Test Manager.
Important note: If you are using a secure Test Manager installation, set the "useSSL" property to true using the setUseSSL method.
The class includes the following methods:
-
TestManager(String serverIP, int serverPort, String username, String password) - the constructor method Parameters:
- serverIP - NV Test Manager IP
- serverPort - NV Test Manager port
- username - username for authentication
- password - password for authentication
-
setUseSSL(boolean useSSL) - sets the useSSL Boolean value.
Parameters - useSSL: set to true if you are using a secure Test Manager installation. Default: falseReturns - void
-
init() - initializes the TestManager object with the pre-existing tests, both completed and running Returns - void
Throws:
- NVExceptions.MissingPropertyException - if the existing tests have missing properties.
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
stopAllTests() - stops all tests that are part of the emulation
Returns - an EmulationStopResponse object which contains a list of Shunra files (one .shunra file per test), for example:{ "analysisResourcesLocation": { "073bac1a-48a9-4f70-9c22-df23ff21473db3673d23-f4d4-47c1-817a-b619f7d7b032": "C:\\tmp\\TrafficResources\\073bac1a-48a9-4f70-9c22-df23ff21473d\\b3673d23-f4d4-47c1-817ab619f7d7b032\\AnalysisResources.shunra" } }Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
stopTests(List<Test> tests) - stops the specified list of tests
Parameters:- tests - a list of tests to stop
Returns - an EmulationStopResponse object (the same object as in "stopAllTests" method)
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
getTestTokens(boolean allUsers) - gets all running test tokens
Parameters:- allUsers - set to true to return test tokens for all users, not just the user for API authentication. The user for API authentication must have administrator privileges to use this parameter.
Returns - a MultiUserEmulationTokensResponse object that contains all the running test tokens, for example:
{ "tests": [{ "userId": "admin", "emulationEngine": { "IL-Igor-LT.shunra.net": { "testTokens": ["fe7aff67-6eef-4c92-b357-80da7becf50937d7cb1d-4a18-42ae-8533-992e4f2945a7"], "emulationMode": "SINGLE_USER" } } }] }Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
startPacketListCapture() - starts capturing all packet lists in all running tests
Returns - voidThrows:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
stopPacketListCapture() - stops capturing all packet lists in all running tests
Returns - voidThrows:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
getPacketListInfo() - provides packet list information for all packet lists in all running tests
Returns - a PacketListInfoResponse object, for example:{ "packetListsInfo": [ { "flowId": "FLOWS_4", "plId": "ID_PACKET_LIST_CLIENT_FLOWS_4", "captureStatus": "CAPTURING" }, { "flowId": "FLOWS_5", "plId": "ID_PACKET_LIST_CLIENT_FLOWS_5", "captureStatus": "CAPTURING" } ], "globalCaptureStatus" : "CAPTURING" }Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
setActiveAdapter(String ip, boolean reverseDirection) - sets the active adapter used for the emulation. An active adapter determines the NIC through which impairments are applied to the traffic and packets are captured. Only IPV4 is supported.
Parameters:- ip - the active adapter IP
- reverseDirection - (Relevant when using "Default Flow") When the packet direction cannot be determined from the packet header,
NV cannot determine if the packet originated in the client or the server.
Possible values:- false. The packets are treated as if the NV Driver is installed on the client. All packets arrive from the server endpoint, and all packets exit to the server endpoint.
- true. The NV driver is considered as if installed on the server. All packets arrive from the client endpoint, and all packets exit to the client endpoint.
Returns - void.
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
- NVExceptions.UpdateConfigErrorException - if tests are currently running (because the active adapter cannot be updated during a run session).
-
setActiveAdapter(String ip) - sets the active adapter used for the emulation with a reverseDirection property value of false (see above for details on the "reverseDirection" property). An active adapter determines the NIC through which impairments are applied to the traffic and packets are captured. Only IPV4 is supported. Parameters - the active adapter IP
Returns - void
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
- NVExceptions.UpdateConfigErrorException - if tests are currently running (because the active adapter cannot be updated during a run session).
-
getActiveAdapter() - gets the active adapter
Returns - the ActiveAdapter object, for example:{ "ip": "192.168.0.101", "reverseDirection": false }Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
setConfiguration(boolean isPacketListCaptureCyclic, int packetListMaxSizeMB, double packetListServerClientRatio) - sets the NV configuration
Parameters:- isPacketListCaptureCyclic - Default: true
- packetListMaxSizeMB - the maximum size of the packet list (comprises all devices in a test)
- packetListServerClientRatio - Default: 0 (all packet lists are allocated on the client side)
Returns - void.
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
- NVExceptions.UpdateConfigErrorException - if tests are currently running, the configuration cannot be updated.
-
getConfiguration() - gets the NV configuration
Returns - a ConfigurationSettings object, for example:{ "isPacketListCaptureCyclic": true, "packetListMaxSizeMB": 100, "minNumOfPacketListSpace": 3, "captureBytesPerPacket": 1500, "packetListServerClientRatio": 0 }Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
analyzeShunraFile(String[] ports, String zipResultFilePath, String shunraFilePath) - analyzes the specified .shunra file and returns the analysis result as a .zip file
Parameters:- ports - array of ports to be analyzed
- zipResultFilePath - the path of the .zip file that is created. Default: "analysis-result.zip"
- shunraFilePath - the .shunra file path used for analysis
Returns - a File object associated with the created .zip file
Throws:
- NVExceptions.MissingPropertyException - if the "shunraFilePath" parameter passed is null.
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
analyzeShunraFile(String[] ports, String shunraFilePath) - analyzes the specified .shunra file and returns the analysis result object
Parameters:- ports - array of ports to be analyzed
- shunraFilePath - the .shunra file path used for analysis
Returns - an ExportableResult object (an analysis result object)
Throws:
- NVExceptions.MissingPropertyException - if the "shunraFilePath" parameter passed is null.
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
This class represents an NV test instance and includes the following methods:
-
Test(TestManager testManager, String testName, String networkScenario) - the constructor method Parameters:
- testManager - a previously created TestManager object that contains the NV server URL, NV server port, user credentials, and so on
- testName - test name
- networkScenario - network scenario name
Throws:
- NVExceptions.MissingPropertyException - if one of the properties passed is null.
-
setDescription(String description) - sets the test's description
Parameters - the test's descriptionReturns - void
-
setEmulationMode(String emulationMode) - sets the emulation mode Parameters - the emulation mode. Set to "MULTI_USER" to use MULTI_USER emulation and set to "SINGLE_USER" to use SINGLE_USER emulation
Returns - void
-
setTestMode(Mode testMode) - sets the test mode
Parameters - a Test.Mode enum. Possible values: Test.Mode.NTX and Test.Mode.CUSTOM.Returns - void
-
setNtxxFilePath(String ntxxFilePath) - sets the path to the .ntx/.ntxx file used in Test.Mode.NTX test mode
Parameters - the path to the .ntx/.ntxx file containing the client and server IP rangesReturns - void
-
setOverrideIp(boolean overrideIp) - sets the overrideIp value
Parameters - overrideIp: if set to true, allows you to override the client IP defined in the .ntx/.ntxx file with the active adapter value. In this case, the .ntx/.ntxx file must be a single flow file and the mode must be SINGLE_USER.Returns - void
-
setUseNVProxy(boolean useNVProxy) - sets the "useNVProxy" parameter value. Relevant for analyzing HTTPS traffic. Requires configuration.
In NV Test Manager > Settings tab, configure the NV proxy settings. Then, set the browser's proxy setting to use the IP of your NV Test Manager and the port configured in the proxy settings. For more details, see: http://nvhelp.saas.hpe.com/en/9.10/help/Content/Setup/Setup_environment.htm.
Parameters - useNVProxy: Indicates whether to enable NV to capture and decrypt HTTPS traffic in the test.Returns - void
-
addFlow(flow) - adds a flow to the list of test flows. Used to add a flow to the test before the "start" method is called.
Parameters:- flow - a Flow object
Returns - void
Throws:
- NVExceptions.NotSupportedException - the following are not supported:
a. If the test is currently running
b. More than one "Default Flow" per test
c. "Default Flow" in MULTI_USER mode
d. Empty source and destination IPs when the list of flows is not empty (only one flow is allowed in that case) - NVExceptions.MissingPropertyException - an empty source IP is accepted only if the destination IP is also empty.
-
start() - starts the test
Returns - an EmulationResponse object, for example:{ "testToken":"133a1a9e-2885-443f-9ea5-4de373d4a57a372572b2-0d25-4852-91f8-fb849056c89a" }Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
- NVExceptions.IllegalActionException - if a single-mode test is running, no additional tests can start and if a concurrent-mode test is running, no single-mode tests can start.
- NVExceptions.NotSupportedException - if the test mode set is not supported.
-
connectToTransactionManager(String plId, String clientId, String flowID, boolean overwriteExistingConnection) - connects to the transaction manager. You can optionally specify a specific endpoint or packet list to mark the test's transactions for analysis.
Parameters:- plId - the ID of the packet list from which to connect or null
- clientId - the IP address from which to connect (must be a valid IPv4 address) or null.
- flowID - the ID of a specific flow or null
- overwriteExistingConnection - a Boolean flag indicating whether to overwrite an existing connection. Default: true To connect to all packet lists in the running test, call "connectToTransactionManager" with no parameters.
Returns - a ConnectResponse object, for example:
{ "transactionManagerSessionIdentifier": "Aead518af - 3fa3 - 460c - 9be5 - fc3b6a7101cfB" }Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
connectToTransactionManager() - connects to the transaction manager. Call this method to connect to all packet lists in the running test. Returns - a ConnectResponse object, for example:
{ "transactionManagerSessionIdentifier": "Aead518af - 3fa3 - 460c - 9be5 - fc3b6a7101cfB" }Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
disconnectFromTransactionManager() - disconnects from the transaction manager
Returns - voidThrows:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
- NVExceptions.IllegalActionException - if the test is currently not connected to the transaction manager.
-
stop() - stops the test
Returns - an EmulationStopResponse object (the same object as in the TestManager class' "stopAllTests" method).Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
analyze(String[] ports, String zipResultFilePath) - analyzes the test and gets the analysis result as a .zip file
Parameters:- ports - array of ports whose traffic is analyzed
- zipResultFilePath - the path of the .zip file that is created. Default: "analysis-result.zip"
Returns - a File object associated with the created .zip file
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
- NVExceptions.MissingPropertyException - if the "ports" parameter passed is null.
-
analyze(String[] ports) - analyzes the test and returns the analysis result object. This method does not write the analysis result to a .zip file.
Parameters:- ports - array of ports whose traffic is analyzed
Returns - an ExportableResult object (an analysis result object)
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
- NVExceptions.MissingPropertyException - if the "ports" parameter passed is null.
-
stopAndAnalyze(String[] ports, String zipResultFilePath) - Stops and analyzes the test and gets the analysis result as a .zip file.
Parameters:- ports - array of ports whose traffic is analyzed
- zipResultFilePath - the path of the .zip file that is created. Default: "analysis-result.zip"
Returns - a File object associated with the created .zip file
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
- NVExceptions.MissingPropertyException - if the "ports" parameter passed is null.
-
stopAndAnalyze(String[] ports) - Stops the test, analyzes it, and returns the analysis result object. This method does not write the analysis result to a .zip file.
Parameters:- ports - array of ports whose traffic is analyzed
Returns - an ExportableResult object (an analysis result object)
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
- NVExceptions.MissingPropertyException - if the "ports" parameter passed is null.
-
realTimeUpdate(String networkScenario, String description, String ntxxFilePath) - updates the test in real-time using Test.RTUMode.NTX mode.
Parameters:- networkScenario - the replacement network scenario name
- description - the replacement description
- ntxxFilePath - a path to an .ntx/.ntxx file. You can use the complete .ntx/.ntxx file or only the parts of the file that include the shapes that require updates.
Returns - a RealTimeUpdateResponse object that includes the updated test properties
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
- NVExceptions.IllegalActionException - if, for example, the test is not running or the network scenario passed is not unique.
-
realTimeUpdate(String networkScenario, String description, List<Flow> flows) - updates the test in real-time using Test.RTUMode.CUSTOM mode.
Parameters:- networkScenario - the replacement network scenario name
- description - the replacement description
- flows - the replacement Flow array.
Returns - a RealTimeUpdateResponse object that includes the updated test properties
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
- NVExceptions.IllegalActionException - if, for example, the test is not running or the network scenario passed is not unique.
-
getFlowStatistics(Long startTime, Long endTime, List<String> flows) - gets flow statistics
Parameters:- startTime - used to get statistics from a defined start point. Default: test start time
- endTime - used to get statistics until the defined end point. Default: current time
- flows - list of flow IDs. Specify a null list to get statistics for all flows.
Returns - a MultiFlowStatistics object, for example:
{ "statistics": [{ "timeStamp": 1361528862628, "flowStats": [{ "id": "FLOWS_1", "clientDownStats": { "bps": 480, "total": 300, "bwUtil": 0 }, "clientUpStats": { "bps": 480, "total": 360, "bwUtil": 0 }, "serverDownStats": { "bps": 480, "total": 360, "bwUtil": 0 }, "serverUpStats": { "bps": 480, "total": 300, "bwUtil": 0 }, "cloudStats": { "avgLatency": 500, "packetLossCount": 0, "packetLossPercent": 0, "packetLossTotal": 0 } }] }] }Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
getFlowStatistics(List<String> flows) - gets flow statistics from test start till now (current time)
Parameters:- flows - list of flow IDs. Specify a null list to get statistics for all flows.
Returns - a MultiFlowStatistics object (the same object as in the above "getFlowStatistics" method)
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
getLastStats() - gets the data retrieved in the last call to "getFlowStatistics"
Returns - the last MultiFlowStatistics object retrieved -
getLastStatsTimestamp() - gets the value of the response header "x-shunra-next" in the last call to "getFlowStatistics". This header provides the last timestamp for the latest statistics data. You can use this header for future calls to collect statistics data starting from this timestamp.
Returns - the last timestamp -
startPacketListCapture(String packetListId) - starts capturing the specified packet list
Parameters:- packetListId - used to capture a specific packet list
Returns - void
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
startPacketListCapture() - starts capturing all of the test's packet lists
Returns - voidThrows:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
stopPacketListCapture(String packetListId) - stops capturing the specified packet list.
Parameters:- packetListId - used to stop capturing a specific packet list
Returns - void
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
stopPacketListCapture() - stops capturing all of the test's packet lists.
Returns - voidThrows:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
downloadPacketList(String packetListId, Boolean clear, String packetListFilePath) - downloads the specified packet list
Parameters:- packetListId - the packet list ID
- clear - set to true to clear the packet list after download. Default: false. Use the "clear" flag to save disk space and prevent overwriting packet lists.
- packetListFilePath - the path of the packet list file that is created. Default: "packet-list-<packetListId>.pcap".
Returns - a File object associated with the downloaded packet list file
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
- NVExceptions.MissingPropertyException - if the "packetListId" parameter passed is null.
-
getPacketListInfo(String packetListId) - gets packet list information from all of the test's packet lists or from a specific packet list.
Parameters:- packetListId (optional) - the packet list ID
Returns - a PacketListInfoResponse object (the same object as in the TestManager class' "getPacketListInfo" method)
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
getPacketListInfo() - gets packet list information from all of the test's packet lists.
Returns - a PacketListInfoResponse object (the same object as in the TestManager class' "getPacketListInfo" method)
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
downloadShunra(String packetListId, String shunraFilePath) - downloads a .shunra file containing all of the test's packet lists or a specific packet list (in addition to other files).
Parameters:- packetListId - the packet list ID (used to get a .shunra file containing a specific packet list) or null to get all the packet lists
- shunraFilePath - the path of the .shunra file that is created. Pass null to use the default value: "shunra-<testName>.shunra" or "shunra-<packetListId>" (if "packetListId" is specified)
Returns - a File object associated with the downloaded .shunra file.
Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
This class represents a Transaction instance and includes the following methods:
-
Transaction(String name) - the constructor method
Parameters:- name - the transaction name
-
setDescription(String description) - sets the transaction's description
Parameters:- description - a description for the transaction
Returns - void
-
addToTest(Test test) - adds the transaction to the test specified
Returns - a TransactionEntity object, for example:{ "id": "9ee4f61e-553b-42f4-b616-f6e55da6c39b", "name": "Search", "description": "", "orderNum": 0, "averageUserTime": 0.0, "averageNetworkTime": 0.0, "runs": { } }Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
-
start() - starts the transaction Returns - a TransactionResponse object, for example:
{ "transactionIdentifier": "e16645fa-6f96-4707-b884-fe46b872e3a436434aa6-ae80-4ace-8009-8ee8c970e689", "transactionEntity": { "id": "e16645fa-6f96-4707-b884-fe46b872e3a4", "name": "transaction1", "description": "Login transaction", "averageUserTime": 0, "averageNetworkTime": 0, "orderNum": 0, "runs": { "36434aa6-ae80-4ace-8009-8ee8c970e689": { "id": "36434aa6-ae80-4ace-8009-8ee8c970e689", "startTime": 1382461475606, "endTime": 0, "userTime": 0, "networkTime": 0, "status": "Start", "averageBandwith": 0, "totalThroughputClient": 0, "totalThroughputServer": 0, "aggregateScore": 0, "numberOfErrors": 0, "applicationTurns": 0, "protocolOverhead": 0, "passed": true } } } }Throws:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
- NVExceptions.IllegalActionException - if the transaction was added to an NV test that is not connected to the transaction manager (no session exists).
-
stop() - stops the transaction
Returns - a TransactionResponse objectThrows:
- IOException - if an input or output exception occurs.
- NVExceptions.ServerErrorException - if the NV Test Manager server returns an error.
This class represents an IPRange instance and includes the following methods:
- IPRange(String from, String to, int port, int protocol) - the constructor method
Parameters:- from - pass null to set the "from" address to the default value: 0.0.0.1
- to - pass null to set to the "from" address. If "from" is also null, the "to" address is set to the default value: 255.255.255.255
- port - Default: 0
- protocol - IPRange.PROTOCOL enum values (see "Enums" section below). Default: IPRange.PROTOCOL.ALL
This class represents a Range instance that consists of included and excluded IPRange arrays. It includes the following methods:
- Range() - the constructor method that creates a Range object with empty "include" and "exclude" lists of IP ranges
This class represents a Flow instance and includes the following methods:
-
Flow(String flowId, double latency, double packetloss, double bandwidthIn, double bandwidthOut) - the constructor method
Parameters:- flowId - flow ID
- latency - Default: 100
- packetloss - Default: 0.1
- bandwidthIn - Default: 0
- bandwidthOut - Default: 0
Throws:
- NVExceptions.MissingPropertyException - if the "flowId" parameter is null.
-
Flow(String flowId) - call this constructor method to use the default values of the other parameters
Parameters - flowId: the flow ID -
setCaptureClientPL(boolean captureClientPL) - sets the isCaptureClientPL Boolean value
Parameters - captureClientPL: if set to false no packets lists are captured for the flowReturns - void
-
setDefaultFlow(boolean defaultFlow) - sets the defaultFlow Boolean value Parameters - defaultFlow: set to true to use "Default Flow". Note: Not supported in MULTI_USER mode. A test can include only one "Default Flow".
Returns - void
-
setSrcIp(String srcIp) - sets the client IP (source IP). You can use either a source IP or a source IP range. If no values are provided for srcIp and srcIpRange, the source IP takes the IP of the active adapter.
Parameters - srcIp: the client IP (source IP)Returns - void
-
setDestIp(String destIp) - sets the server IP (destination IP). You can use either a destination IP or a destination IP range. If no values are provided for destIp and destIpRange, the destination IP range is set to the entire network (0.0.0.1-255.255.255.255), excluding all source IPs in the emulation (to prevent ambiguity). Parameters - destIp: the server IP (destination IP)
Returns - void
-
setSrcIpRange(Range srcIpRange) - sets the client (source) range (an instance of Range class). You can set the source IP range by passing this Range object to this method or by calling the "includeSourceIPRange" and/or "excludeSourceIPRange" methods after flow creation. You can use either a source IP or a source IP range. If no values are provided for srcIp and srcIpRange, the source IP takes the IP of the active adapter.
Parameters - srcIpRange: the client (source) rangeReturns - void
-
setDestIpRange(Range destIpRange) - sets the server (destination) range (an instance of Range class). You can set the destination IP range by passing this Range object to this method or by calling the "includeDestIPRange" and/or "excludeDestIPRange" methods after flow creation. You can use either a destination IP or a destination IP range. If no values are provided for destIp and destIpRange, the destination IP range is set to the entire network (0.0.0.1-255.255.255.255), excluding all source IPs in the emulation (to prevent ambiguity). Parameters - destIpRange: the server (destination) range
Returns - void
-
setShareBandwidth(boolean shareBandwidth) - sets the server shareBandwidth Boolean value.
Parameters - shareBandwidth: set to false to let every Source-Destination IP pair that fits this flow definition use the defined bandwidth. This enables packets to be handled without delay. (When set to true, a queue manages the packets, which may result in delayed packet handling.) Default: trueReturns - void
-
includeSourceIPRange(IPRange ipRange) - adds the specified source IP range to the srcIpRange Range object's "include" array
Parameters - ipRange: an IPRange objectReturns - void
Throws:
- NVExceptions.IllegalArgumentException - if the specified argument is not an instance of IPRange class.
-
excludeSourceIPRange(IPRange ipRange) - removes the specified source IP range from the srcIpRange Range object's "exclude" array
Parameters - ipRange: an IPRange objectReturns - void
Throws:
- NVExceptions.IllegalArgumentException - if the specified argument is not an instance of IPRange class.
- NVExceptions.NotSupportedException - if the flow is defined as "Default Flow" and the exclude range protocol and port settings are set.
-
includeDestIPRange(IPRange ipRange) - adds the specified destination IP range to the destIpRange Range object's "include" array
Parameters - ipRange: an IPRange objectReturns - void
Throws:
- NVExceptions.IllegalArgumentException - if the specified argument is not an instance of IPRange class.
-
excludeDestIPRange(IPRange ipRange) - removes the specified destination IP range from the destIpRange Range object's "exclude" array
Parameters - ipRange: an IPRange objectReturns - void
Throws:
- NVExceptions.IllegalArgumentException - if the specified argument is not an instance of IPRange class.
- NVExceptions.NotSupportedException - if the flow is defined as "Default Flow" and the exclude range protocol and port settings are set.
-
Test mode enum - represents the test mode. Possible values: Test.Mode.NTX and Test.Mode.CUSTOM.
-
Real-time update mode enum - represents the real-time update mode. Possible values: Test.RTUMode.NTX and Test.RTUMode.CUSTOM.
-
IP range protocol enum - represents the IPRange protocol. Each protocol has a corresponding ID.
public enum Protocol { ALL(0), ICMP(1), TCP(6), EGP(8), UDP(17), DDP(37), ICMPV6(58), L2TP(115); ... }
The \hpe-nv-java-samples\src\main\java\com\hpe\nv\samples folder contains both basic and advanced samples that demonstrate the NV API and show common use cases.
To help you get started, each sample has a corresponding batch file (under the \hpe-nv-java-samples\scripts folder) with suggested commands. You can run these batch files with the pre-populated commands, or you can run the samples using your own run arguments.
Note: Minimum recommended Command Prompt (cmd) window size width: 156
Some of the samples let you optionally generate a .zip file containing the NV Analytics report. You do this by specifying a .zip file path argument.
To view the list of arguments, run:
java -cp hpe-nv-java-samples-1.0.0.jar com.hpe.nv.samples.basic.<sample-class-name> --help
or
java -cp hpe-nv-java-samples-1.0.0.jar com.hpe.nv.samples.advanced.<sample-class-name> --help
Example: java -cp hpe-nv-java-samples-1.0.0.jar com.hpe.nv.samples.basic.BasicAnalyze2Scenarios --help
We suggest starting with the basic samples according to the order in the "Basic Step-by-Step Samples" section. These samples walk you step-by-step through the most basic NV methods that you can use in your automated tests. Each subsequent sample demonstrates an additional NV capability. When you finish the basic samples, you can move on to the advanced samples that demonstrate more complex NV methods.
Important notes:
- Each sample receives an --ssl argument. Make sure to pass true if you are using a secure Test Manager installation.
- If the website you are testing contains HTTPS traffic, you must use the NV proxy and install an appropriate SSL certificate, as described in http://nvhelp.saas.hpe.com/en/9.10/help/Content/Setup/Setup_environment.htm.
This sample demonstrates the use of the most basic NV methods.
First, the sample creates a TestManager object and initializes it.
The sample starts an NV test over an emulated �3G Busy� network. ("3G Busy" is one of NV's built-in network profiles. A network profile specifies the network traffic behavior, including latency, packet loss, and incoming/outgoing bandwidth. Network profiles are used to emulate traffic over real-world networks.)
Next, the sample navigates to the home page in the HPE Network Virtualization website using the Selenium WebDriver.
Finally, the sample stops the NV test.
- Create a TestManager object and initialize it.
- Start the NV test with the "3G Busy" network scenario.
- Build the Selenium WebDriver.
- Navigate to: http://www8.hp.com/us/en/software-solutions/network-virtualization/index.html
- Close and quit the Selenium WebDriver.
- Stop the NV test.
This sample demonstrates the use of the most basic NV methods.
First, the sample creates a TestManager object and initializes it.
The sample starts an NV test over an emulated �3G Busy� network.
Next, the sample navigates to the home page in the HPE Network Virtualization website using the Selenium WebDriver.
Finally, the sample stops the NV test, analyzes it, and prints the path of the analysis .zip file to the console.
- Create a TestManager object and initialize it.
- Start the NV test with the "3G Busy" network scenario.
- Build the Selenium WebDriver.
- Navigate to: http://www8.hp.com/us/en/software-solutions/network-virtualization/index.html
- Close and quit the Selenium WebDriver.
- Stop and analyze the NV test and get the result as a .zip file.
- Print the path of the .zip file to the console.
This sample demonstrates how NV helps you test your application under various network conditions.
This test starts by navigating to the home page in the HPE Network Virtualization website using the Selenium WebDriver. This initial step runs without NV emulation and provides a basis for comparison.
Next, the sample starts an NV test configured with a "3G Busy" network scenario. The same step runs as before - navigating to the home page in the HPE Network Virtualization website - but this time, it does so over an emulated "3G Busy" network as part of an NV transaction.
When the sample finishes running, it prints a summary to the console. This summary displays a comparison of the time it took to navigate to the site both with and without NV's network emulation. The results show that the slow "3G Busy" network increases the time it takes to navigate to the site, as you would expect.
- Build the Selenium WebDriver.
- Navigate to: http://www8.hp.com/us/en/software-solutions/network-virtualization/index.html
- Close and quit the Selenium WebDriver.
- Create and initialize the TestManager object.
- Set the active adapter.
- Start the NV test with the "3G Busy" network scenario.
- Connect to the transaction manager.
- Start the "Home Page" NV transaction.
- Rebuild the Selenium WebDriver.
- Navigate to the site again.
- Stop the "Home Page" NV transaction.
- Close and quit the Selenium WebDriver.
- Stop the NV test.
- Analyze the NV test and extract the network time for the NV transaction.
- Print the network time comparison summary to the console.
This sample demonstrates how to run transactions as part of an NV test.
In this sample, the NV test starts with the "3G Busy" network scenario, running three transactions (see below). After the sample stops and analyzes the NV test, it prints the analysis .zip file path to the console.
This sample runs three NV transactions:
- "Home Page" transaction: Navigates to the home page in the HPE Network Virtualization website
- "Get Started" transaction: Navigates to the Get Started Now page in the HPE Network Virtualization website
- "Overview" transaction: Navigates back to the home page in the HPE Network Virtualization website
- Create a TestManager object and initialize it.
- Start the NV test with the "3G Busy" network scenario.
- Connect the NV test to the transaction manager.
- Start the "Home Page" NV transaction.
- Build the Selenium WebDriver.
- Navigate to: http://www8.hp.com/us/en/software-solutions/network-virtualization/index.html
- Stop the "Home Page" NV transaction.
- Start the "Get Started" NV transaction.
- Click the Get Started Now button using the Selenium WebDriver.
- Stop the "Get Started" NV transaction.
- Start the "Overview" NV transaction.
- Click the Overview button using the Selenium WebDriver.
- Stop the "Overview" NV transaction.
- Close and quit the Selenium WebDriver.
- Stop and analyze the NV test and get the result as a .zip file.
- Print the path of the .zip file to the console.
This sample demonstrates a comparison between two network scenarios - "WiFi" and "3G Busy".
In this sample, the NV test starts with the "WiFi" network scenario, running three transactions (see below). Then, the sample updates the NV test's network scenario to "3G Busy" using the real-time update API and runs the same transactions again.
After the sample analyzes the NV test and extracts the transaction times from the analysis results, it prints a summary to the console. The summary displays the comparative network times for each transaction in both network scenarios.
This sample runs three identical NV transactions before and after the real-time update:
- "Home Page" transaction: Navigates to the home page in the HPE Network Virtualization website
- "Get Started" transaction: Navigates to the Get Started Now page in the HPE Network Virtualization website
- "Overview" transaction: Navigates back to the home page in the HPE Network Virtualization website
- Create and initialize the TestManager object.
- Set the active adapter.
- Start the NV test with the "WiFi" network scenario.
- Connect the NV test to the transaction manager.
- Start the "Home Page" NV transaction.
- Build the Selenium WebDriver.
- Navigate to: http://www8.hp.com/us/en/software-solutions/network-virtualization/index.html
- Stop the "Home Page" NV transaction.
- Start the "Get Started" NV transaction.
- Click the Get Started Now button using the Selenium WebDriver.
- Stop the "Get Started" NV transaction.
- Start the "Overview" NV transaction.
- Click the Overview button using the Selenium WebDriver.
- Stop the "Overview" NV transaction.
- Close and quit the Selenium WebDriver.
- Update the NV test in real time - update the network scenario to "3G Busy".
- Rerun the transactions (repeat steps 5-11).
- Stop the NV test.
- Analyze the NV test and extract the network times for the NV transactions.
- Print the network time comparison summary to the console.
This sample demonstrates all of the Test class APIs except for the real-time update API, which is demonstrated in AdvRealtimeUpdate.java. You can start the test in this sample using either the NTX or Custom modes.
- Create and initialize the TestManager object.
- Set the active adapter.
- Start the NV test with the "3G Good" network scenario.
- Connect the NV test to the transaction manager.
- Start packet list capture.
- Get packet list information and print it to the console (displayed only if the --debug argument is set to true).
- Start the "Home Page" NV transaction.
- Build the Selenium WebDriver.
- Navigate to: http://www8.hp.com/us/en/software-solutions/network-virtualization/index.html
- Get the NV test statistics.
- Print the Client-in statistics retrieved in the previous step to the console (displayed only if the --debug argument is set to true).
- Stop the "Home Page" NV transaction.
- Stop the packet list capture.
- Get packet list information and print it to the console (displayed only if the --debug argument is set to true).
- Disconnect from the transaction manager.
- Stop the NV test.
- Analyze the NV test and retrieve the result as an object or as a .zip file, if the --zip-result-file-path argument is specified.
- Print the NV transaction's network time or the path of the .zip file, if the --zip-result-file-path argument is specified.
- Download the specified packet list.
- Download the .shunra file.
- Close and quit the Selenium WebDriver.
This sample demonstrates the real-time update API. You can use this API to update the test during runtime. For example, you can update the network scenario to run several "mini tests" in a single test.
This sample starts by running an NV test with a single transaction that uses the "3G Busy" network scenario. Then the sample updates the network scenario to "3G Good" and reruns the transaction. You can update the test in real time using either the NTX or Custom real-time update modes.
- Create and initialize the TestManager object.
- Set the active adapter.
- Start the NV test with the "3G Busy" network scenario.
- Connect the NV test to the transaction manager.
- Start the "Home Page" NV transaction.
- Build the Selenium WebDriver.
- Navigate to: http://www8.hp.com/us/en/software-solutions/network-virtualization/index.html
- Stop the "Home Page" NV transaction.
- Close and quit the Selenium WebDriver.
- Update the NV test in real time - update the network scenario to "3G Good".
- Rerun the transaction (repeat steps 5-9).
- Stop the NV test.
- Analyze the NV test and retrieve the result as an object or as a .zip file, if the --zip-result-file-path argument is specified.
- Print the NV transactions' network times or the path of the .zip file, if the --zip-result-file-path argument is specified.
This sample demonstrates all of the TestManager class APIs. These APIs let you:
- initialize the TestManager object to pass logon credentials, the NV server IP, the port, and so on
- set/get the NV configuration and active adapter
- get the running tests tokens
- start/stop packet list capture
- get packet list information
- stop a specified array of tests or all of the running tests
- analyze a .shunra file, which is a compressed file that includes an events file, metadata, and packet lists
- Create and initialize the TestManager object.
- Set the active adapter.
- Get the active adapter and print its properties to the console (displayed only if the --debug argument is set to true).
- Set the NV configuration.
- Get the NV configuration and print its properties to the console (displayed only if the --debug argument is set to true).
- Start the first NV test with "Flow1" - view the sample's code to see the flow's properties.
- Connect the first NV test to the transaction manager.
- Start the second NV test with "Flow2" - view the sample's code to see the flow's properties.
- Connect the second NV test to the transaction manager.
- Get the running tests tokens and print them to the console (displayed only if the --debug argument is set to true).
- Start the "Home Page" NV transaction in the first test.
- Start the "Home Page" NV transaction in the second test.
- Start capturing all packet lists in all running tests.
- Build the Selenium WebDriver.
- Navigate to: http://www8.hp.com/us/en/software-solutions/network-virtualization/index.html
- Get packet list information and print it to the console (displayed only if the --debug argument is set to true).
- Stop capturing all packet lists in all running tests.
- Stop the "Home Page" NV transaction in the first test.
- Stop the "Home Page" NV transaction in the second test.
- Stop the first NV test using the "stopTests" TestManager class API.
- Stop all tests using the "stopAllTests" TestManager class API.
- Analyze the specified .shunra file and retrieve the result as an object or as a .zip file, if the --zip-result-file-path argument is specified.
- Print the network times of the transactions in the .shunra file, or the path of the .zip file, if the --zip-result-file-path argument is specified.
- Close and quit the Selenium WebDriver.
This sample shows how to run several tests sequentially with different network scenarios.
- Create and initialize the TestManager object.
- Set the active adapter.
- Start the first NV test with the "3G Busy" network scenario.
- Connect the first NV test to the transaction manager.
- Start the "Home Page" NV transaction in the first NV test.
- Build the Selenium WebDriver.
- Navigate to: http://www8.hp.com/us/en/software-solutions/network-virtualization/index.html
- Stop the "Home Page" NV transaction in the first NV test.
- Close and quit the Selenium WebDriver.
- Stop the first NV test.
- Analyze the first NV test and retrieve the result as an object or as a .zip file, if the --zip-result-file-path argument is specified.
- Print the NV transaction's network time or the location of the .zip file for the first test, if the --zip-result-file-path argument is specified.
- Start the second NV test with the "3G Good" network scenario.
- Connect the second NV test to the transaction manager.
- Run the same transaction in the second test (repeat steps 5-9).
- Stop the second NV test.
- Analyze the second NV test and retrieve the result as an object or as a .zip file, if the --zip-result-file-path argument is specified.
- Print the NV transaction's network time or the location of the .zip file for the second test, if the --zip-result-file-path argument is specified.
This sample shows how to run several tests concurrently with different flow definitions. When running NV tests in parallel, make sure that:
- each test is configured to use MULTI_USER mode
- the include/exclude IP ranges in the tests' flows do not overlap - this ensures data separation between the tests
- your NV Test Manager license supports multiple flows running in parallel
- Create and initialize the TestManager object.
- Set the active adapter.
- Start the first NV test with "Flow1" - view the sample's code to see the flow's properties.
- Connect the first NV test to the transaction manager.
- Start the second NV test with "Flow2" - view the sample's code to see the flow's properties.
- Connect the second NV test to the transaction manager.
- Start the "Home Page" NV transaction in the first test.
- Start the "Home Page" NV transaction in the second test.
- Build the Selenium WebDriver.
- Navigate to: http://www8.hp.com/us/en/software-solutions/network-virtualization/index.html
- Stop the "Home Page" NV transaction in the first test.
- Stop the "Home Page" NV transaction in the second test.
- Stop the first NV test.
- Stop the second NV test.
- Analyze the first NV test and retrieve the result as an object or as a .zip file, if the --zip-result-file-path argument is specified.
- Print the NV transaction's network time or the location of the .zip file for the first test, if the --zip-result-file-path argument is specified.
- Analyze the second NV test and retrieve the result as an object or as a .zip file, if the --zip-result-file-path argument is specified.
- Print the NV transaction's network time or the location of the .zip file for the second test, if the --zip-result-file-path argument is specified.
- Close and quit the Selenium WebDriver.
During a run session, the HPE Network Virtualization API Java library writes various messages to the nv.log file. This log file is stored in the current directory under the log folder (for example, \hpe-nv-java-samples\scripts\basic\log).
In addition, each sample receives a --debug argument. You can pass true to view debug messages in the console or pass false to hide the debug messages.
(c) Copyright [2016] Hewlett Packard Enterprise Development LP
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.