Skip to main content

Selenium Java Agent

Eva Ferreira
  • Updated

With the Selenium Java Agent, you can migrate your Java-based Selenium tests to mabl without making any change to code. The Selenium Java Agent is a JVM agent that loads at runtime and intercepts RemoteWebDriver method invocations to translate Selenium actions into mabl actions. This article explains how to import Java-based tests to mabl using the Selenium Java Agent.

  1. Obtain an API key
  2. Download the agent
  3. Run Selenium tests with the agent enabled
  4. Update the imported mabl tests

Supported Selenium versions

The Selenium Java Agent currently supports only Selenium 3.x. If you need to import tests from Selenium 4.x using the Selenium Java Agent, reach out to the mabl support team.

Other versions may work with the Selenium proxy method described in Java migration using Selenium proxy

Step 1: Obtain an API key

To run the Selenium Java Agent, you need a mabl API key:

  1. Go to the APIs page: Settings > APIs.
  2. Click on + Create API key.
  3. For Type of API key, select "Java Selenium Agent". 
  4. Give the API key a name.

Only workspace owners can create API keys.

Step 2: Download the agent

Download the mabl Selenium Agent jar file from here. Place this jar file in a location such as C:\mabl\mabl-selenium-agent.jar on Windows or ~/mabl/mabl-selenium-agent.jar on Linux/Mac.

Step 3: Run Selenium tests with the agent enabled

To migrate your Java-based Selenium tests, run your tests as you normally would but with an extra JVM argument to enable the Selenium Java Agent:

-javaagent:/path/to/mabl-selenium-agent.jar=apiKey=[your-api-key]

For example, if you execute your tests using an IDE like Eclipse, create or edit a Run Configuration and add the agent to the JVM arguments:

Run configuration image

Run configuration image

Java version 16 or newer

If your JVM is version 16 or newer, add additional VM arguments in the same location where the -javaagent argument is specified:

--add-opens java.base/java.util=ALL-UNNAMED --add-opens java.base/java.util.stream=ALL-UNNAMED

Without these arguments you will see an error similar to the following:

Caused by: java.lang.reflect.InaccessibleObjectException: Unable to make field private java.util.Spliterator java.util.stream.AbstractPipeline.sourceSpliterator accessible: module java.base does not "opens java.util.stream" to unnamed module

Agent arguments

The agent accepts a number of parameters:

Name Value Required?
apiKey mabl API key to use Yes
httpProxy Proxy to use to connect to mabl, specified as host:port No
proxyUser Username for proxy auth No
proxyPassword Password for proxy auth No
name The name to use when saving the test to mabl No

Parameters are passed as comma-delimited key-value pairs. The following is an example showing how to pass multiple arguments to the agent:

-javaagent:/path/to/mabl-selenium-agent.jar=apiKey=your-api-key,httpProxy=proxy.example.com:8080,proxyUser=myuser,proxyPass=mypassword

Expected output

After the test runs, the agent outputs a link to the imported test in the mabl app, as shown in the following example:

mabl Selenium Agent - MablAgent version 1.1.1
mabl Selenium Agent - Initializing API client...
mabl Selenium Agent - API client initialized with workspace ID {workspace-id}

{test output here}

mabl Selenium Agent - Imported test 1 with 7 steps
mabl Selenium Agent - Captured 1 test(s)
mabl Selenium Agent - Saving test...
mabl Selenium Agent - https://app.mabl.com/workspaces/{workspace-id}/train/journeys/{test-id}

Step 4: Update the imported mabl tests

The following Selenium actions are not migrated during the import session:

  • Assertions
  • Variables
  • File downloads
  • File uploads
  • Drag and drop actions
  • Conditional logic
  • Loop logic
  • Steps that interact with elements in an iframe
  • Hover actions
  • Cookies

To set your migrated tests up for success, we strongly recommend taking the following next steps:

Add missing steps

Edit the test in the mabl Trainer. Add in missing steps that were not migrated.

Use flows for common step sequences

If you imported multiple Selenium tests, save common sequences of steps as flows and import into other migrated tests to minimize the refactoring effort.

Related articles