This section describes how to run Selenic from the command line so that you can automate Selenic as part of your continuous test execution process. In this section:
Introduction
Parasoft Selenic is implemented as two .jar files. Run the selenic_agent.jar file first as part of your continuous test execution process to capture information about the test execution. Next, run the selenic_analyzer.jar file to analyze the data captured by the agent.
The analyzer will generate recommendations based on what Selenic has learned about your tests and application. You can review the report and manually apply the recommendations, or enable the self-healing feature so that the Selenic agent automatically applies recommendations and/or heals wait conditions during successive test executions. This enables automated UI testing activities to continue without affecting downstream processes.
If you are using the Selenic IDE plug-in, both processes (capturing test execution behavior and analyzing the data) are performed under a single action. The following video provides an overview of how to use Selenic on the command line.
Capturing Test Execution Data
Specify and configure the selenic_agent.jar file using the -javaagent JVM argument when executing your tests to teach Selenic your test logic. The captureDom option must be enabled to capture test execution data. At least one successful test execution is required for Selenic to provide recommendations. The following example demonstrates how the Selenic agent may be run using the Java executable:
java -javaagent:/path/to/selenic_agent.jar=captureDom=true -cp /path/to/junit.jar;/path/to/folder/containing/test/classes junit.textui.TestRunner com.mypackage.MyTestClass
The command line examples in this documentation use Maven commands:
mvn test -DargLine=-javaagent:/path/to/selenic_agent.jar=captureDom=true
You can leverage additional Selenic functionality by configuring the Java agent argument using the following format:
mvn test -DargLine=-javaagent:/path/to/selenic_agent.jar=arg1=value1,arg2=value2
See Selenic Agent Options for details.
Selenic will save the test execution data to the <USER_HOME>/parasoft/recorded_data directory. Run the Selenic analyzer to analyze the data and create recommendations for updating any bad locators.
Test execution results will be saved to the <PROJECT>/target/surefire-report directory.
Example Commands
The following examples show how to use the available Selenic Agent Options.
Capture DOM and Take Screenshots During Execution
mvn test -DargLine=-javaagent:/Applications/parasoft_selenic/selenic_agent.jar=captureDom=true,screenshot=failures
Create API Tests and Self-heal Bad Locators and Wait Conditions
In this example, the main selfHealing option is enabled, which enables Selenic to apply default self-healing functionality to locators and wait conditions. The test must have been executed successfully at least once with the Selenic Java agent to automatically heal bad locators. There are no prerequisites for healing wait conditions.
The createApiTests option has the following prerequisites:
- A SOAtest server must be running
- The Parasoft Web Proxy must be running
mvn test -DargLine=-javaagent:/Applications/parasoft_selenic/selenic_agent.jar=createApiTests=true,proxyPort=40090,soatestHost=localhost,soatestPort=9080,username=admin,password=admin,selfHealing=true
The API Tests will be created in the SOAtest server's workspace.
Executing Tests Affected by Change
You can leverage Selenic's test impact analysis functionality to determine which tests are affected by changes to the application under test. See Test Impact Analysis for details about using this functionality.
Generating Recommendations
Run the selenic_analyzer.jar file to generate recommendations after you have executed your tests with Selenic. The analyzer will analyze the data in the <USER_HOME>/parasoft/recorded_data directory and generate recommendations for failed locators. The report Selenic produces will also contain recommendations for wait conditions if self-healing for wait conditions was enabled. If the -allLocators option is used, then recommendations will be generated for all passed and failed locators.
java -jar /path/to/selenic_analyzer.jar
You can specify additional arguments to customize how Selenic outputs the results of its analysis. See Selenic Analyzer Arguments for information about all available arguments.
java -jar /path/to/selenic_analyzer.jar -<arg> <arg_value>
Selenic Agent Options
You can specify the following options during test execution with Selenic.
captureDom
This option enables Selenic to capture the DOM when Selenium attempts to locate an element. This option is required for Selenic to automatically heal bad locators and/or generate recommendations for locators.
Default is false
collectCoverage
This option enables Selenic to collect coverage data for test impact analysis during test execution. Refer to Test Impact Analysis for details.
Default is false
coverageAgentHost
This option specifies the host where the AUT and coverage agent are running so that coverage data can be captured for test impact analysis during test execution. Refer to Test Impact Analysis for details.
Default is localhost
coverageAgentPort
This option specifies the port where the AUT and coverage agent are running so that coverage data can be captured for test impact analysis during test execution. Refer to Test Impact Analysis for details.
Default is 8050
coverageAgentUserID
This option specifies a user ID so that different users can be distinguished when collecting coverage in multi-session mode. Refer to Test Impact Analysis for details.
coverageDir
This option specifies a local directory for coverage data to be downloaded from the AUT server for test impact analysis during test execution. Refer to Test Impact Analysis for details.
createApiTests
This option enables Selenic to create API tests using Parasoft SOAtest during UI test execution.
Default is false
data
This option specifies the location of the data recorded during test execution. The -data option for the Selenic analyzer should be configured to match the value configured for this option.
Default is <USER>/parasoft/recorded_data
proxyPort
If you are creating API tests during UI test execution, specify the port number for the SOAtest Web Proxy.
Refer to the Parasoft Recorder documentation for additional information.
Default is 40090
soatestHost
If you are creating API tests during UI test execution, specify the host where the SOAtest server is running.
Refer to the Parasoft Recorder documentation for additional information.
Default is localhost
soatestPort
If you are creating API tests during UI test execution, specify the port number for the SOAtest Server.
Refer to the Parasoft Recorder documentation for additional information.
Default is 9080
secure
If you are creating API tests during UI test execution, this option enables Selenic to communicate with the SOAtest server over HTTPS.
Default is false
username
If you are creating API tests during UI test execution and user authentication is enabled for SOAtest server, this option specifies the user name for logging into the server.
password
If you are creating API tests during UI test execution and user authentication is enabled for SOAtest server, this option specifies the password for logging into the server.
maxSessionDaysToAnalyze
This option indicates how many days worth of test sessions to include when applying the selfHealLocators option during execution. By default, there is no limit, so Selenic will analyze all available recorded data.
In the following example, the Selenic agent will use 12 days worth of recorded data to determine the best option for automatically healing a failed locator or wait condition.
maxSessionDaysToAnalyze=12
The number of days refers to the most recent days for which data was recorded, regardless of how many calendar days have passed.
maxSessionDaysToKeep
This option indicates how many days worth of test session data to keep on disk. By default, no limit will be set and Selenic will continue to store recorded data until it is manually removed.
In the following example, the Selenic agent will keep 12 days worth of recorded data on disk:
maxSessionDaysToKeep=12
The specified value refers to days for which data was recorded and not the number calendar days.
screenshot
This option enables the test machine to take a screenshot for any WebDriver commands Selenic logs.
You can set one of the following values:
all- A screenshot for eachfind elementcall in the Selenium test is capturedfailures- Only screenshots for failingfind elementcalls are capturednone- No screenshots are captured
Default is none
selfHealing
This option enables self-healing functionality. When set to true, the selfHealLocators and selfHealWaitConditions options are enabled.
Default is false
selfHealLocators
This option enables Selenic to automatically attempt to update a locator at runtime based on historical information collected during test execution.
Default is true when selfHealing is enabled.
selfHealWaitConditions
This option enables Selenic to extend Selenium wait conditions to prevent timeouts or other types of errors due to insufficient wait conditions during test execution.
Default is true when selfHealing is enabled.
additionalWaitTimePercent
This option specifies how much additional time a wait condition should be extended to prevent a timeout or other errors related to insufficient wait conditions during test execution. The value specified with this option is a percentage of the original wait condition. Selenic will calculate the additional time based on the percentage and extend the Selenium tests' wait conditions. In the following example, a wait condition originally configured for 4 seconds will be extended by 50% to 6 seconds.
additionalWaitTimePercent=50
Default is 50 when selfHealing and selfHealWaitConditions are enabled.
minAdditionalWaitTime
This option specifies a minimum number of seconds by which original wait conditions will be extended to prevent a timeout or other errors related to insufficient wait conditions during test execution. The value for this option overrides the value dynamically set with the additionalWaitTimePercent option if the resulting percentage is less than the minimum.
Default is true when selfHealing and selfHealWaitConditions are enabled.
sessionId
This option specifies an identifier for test execution data. This setting is optional and should only be used when running tests across multiple projects so that Selenium data from all projects can be grouped under a single session. Otherwise, Selenium data for each project will be recorded under separate session IDs. As a result, the analyzer will need to run for each test execution in a project before you can run tests in a different project.
Example:
mvn test -DargLine=-javaagent:/path/to/selenic_agent.jar=captureDom=true,sessionId=ID_1
When analyzing the data, use the -sessionId option when calling the selenic_analyzer.jar file to reference the ID set during test execution. For example:
java -jar /path/to/selenic_analyzer.jar -sessionId ID_1
By default, a date and time stamp is used.
Selenic stores execution data in the directory specified with the data property. Each subdirectory within the recorded data directory contains execution data for individual sessions. The subdirectories are named with the sessionId value. If the sessionId parameter is not configured, Selenic will store the data in a subdirectory identified with a timestamp by default.
If you do not specify a session ID, then you must run the analyzer each time you run tests in a project before running tests in a different project. A session ID should be different for each test run so that results from an earlier test run to do get combined with later test runs. Therefore, using a build identifier or the default timestamp is recommended.
Selenic Analyzer Arguments
The following options are supported.
-allLocators
Use this option to get locator recommendations for all actions in Selenium tests. By default, Selenic only provides locator recommendations for failed locators. Recommendations for locators that succeeded will only be visible in the JSON report and not in the HTML report.
-report <value>
This option specifies the location and name of the report file to be generated.
Absolute paths to a directory/file are supported.
Examples:
java -jar /Users/tester/parasoft_selenic/selenic_analyzer.jar -report /home/reports
java -jar /Users/tester/parasoft_selenic/selenic_analyzer.jar -report "C:\reports\my-report.html"
The following location is used by default:
"{WORKING_DIR}/report.html"
-settings <location_of_properties_file>
Use this option to specify a .properties configuration file containing the execution options for the selenic_analyzer.jar. The .properties file contains licensing and reporting configurations that can be implemented during Selenic analysis. Refer to the following sections for additional information:
-encodepass <password>
Use this option to print an encoded password that you can use in the selenic.properties file. See Licensing.
An encoded string will be printed to the console in the following example that can be used in place of myPassword:
java -jar /Users/tester/parasoft_selenic/selenic_analyzer.jar -encodepass myPassword
-publish
Use this option to publish test results to your project in DTP. The DTP connection and project settings must be configured (see Reporting Results to DTP).
-data
This option specifies the location of the recorded data. It should be configured to match the location specified with the data option when running the Selenic agent.
Default is <USER>/parasoft/recorded_data
-maxSessionDaysToAnalyze
This option indicates how many days worth of test sessions to include when analyzing recorded data to generate recommendations. By default, there is no limit, so Selenic will analyze all available recorded data.
In the following example, the Selenic analyzer will use 12 days worth of recorded data to generate locator or wait condition recommendations.
java -jar /Users/tester/parasoft_selenic/selenic_analyzer.jar -maxSessionDaysToAnalyze 12
The number of days refers to the most recent days for which data was recorded, regardless of how many calendar days have passed.
-help
This option prints the list of supported arguments to the console.
-sessionId <value>
This option enables you to specify the ID of the test session that contains the recorded data to process. If not specified, the data from the last recorded session is used.
-surefire
This option enables you to specify the location of the Surefire XML report. The Surefire XML report is created when running tests in Maven and is used to create the HTML report.
Absolute paths to a directory/file are supported.
The following wildcards are also supported:
** - Use two asterisks to match directories.
* - Use a single asterisk to match file names.
Examples:
-surefire "/home/folder"
-surefire "C:\folder\file.xml"
In the following example, Selenic will find XML files in /folder1/folder2/folder3, /folder2/folder3, and /folder3:
-surefire "**/folder3"
In the following example, Selenic will find all XML files prefixed with "ProjectA" in folder3:
-surefire "**/folder3/ProjectA*.xml"
The following location is used by default:
"**/target/surefire-reports/"
