ReadyAPI Plugin for Opentext ALM

SmartBear ReadyAPI (opens in a new tab) is one of the most popular commerical applications for testing API interfaces. Dragonfly ReadyAPI plugin is a native plugin that seamlessly integrates into ReadyAPI using ReadyAPI extensions framework and exposes context menus and workflows for integrating ReadyAPI with HP / Opentext ALM. Using Dragonfly, users can export tests and testrun results from ReadyAPI ALM automatically by simple configurations and without writing any code.

The ReadyAPI Plugin provides the following capabilities

Project : Import and Export Projects
Tests: Import and Export ReadyAPI tests to ALM
Test Mapping: Map existing ALM tests to ReadyAPI tests
Custom Fields : Configure ALM custom fields
Automation : Automatically create Tests, Test Plans, Test Labs, Runs, etc.

Installation

ReadyAPI 3.0 or higher

Download (opens in a new tab) the latest version of the Dragonfly ReadyAPI plugin and use the installer's easy to follow instructions.

Install ALM Connectivity Addin

Dragonfly communicates with ALM using the ALM connectivity interfaces. Install ALM Connectivity Add-in from https://<your alm severl>/qcbin/addins.html

Location

Smartbear plugins are typically installed under user.home\.soapui\plugins directory. Example: C:\Users\agiletestware\.soapui\plugins

Dragonfly installer will automatically detect user.home\.soapui and copy the installation files to user.home\.soapui\plugins and user.home\dragonfly folders.

License

The Dragonfly license is specified during the installation process. You can also updated the license by placing the new license file in %USERPROFILE%\dragonfly folder.

update license

ALM Permissions

Dragonfly plugin creates tests and uploads test results in ALM's TestPlan and TestLab. As such, the user needs to have appropriate permission in ALM.

TestPlan Permissions

Create TestPlan folder
Create Tests in TestPlan
Create, Update, Delete Design Steps in the testcase

tesplan permissions

TestLab Permissions

Create, Update, Delete Result
Create, Update, Delete Run
Create, Update, Delete Run Step
Create, Update Test Instance
Create, Update Test Set
Create, Update TestLab folder

testlab permissions

Project Configuration

Dragonfly plugin configurations are stored in ReadyAPI project as project level fields. This allows users to configure each ReadyAPI independently of other ReadyAPI projects.

Initialize

To start using Dragonfly plugin, first initialize the ReadyAPI project. This will inject ALM specific properties at the Project, Suite, and Test Levels.

Select the Dragonfly: (Un)Initialize project project menu. This will adds all required custom properties to your project, test suites and test cases. To remove these fields from the project, use Dragonfly: (Un)Initialize project

project configuration

The highlighted properties below are required and must be configured to reflect your ALM environment settings.

Field Configuration

ALM users often have countless custom fields for project entities such as Test, TestSets, and Test Runs etc to capture additional data. Dragonfly ReadyAPI plugin provides a convienent wizard for configuring these ALM fields.

⚠️

If an ALM project has required fields and the ReadyAPI project has not mapped these fields, Dragonfly will emit useful warning message in the Dragonfly log tab.

To configure ALM custom fields, select the Dragonfly: Configure Custom Fields project menu to start the configuration wizard. The wizard allows you to configure Test, TestSet and Run entities. Specify the ALM Field Name, Label, and default values.

custom fields wizard

custom fields save

The specified default values will be added to the ReadyAPI project in the following places

Test: ReadyAPI TestCase custom property
Testset: ReadyAPI project and test suite custom property
Run: ReadyAPI TestCase custom property

Test Example: testcase example

Copy Config

ReadyAPI users may have multiple projects that share the same field configuration. Dragonfly provides a convienent way to copy field configuration across projects.

Open the configuration wizard Dragonfly: Configure Custom Fields and select Copy from project

copy configuration

Select the source project whose configuraiton needs to be copied

copy configuration

Export Config

Field configuration can be exported to some file or imported into a project. This can be useful for sharing configuration with other members or checking them in source control.

Export Configuration:

Select the Dragonfly: Configure Custom Fields project menu
Select Menu → Export
Type in file name to which configuration should be stored and click Open

Import configuration:

Select the Dragonfly: Configure Custom Fields project menu
Select Menu → Import
Type in file name from which configuration should be read and click Open
Click Save button

Project properties

These properties allow you to specify ALM connection details and control the test and results export behavior.

