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. It captures a rich recording of the Selenium session and hands the recording off to mabl’s cloud test authoring agent, which authors the corresponding mabl test asynchronously.

Supported Selenium versions

The Selenium Java Agent supports Selenium 4.x and the following Long-Term Support (LTS) Java versions: 11, 17, and 21. If your project requires Java 25+, please reach out to your customer success manager or submit a request in the mabl Product Portal.

Older versions may also work with the Selenium proxy method described in migrating from Selenium.

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: Add application, environment, and credentials to mabl

Before running the import, make sure you have added the application, environment, and target URL to your mabl workspace. If your test uses credentials, add those credentials to mabl.

When you run the import, the mabl agent uses the URLs and credentials from the recording to pick the matching entities in your mabl workspace.

Step 3: Download the agent

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

Step 4: 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]

To bind the test to a set of credentials in mabl, include the credentialsId argument:

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

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

InaccessibleObjectException at startup

If you see an error similar to the following when the agent starts up:

Caused by: java.lang.reflect.InaccessibleObjectException: Unable to ...

your JVM is using strict module access. Add the following additional VM arguments in the same location where the -javaagent argument is specified to grant the agent the reflective access it needs:

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

Most JVMs no longer require these arguments by default, so only add them if you actually see the InaccessibleObjectException.

Agent arguments

The agent accepts a number of parameters:

Name Value Required?
apiKey mabl API key to use Yes
name The name to use when saving the test to mabl. If omitted, mabl generates a descriptive name from the captured session. No
plan Whether to run the captured session through the test planning agent before authoring. Defaults to true. Set to false to submit the captured session directly to the test authoring agent (faster, but with less workspace context). No
saveOnFailure By default, if the test framework reports a failure, the captured session is not submitted to mabl. A failing run is rarely the test you want to import. Set to true to submit failing sessions anyway. Defaults to false. No
captureAssertions Whether to capture assert* and fail calls from JUnit 4, JUnit 5, TestNG, and Hamcrest as hints to the test authoring agent. Defaults to true. No
useLink Bias the planner toward applications and environments configured for the mabl Link Agent. Defaults to false. Set to true when the application under test requires Link Agent connectivity even if that isn’t obvious from the recording. No
credentialsId Workspace credential ID to bind to the imported test. Use this when your captured login pulls secrets from a vault or environment-specific config that doesn’t match any mabl credential. Without it, the planner has no signal for which credential to pick. No
save Whether to submit the captured session to mabl. Defaults to true. Set to false to print the captured session JSON to the log without submitting. Useful for inspecting what the agent captured. No
debug Enable verbose agent logging. Defaults to false. No
config Path or https:// URL to a Java .properties file containing any of the keys above. Values supplied as agent arguments take precedence over values in the file. Useful for keeping apiKey out of argLine. No
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

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],name=CheckoutHappyPath,useLink=true

Expected output

After the test runs, the agent submits each captured session to the mabl cloud test authoring agent and outputs a link to the running authoring session. From there you can watch the test get authored in real time; the finished test appears in your workspace when authoring completes.

mabl Selenium Agent - MablAgent version 2.0.0
mabl Selenium Agent - Initializing API client...
mabl Selenium Agent - API client initialized with workspace ID {workspace-id}
{test output here}
mabl Selenium Agent - Captured 1 session(s)
mabl Selenium Agent - Submitting session to mabl for test generation...
mabl Selenium Agent - Test authoring session initiated: session={session-id} instance={instance-id}
mabl Selenium Agent - https://app.mabl.com/workspaces/{workspace-id}/agents/tasks/{session-id}

Import is asynchronous: the agent returns as soon as the cloud authoring session has been initiated and does not block waiting for the test to be authored.

Step 5: Review the imported mabl test

The cloud test authoring agent authors a complete mabl test from your captured Selenium session, including assertions (when captureAssertions is on), variables, and waits. We still recommend reviewing the test after authoring completes:

Verify the application and environment

Make sure the test chose the correct application, environment, and, if using, credentials, in mabl. If the captured run started on a third-party identity provider page, or visited multiple hosts, double-check that the test is bound to the right application/environment in mabl.

Add anything that wasn’t visible in the recording

A few things are inherently invisible to the agent and may need to be added manually after authoring:

  • File downloads and uploads
  • Drag and drop actions
  • Hover actions
  • Steps that interact with elements inside an iframe
  • Cookie inspection

Edit the test in the mabl Trainer to add any of these that your test needs.

Use flows for common step sequences

If you’re importing multiple Selenium tests with common sequences of steps, you can add flows to minimize overall refactoring:

  1. Import an initial subset of tests with common sequences of steps
  2. Manually edit and convert those common steps into reusable flows
  3. Import the rest of the tests. Subsequent imports will be able to use the flows you just created.

Related articles