Activate ReadyAPI on Headless Machines and CI/CD build runs with SLM

Applies to ReadyAPI 3.52, last modified on April 18, 2024

This page is related to the new SmartBear ID-based licenses that we’ve introduced in ReadyAPI 3.8.1.
In this version, we included support for SmartBear-hosted ID-based (online) licenses. Furthermore, in version 3.40.0, we added support for on-premise hosted and offline ID-based licenses.

About

Running ReadyAPI on a headless machine means that it works from the command line. The same happens when you run ReadyAPI and its test runners from a CI/CD build.

To specify the SmartBear licenses to be used for the run, you add certain parameters to the command line. See below for details.

ReadyAPI licenses to which this info applies

Here, we have explained the use of SLM licenses in Private Networks.

Customers installing and activating a license through the ReadyAPI User Interface can use offline fixed licenses or floating licenses.

Customers planning to run tests headlessly need to add licensing credentials to the command line. To use this, you will need a floating license. Offline fixed licenses do not work with test runners.

Requirements

Activating licenses in Private Networks

If you are unable to 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 - To run tests headlessly, you need a floating license. Also, add license credentials to the command line.

    Floating licenses require downloading and installing a special On-Premise License Server.

    The computer where you are going to run tests must have access to the internal (on-prem) License Servers.

  • Fixed License - Offline (fixed) licenses can only be activated through the GUI and do not work with Test Runners.

Please note, as outlined here and in our Terms of Use:

Floating licenses are required for scenarios including multiple authorized users, service accounts, and machine combinations including virtual machines and containerized environments. Floating licenses are required for any headless use case with virtual machines and docker.

Before you commence to use ReadyAPI in Headless mode

In order to use ReadyAPI headlessly, you need to export the required license to the on-prem server using the server fingerprint file as outlined here.

You must then assign the correct license to the required user or service account for headless calls to be successful. See License Administrators actions outlined here.

Once the license has been assigned to the user account requiring headless access, you can configure your headless commands and implement your test.

Configure and Run the Headless Commands

You cannot use UI based automation scripts on headless machine.

Functional, Performance, Security, and Virtual Service testrunners

We recommend you to use the Get Access Key for the Test User on the on-prem server. You can configure and run Functional, Performance, Security, and Virtual Service testrunners through Command Line. Use the similar parameters to activate the on-prem license, this time adding 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

Alternatively, once the correct license is assigned to the Test User, you can configure and run Functional, Performance, Security, and Virtual Service testrunners through Command Line. Use the similar parameters to activate the on-prem license:

"C:\Program Files\SmartBear\ReadyAPI-xxx\bin\testrunner.bat" [email protected] -V<password> -DlicenseApiHost=SLM_License_Server_Address -DlicenseApiPort=SLM_License_Server_Port "-EDefault environment" C:\Project-test.xml
Note: To request a license for headless calls, please ensure that your username follows the email format: [email protected] or [email protected]. If you don't follow this format, we suggest using the Access Key as your credential.

Using access for everyone with Headless Testing in Private Networks

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

In that case, you can 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 On-Premise Server on your headless machine.
  2. Log in with the following credentials:
    • username: anonymous.user
    • password: <any, but cannot be left blank>
  3. Optionally set access to Access for Everyone.
  4. In the top right corner of the On-Premise License Server UI, select > 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 testrunners via Docker and with Command Line.

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

Put the project in the preferred folder e.g., "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 here .

Request the Get Access Key for the Test User on the on-prem 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>

These instructions also with Docker image with SoapUI TestRunner with uienv tag.

Note:

  • A floating license is required for use of ReadyAPI on Virtual Machines and Docker. Use of Fixed Offline licenses will cause errors in the console log: “Please contact your administrator to assign a floating license to Docker”.

  • When using email and password credentials with the testrunner.sh and testrunner.bat scripts, they default to search for the service account via the "mail" attribute instead of the standard "sAMAccountName." This means users can successfully log in with the Service Account through the Web UI but not with the testrunner.

  • Customers using LDAP might find that email addresses in Active Directory are stored under the "email" attribute rather than the "mail" attribute.

  • You can configure SLM On-prem to search for the email field by setting -Dldap.emailField=email in the vmoptions file located in the /bin folder of the installation directory. After changing the configuration, the server needs to be restarted. TestRunner sends email/password requests, which are matched to the field configured by -Dldap.emailField (default is 'mail'). This configuration is supported in version 1.3 of SLM On-prem.

  • On the on-prem server, the DESKTOP token expires after 4 weeks, regardless of usage. To ensure uninterrupted work, replace the value of the authToken (i.e., "DESKTOP" token) with an Access Key. Additionally, update the authToken in both the smarbear.auth and *.auth files found in product directory you are using.

    For instance, update smarbear.auth, TestComplete/TestComplete.auth, and TestExecute/TestExecute.auth files accordingly.

Maven configuration for SmartBear ID Based Licensing

  1. You may provide your credentials by either enclosing them within the <slmAccessKey>Access_Key</slmAccessKey> tag, or by using the <slmUsername>Username</slmUsername> and <slmPassword>Password</slmPassword> tags.

  2. The server address and access settings for all users can be defined 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 SmartBear license server is included and does not require additional configuration. However, if you have installed and configured an offline (on-premise) license server for your ID-based licenses, you need to specify the server address and port information.

See Also

ReadyAPI – Licensing in Private Networks

Highlight search results