Some properties like QC_TestPlanDirectory, QC_TestLabDirectory, QC_TestSet can also be configured at the testsuite level. If specified at the testsuite level, the testsuite value will take precedence over project values. Specifying these values at the test suite is very useful when users want to map each test suite to a different testplan, testlab, testset.

The prefix QC is for historical reasons and refers to orginal name of ALM: Quality Center (QC)

Dragonfly will automatically create TestPlan, TestLab, and TestSet if the specified value does not exist.

Name	Description	Example	Required
QC_URL	ALM URL	`https://<server>:8080/qcbin`	Yes
QC_Domain	ALM domain	default	Yes
QC_Project	ALM project	demo-project	Yes
QC_user	ALM user. The user must have the following permissions: `add tests`, `add/delete design steps`, `add test plan`, , `add testset`, `add/delete runs`,	`jsmith`	Yes
QC_password	ALM password		Yes
QC_TestPlanDirectory	ALM Test Plan path	`Subject\testplan01`	Yes
QC_TestLabDirectory	ALM Test Lab path	`Root\testlab01`	Yes
QC_TestSet	ALM Testset value	`myTestSet01`	Yes
QC_soapUI_ARGS	Dragonfly can be invoked via ReadyAPI testrunner.bat CLI as part of the CICD workflows by specifying arguments	`"-j" "-fC:\Reports"`	No
QC_BulkUpdate	Enabling bulk update will update ALM at the end of the ReadyAPI instead of at the end of each test. This can help improve the overall performance.	`enabled` `disabled`	No
QC_RunName	Overrides default run name. Default format is `Run: [time stamp] syncing complete`	`release-1.6-run`	No
QC_ProjectPath	If running ReadyAPI tests via HP ALM, carefully specify this value. By default, when tests are exported to HP ALM, Dragonfly takes the user's local ReadyAPI project location and dynamically creates VBS script in HP ALM test case. In ALM, tests can run on a variety of hosts. The user should make sure that all the hosts have the ReadyAPI project in the specified location. We recommend that user's use git to synchronize the code on ALM hosts.	`C:\ReadyAPI-projects\\`	No
QC_soapUIPath	When running ReadyAPI tests via HP testlab, dragonfly uses ReadyAPI's `testrunner.bat` and default to the user's ReadyAPI location. If the ALM nodes don't have ReadyAPI installed in the same location as the exporting user, you should specify the path to testrunner.bat	`D:\ReadyAPI\bin\testrunner.bat`	No
QC_Export_Disabled_Tests	If enabled, all tests (disabled + enabled) will be exported to ALM testset.	`enabled` `disabled`	No
QC_Dragonfly_Plugin	Enables or disables the Dragonfly plugin. Useful when you don't want tests to be automatically exported while running.	`enabled` `disabled`	No
QC_Override_Test_Runs	If enabled, removes all previous test runs in HP ALM so test has only one run.	`enabled` `disabled`	No

ALM Credentials

Dragonfly stores your ALM username and encrypted password in the ReadyAPI project file. This may not be ideal as projects need to checked into source control to be shared across team members and each time you will need to replace with your own ALM username/password.

Dragonfly provides a way of specifying ALM username and password outside of the project. If configured, Dragonfly will read the username and password value from the system and ignore any username/password values in the ReadyAPI project.

Navigate to the .dragonfly folder inside the userprofile directory and run java -jar dragonfly.bat login [username] [password]. This will create a user-setting.xml file containing your username and encrypted password. Once created, all Dragonfly actions will use these username/password values to connect to ALM.

navigate

credentials

Import / Export Project

Export Project

Dragonfly will automatically create QC_TestPlanDirectory, QC_TestLabDirectory, or QC_TestSet if they are not found in ALM

⚠️

Dragonfly: Export to HP ALM project menu always deletes the existing design steps in ALM test case and re-creates ReadyAPI's testcase steps. This is done to ensure that the ReadyAPI tests are in sync with HP ALM testcase.

Export to HP ALM action will DELETE ALL design steps in HP ALM" Dragonfly: Export to HP ALM project menu always deletes the existing design steps in ALM test case and re-creates ReadyAPI's testcase steps. This is done to ensure that the ReadyAPI tests are in sync with HP ALM testcase.

The typical usecase for Dragonfly is to export the ReadyAPI project to ALM and then run tests in ReadyAPI to capture results in ALM. To export, select the Dragonfly: Export to HP ALM project menu

