Activate ReadyAPI on Headless Machines and CI/CD with SLM

Important

A Floating license is required for all headless and CI/CD use. Fixed (Named) licenses cannot run Test Runners and fail silently in pipeline environments.

Running ReadyAPI on a headless machine means it runs from the Command Line. To specify the SmartBear licenses to use for the run, add certain parameters to the Command Line.

Requirements

Activating licenses in Private Networks

If you cannot configure network settings to connect to SmartBear-hosted license servers, you need to convert your online SmartBear licenses to offline licenses. Furthermore, you must activate these offline licenses within your private network. Follow these links for details:

  • Floating license - Required for headless use. The computer running tests must have access to the internal On-Premises License Servers.

  • Fixed (Offline) license - You can only activate these licenses through the GUI, and they do not support Test Runners.

Note

As outlined in About ReadyAPI Licenses and in our Terms of Use:About ReadyAPI Licenses

  • Floating licenses are required for scenarios including multiple authorized users, service accounts, and machine combinations, including virtual machines and containerized environments.

  • Floating licenses are also required for any headless use case with virtual machines and Docker.

Before you start

To use ReadyAPI headlessly, export the required license to the on-premises server using the server fingerprint file as outlined in Floating Licenses: On-Premise License Manager in the Administration documentation.

The license must be assigned to the user or service account for headless calls to succeed. See License administrator actions outlined in Get a Floating License Seat in a Private Network in the Administration documentation.

Once the license is assigned to the user account requiring headless access, you can configure your environment and run your test.

Run the headless commands

Important

You cannot use UI-based automation scripts on a headless machine.

Test Runners

Use the Get Access Key for the test user on the on-premises server. You can configure and run Functional, Performance, Security, and Virtual Service test runners through the Command Line. Use similar parameters to activate the on-premises license - use the Access Key instead of credentials:

"C:\Program Files\SmartBear\ReadyAPI-xxx\bin\testrunner.bat" -K<Access Key> ^
  -DlicenseApiHost=SLM_License_Server_Address ^
  -DlicenseApiPort=SLM_License_Server_Port ^
  "-EDefault environment" ^
  C:\Project-test.xml

Important

From ReadyAPI 3.62.0, VirtServer 3.29.0, TestEngine 1.34.0 onwards, SLM On-Prem servers version 2.0 or later do not support email/password as a license access method for test execution. The combination of email/password works only on On-Prem servers version 1.3.1 or earlier. Use access key, accessforeveryone, or client credentials (if OIDC is enabled) instead.

SLM on-premises 2.0 and later can be configured for OIDC/Okta. Once configured, client credentials can be added to the CLI command to request and install a license:

"C:\Program Files\SmartBear\ReadyAPI-xxx\bin\testrunner.bat" -ci <Client ID> -cs <Client Secret> ^
  -DlicenseApiHost=SLM_License_Server_Address ^
  -DlicenseApiPort=SLM_License_Server_Port ^
  "-EDefault environment" ^
  C:\Project-test.xml

Note

To request a license for headless calls, ensure that your username follows the email format: first.last@company.com or name@company.com. If you don't follow this format, use the Access Key as your credential.

Access for Everyone

If you enable Access for Everyone on SLM on-premises, you no longer need to add Access Key credentials to your CLI configuration for TestRunner, Performance Load Runner, Security Test Runner, and VirtRunner.

In that case, add the -D licenseApiAccessForEveryone=true flag to your CLI command.

To license SmartBear products for headless testing in private networks, take the following steps:

  1. Request and install an On-Premises Server on your headless machine.

  2. Log in with the following credentials:

    • username: anonymous.user

    • password: <cannot be left blank>

  3. Optionally set access to Access for Everyone.

  4. In the top right corner of the On-Premises License Server UI, select the > Access Key and copy the access key in the subsequent dialog.

  5. Use the access key in your command-line configuration as specified in your product's documentation.

Docker Image

You can also run Functional, Performance, Security, and Virtual Service test runners through Docker and from the Command Line.

Install Docker on your machine with Install Docker image with SoapUI TestRunner.

Put the project in the preferred folder, for example, "C:\TestDocker\Projects"

Once you have created your Ready-API-SoapUI-TestRunner Docker image, you must assign the Test or Bundle license to the test user as outlined Get a Floating License Seat in a Private Network.

Request the Get Access Key for the test user on the on-premises server. Enter the following command in the console and press Enter:

docker run -v "C:\TestDocker\Projects":/project \
  -e SLM_LICENSE_SERVER="<Address for onprem SLM license server>" \
  -e API_KEY="<API key for floating SLM>" \
  -e COMMAND_LINE="'-EDefault environment' -sTestSuite-Main -cTestCase-Main '/%project%/Project-func-test.xml'" \
  -it smartbear/ready-api-soapui-testrunner:<tag>

Docker commands can also be configured to support SLM on-premises 2.0 or later when configured for OIDC/Okta. Client Credentials Flow can be initiated using the following command:

docker run -v "/path/to/projects":/project \
  -v "/path/to/reports":/reports \
  -e COMMAND_LINE="'/%project%/REST-Sample-Project-readyapi-project.xml'" \
  -e SLM_LICENSE_SERVER="<Address for onprem SLM license server>" \
  -e CLIENT_ID="<Client ID>" \
  -e CLIENT_SECRET="<Client Secret>" \
  -it smartbear/readyapi-security-testrunner:latest

These instructions also apply for a Docker image with SoapUI TestRunner and a uienv tag.

Email/Password Credentials (SLM On-Prem)

Important

Email/password combination works only on On-Prem servers version 1.3.1 or earlier. SLM On-Prem servers version 2.0 or later do not support this authentication method. From ReadyAPI 3.62.0 and later, use access key, accessForEveryone, or client credentials if OIDC is enabled instead.

A Floating license is required for the use of ReadyAPI in virtual machines and Docker. Use of Fixed Offline licenses causes errors in the console log: Please contact your administrator to assign a floating license to Docker.

LDAP configuration (SLM On-Prem 1.3.1 or earlier only)

  • Scripts default to searching for the service account by the mail attribute instead of the sAMAccountName.

  • To search by email instead, set -Dldap.emailField=email in the vmoptions file in the /bin folder and restart the server.

Token expiry

  • The DESKTOP token expires every 4 weeks. Replace the authToken with an Access Key in the smartbear.auth file and the corresponding *.auth files in your product directory.

    For example, update these files:

    • smartbear.auth

    • TestComplete/TestComplete.auth

    • TestExecute/TestExecute.auth

Maven configuration for SmartBear ID-based licenses

  1. Provide your credentials using one of the following methods:

    • Access Key: <slmAccessKey>Access_Key</slmAccessKey>

    • Your username and password: <slmUsername>Username</slmUsername> and <slmPassword>Password</slmPassword>

  2. The server address and access settings for all users can be configured in the readyApiProperties. To enable access for everyone, set it to true.

    • <readyApiProperties>
         ...
         <property>
           <name>licenseApiAccessForEveryone</name>
           <value>true</value>
         </property>
         <property>
           <name>licenseApiHost</name>
           <value>SLM_License_Server_Address</value>
         </property>
         <property>
           <name>licenseApiPort</name>
           <value>SLM_License_Server_Port</value>
         </property>
      </readyApiProperties>
      
    • By default, the license server is included and requires no additional configuration. However, if you have installed and configured an offline (on-premises) license server for your SmartBear ID-based licenses, you need to specify the server address and port information.

See Also

Licenses in Private Networks

Publication date: