Automation Script

Applies to ReadyAPI 3.53, last modified on June 26, 2024

When you get an access token, ReadyAPI shows you the login, consent, and other screens. Each screen is basically a web page that you interact with to grant permissions on behalf of the resource owner. In ReadyAPI you can create automation scripts to simulate the needed actions and grant permissions in unattended mode.

How to create automation scripts

You create automation scripts in the Automation editor that you can open either in the Auth Manager or in the Auth panel:

  1. Open Auth Manager.

  2. Select the OAuth 2.0 authorization profile for which you want to enable automation.

  3. Open the Automation scripts.

Auth manager

Click the image to enlarge it.

  1. Open a request.

  2. Open the Auth panel.

  3. Select the OAuth 2.0 profile and click Get Access Token.

  4. Click Automation:

Auth panel

Click the image to enlarge it.

In general, creating automation scripts consists of the following steps:

1. Inspect a web page (a screen).

2. Create an automation script to emulate user actions on this page.

3. Repeat these steps for all the pages involved in the process.

Inspect web pages

By using a developer mode in any external browser, you need to inspect web pages involved in the authorization process and find objects to interact with:

OAuth 2.0 Automation: Inspecting a web page

Click the image to enlarge it.

Create automation scripts

Then, in the Automation editor, you specify JavaScript commands that simulate actions required for granting permission: enters the login and password, clicks the needed buttons, and so on. For example, to simulate getting an access token from the authorization page shown above, you can use the following commands:


document.getElementById("tbUserName").value = "john.smith";
document.getElementById("tbPassword").value = "p@ssw0rd";

How automation works

During the authorization process, the screens are shown in a particular order. For each screen, you create a separate script in the Automation editor. When you get an access token, ReadyAPI shows the screens in the internal browser and runs scripts one by one. The URL change is a signal for ReadyAPI to run the next script. For example, after entering valid credentials, the authorization server shows the second page, on which it asks you whether you grant permission to the client application. The automation script in this case may look like this:

OAuth 2.0 Automation: Sample automation script

Click the image to enlarge it.

Background redirects may cause the run of the next script, while the page is not in fact changed. Besides that, an authorization server may change the authorization process by adding or skipping pages. For example, when you get an access token for the first time, it asks you to log in, while next time it remembers your account and asks only for a permission. So we recommend that you add the logic to your script that ensures that the script runs on the proper page since ReadyAPI does not detect which page is currently shown.

Automation samples

Follow these links to see the examples of how to configure automation:

Forced token update

By default, ReadyAPI requests a new token only when the old one expires. You can also use scripts to force ReadyAPI to update the token whether it is expired or not.

To do this, you can use the requestAccessCode method of the OltuOAuth2ClientFacade class that assigns a new access token to the specified authorization profile. See the following script as an example:


// Import the required classes

// Get a project
def project = ModelSupport.getModelItemProject(context.getModelItem());

// Get the needed authorization profile
def authProfile = project.getAuthRepository().getEntry("Ora Bannet");

//Create a facade object
def tokenType = TokenType.ACCESS;
def oAuthFacade = new OltuOAuth2ClientFacade(tokenType);

// Request an access token in headless mode and assign it to the authorization profile we got earlier
oAuthFacade.requestAccessToken(authProfile, true, true);

// Access token retrieval may take time, so we need to pause the execution for 3 seconds to finish it. You may increase this value if needed.

// Posts a new token to the script log"Set new token: " + authProfile.getAccessToken());

If you are using OAuth 2.0 Azure authorization, replace the OltuOAuth2ClientFacade class in the script with the OltuOAuth2AzureClientFacade class.

On headless machines where the browser window is inaccessible, you can use the same approach as described above. However, there are some things you must do first:

  1. Install and run any X Server.

  2. Specify the display number for your X Server (see the documentation of your X Server).

  3. Open the file in a text editor and add the following line:

    export DISPLAY=<ip>:<index>


    The IP address of the X Server.


    The display number you have specified.

Retrieval process exceeds timeout

The default timeout for accessing a new access token is 5 seconds. Usually, it is enough to get a new access token. If your retrieval process takes more time, the automation fails, and the ReadyAPI log contains the following messages:

WARN: OAuth2 access token retrieval timed out after 2000 ms.
ERROR: Exception in request: java.lang.RuntimeException: Unable to refresh expired access token.

To increase the timeout, use the oauth2.access.token.retrieval.timeout JVM option. See Modifying JVM Settings to learn how to do it.

Note: We have optimized the authentication algorithm of automated scripts by extending the default time from 5000ms to 20000ms. Additionally, we added 5-second intervals to monitor authorization progress, enhancing the user experience and execution times of automated authorization.

Browser Error

The browser will display all the errors returned by the authorization server.

Sample Browser Error: Google

Click the image to enlarge it.

Validation Error

If some script cannot be validated for some reason, you will get an error message.

Note: The error message is just an assumption. The error may be elsewhere.
Validation Error

Click the image to enlarge it.

See Also

OAuth 2.0 and OAuth 2.0 (Azure)

Highlight search results