project export

Export to ALM action can also be invoked from the ReadyAPI testsuite or testcase levels. Project action will export/update the entire project. Whereas, testsuite or testcase level actions will only export/update the specified testsuite and testcase respectively.

The ReadyAPI tests should now be visible in the specified TestPlan directory.

validate export

Import Project

In some organizations, teams first write the test in ALM for design and review and then automate it using tools like ReadyAPI. Dragonfly allows users to import tests from ALM Test Plan into a ReadyAPI project, creates a link between ReadyAPI tests and ALM tests, and creates a skeleton project - test cases with no test steps. ReadyAPI users can then create the test logic by adding various ReadyAPI test steps like REST, JDBC, SOAP, etc. and export to ALM using Dragonfly.

To import test cases from HP ALM, configure the QC_TestPlanDirectory property in your ReadyAPI project and select Dragonfly: Import from HP ALM. This will import tests from the configured ALM TestPlan to ReadyAPI project as test suites and cases.

dragonfly menu

import log

Dragonfly creates ReadyAPI test suites based on folders in ALM TestPlan. Dragonfly maps QC_TestPlanDirectory value to the project level and then expects only one level of sub folders which would map to the testsuite in ReadyAPI. If such parent/child folder hierarchy is not detected, Dragonfly imports all tests in a flat structure in ALM_Imported_TestCases test suite.

import suite

import dump

The typical usecase for Dragonfly is to export the ReadyAPI project to ALM and then run tests in ReadyAPI to capture results in ALM. To export, select the Dragonfly: Export to HP ALM project menu

Existing Tests Mapping

In many team, tests are first designed in ALM and then automated in some tool like ReadyAPI. Dragonfly provides a mapping interface to map ReadyAPI tests to existing tests in ALM. To map a ReadyAPI test to a test in ALM, set the QC_Mapped_Test_Id custom property of a test case in ReadyAPI to the Test ID of a test case in HP ALM.

test mapping

test mapping existing

Dragonfly's default behavior is to overwrite the ALM test's design steps in HP ALM's TestPlan when exporting the ReadyAPI project. This behavior is automatically disabled when tests are mapped. This is by design and is intended to preserve the ALM testcase in its original state with all the design steps. During test results export event, Dragonfly simply pass or fail all design steps based on test case pass or fail status.

Requirements Mapping

Dragonfly also allows users to map ReadyAPI tests to requirements in ALM. To map ReadyAPI tests to ALM requirements, specify the list of ALM requirement IDs inside QC_Req_Ids custom property of a testcase in ReadyAPI.

requirements mapping

requirements map

In ALM, requirements may have many level of sub-requirements. If you want to map a ReadyAPI test to all requirements and sub-requirements hierarchy, set the set QC_Req_Recursive property to true and dragonfly will map all child requirements to the testcase.

When the ReadyAPI is exported using Dragonfly's Export to HP ALM project menu, the mapped requirements can be viewed under the Req Coverage tab of a test configuration in TestPlan:

requirements map

When ReadyAPI tests are run, the mapped requirements will be automatically reflected in the coverage report. Test tracebility is one of the best features of ALM that is absent in many other test case management systems.

requirements cov

Run Tests

Once ReadyAPI tests have been export to ALM TestPlan, the next step is to run the ReadyAPI and to be able to view the test results in ALM. Dragonfly captures detailed details such the REST/JDBC/SOAP request and response from ReadyAPI and uploads them as attachments in ALM.

Run from ReadyAPI

To run tests from ReadyAPI, simply run the test as your normally would and Dragonfly will automatically upload the test results as the tests complete. The Dragonfly log will contain useful information about the uploads.

run tests from readyapi

Run from ALM

In many organizations, teams use ALM's hosts to run tests. During export, Dragonfly dynamically generates a VBScript for each test in ALM so that they tests can be be run in ALM. To run the tests from HP ALM Testlab, create a testset and add tests cases to the testset just like you would when running HP UFT, QTP, etc.

The ALM host need to have all both ReadyAPI and Dragonfly and the ReadyAPI project directory.

add to testset

run from ALM

Viewing Results

The view the ReadyAPI tests results in ALM, navigate to ALM TestLab → TestSet

view results

To view testrun details or to view run history, navigate to the specific testcase in the Testset and select Runs. The Runs view shows all the runs for this testcase.

view results

To view the request and response of ReadyAPI steps, navigate to the desired Run ID. All of the test steps from ReadyAPI along with their request and response will be added as attachments.

view results

Bulk Update Mode

By default, Dragonfly updates test results in real-time. This means, Dragonfly will connect with ALM, upload test results, and then disconnect from ALM for every testcase. Calling the ALM connect and disconnect API methods over a large number of tests, as they run serially, can increase overall execution time. If this overall overhead is not desireable, the bulk update mode can help alleviate some of this pressure. When enabled, the test results are stored on file and exported by an explicit action, Dragonfly: Bulk Results Update, by the user. This results in a single connect and disconnect API call which should greatly improve the overall execution time.

To enable bulk update, set QC_BulkUpdate project property to enabled and run the ReadyAPI tests. The dragonfly log tab will have a message indicating that bulkupdate is enabled and test results are being written to file.

project properties

dragonfly log ](/dragonfly/docs/soapui_project_setup/2015-06-09_00h01_23.png)

To upload the queued up test results, select the Dragonfly: Bulk Results Update project menu.

bulkupdate menu

By default, Dragonfly only stores the latest run when bulk update is enabled, but sometimes it is necessary to store all runs and then export them to ALM. To do that, set QC_Bulk_Update to enabled_all_runs.

To clear bulk results from local file system, navigate to Dragonfly: Information from the project menu and then select Clear bulk results

bulkupdate all

Project Export

In order to record testcase results, the ReadyAPI project should first be exported to TestRail. Export action creates Tests in TestRail and maps them to ReadyAPI tests.

To export ReadyAPI tests, right-click the Project's on the Test, Suite, or Project level and select Railflow: Export to TestRail menu. Railflow will export ReadyAPI tests AND test steps.

Exported test cases in TestRail:

Results Export

Railflow exports test results into TestRail automatically at the end of a test, suite, or project run.

Railflow creates a new runs in TestRail or adds runs to specified TR_run_name value.

Railflow exports both test, test steps, attaches the request and response of HTTP/SOAP/JDBC steps, and their statuses. Request/Response attachments can be disabled by TR_upload_attachments project field.

CICD Integration

Smartbear ReadyAPI allows two ways of running ReadyAPI tests from CI applications such as Jenkins, TeamCity, Gitlab, etc. Railflow can be configured at runtime to download the Railflow JAR and license for both of these options

ReadyAPI TestRunner

TestRunner is a shell/batch script which starts ReadyAPI and loads some project.

Download Railflow JAR (opens in a new tab) using wget or something similar.
COPY Railflow JAR into ~/.soapui/plugins folder (Example: C:\Users\user\.soapui\plugins on Windows or /home/user/.soapui/plugins on Unix) on the CI machine or in your Docker image
Create a new ~/railflow directory
COPY Railflow license file into ~/railflow directory

TestEngine Server

TestEngine server runs on the CI agent. To configure TestEngine,

Download Railflow JAR (opens in a new tab) using wget or something similar.
COPY Railflow JAR into ~/.soapui/plugins folder (Example: C:\Users\user\.soapui\plugins on Windows or /home/user/.soapui/plugins on Unix) on the CI machine or in your Docker image
Create a new ~/railflow directory
COPY Railflow license file into ~/railflow directory
Restart TestEngine server

TestEngine Docker Container

To install Railflow plugin to TestEngine docker container, you need to put Railflow plugin JAR file and Railflow license into TestEngine container, to do so please follow the steps below:

Download Railflow JAR (opens in a new tab) using wget or something similar.
COPY/MOUNT Railflow JAR into /data/.soapui/plugins folder of TestEngine container
COPY/MOUNT Railflow license file into /data/railflow directory of TestEngine container
Restart TestEngine container if you copied files into running container

Runtime Configuration

Config Overide

All Railflow configurations can be passed to the ReadyAPI TestRunner CLI (opens in a new tab)

testrunner.sh -P TR_url=https://myserver.testrail.io readyapi-project.xml

Project Export

In some teams, the most accurate state of ReadyAPI may be in GIT. For such teams, it may be more appropriate to export ReadyAPI tests during the CI build. To export ReadyAPI tests within CI, pass the TR_update_cases option to ReadyAPI testrunner

testrunner.sh -P "TR_update_cases=enabled" readyapi-project.xml

Introduction Setup Guide