Tools: Axosoft REST API - TestRail

Tools: Axosoft REST API

Defect plugins can be used to implement a deeper bug tracker integration and TestRail comes with a ready-to-use Axosoft defect plugin.

The Axosoft defect plugin discussed in this article uses Axosoft’s REST API, which we recommend for Axosoft v13 or later (including OnTime Now). If you are using (Axosoft) OnTime v12 or earlier, please use our OnTime SOAP defect plugin instead.

To configure the defect plugin, select Administration > Integration; then select Axosoft_v17_REST from the Defect Plugin dropdown list.

The next step is to configure all the necessary connection settings in the Configuration field. Project-specific plugins and configuration settings can optionally be specified under Administration > Projects.

You might need to activate the API in Axosoft first. To do this:

  • In Axosoft, select Tools > System Settings > Axosoft API Settings
  • Enable the API on that page
  • Generate API keys on that page

The required client ID as well as the client secret needed to configure the integration are also listed on that page.

When the defect plugin has been configured, a new Push link is shown next to the Defects field in the Add Test Result dialog. Clicking the link will open a popup dialog that enables you to push a bug report to Axosoft without leaving TestRail.

Once the test result is added, hovering the mouse cursor over a defect ID will open a window with useful information and status details about the defect in Axosoft.

Please note: Axosoft no longer supports the creation of defects since all Work Items now correspond to Features on their platform.

If you still wish to use the plugin to push features into Axosoft, we recommend implementing an additonal workflow step called “bug”, “defect” or whichever naming convention works for your team. The workflow step should have the Work Item Type set to “Bug (Issue)” and, under the Allowed Next Steps settings for the new Workflow Step, check all the allowed Next Steps for bugs/defects (or create new ones as desired).

The next time you attempt to push a Work Item to Axosoft, remember to set the Workflow Step dropdown field to the step created above. Implementing this workaround means you can continue to use the defect plugin to create Work Items of type Bug (Issue) in Axosoft.

Note: Plugin customizations require the ‘Axosoft_v17_REST’ Defect and Reference plugin, available with TestRail 6.5 and later.

Customizations

The Axosoft defect plugin was built to work with a standard Axosoft configuration. TestRail allows you to customize the fields which appear in the Push dialog as well as when hovering over Defect IDs. Preconfigured push fields and hover fields can be set to ‘on’ or ‘off’ in their respective [push.fields] and [hover.fields] sections, or change the order in which they appear by the fields in each section.

Please keep in mind some fields (such as the title field) are always enabled and may not appear in these sections due to always beings required by either TestRail or Axosoft.

The Axosoft Defect Plugin also supports modifying field properties as well as custom fields.

In addition to enabling, disabling, or re-organizing fields as described above, it’s also possible to change additional options per field. To do this, you would define a section for the field, such as [push.field.description] and specify additional options within this section.

[push.field.description]
label=Detailed Description
required=true

Please see below for full list and explanation of the available field options:

Option Description
label Specifies the display name of the field in the Push Defect dialogue (Required for custom fields)
size Specifies whether the field is displayed as a compact field (compact) or uses the full width of the dialogue (full)
remember Specifies if previously selected values for this field should be remembered and restored the next time the Push Defect dialogue is opened
required Specifies if this field is mandatory or optional and whether users are required to enter a value for this field in the Push Defect dialogue
type Specifies the type of this field, please see section Custom fields below for a list of supported field types (Required for custom fields)

 

Custom fields

You can also use the above-mentioned approach to add custom fields to TestRail’s Push Defect dialogue. To do this, simply add a line with your custom field to the [push.fields] section to add a field. Custom fields are designated by customfield_<id>.

[push.fields]
...
description=on
customfield_11002=on

Then, add a [field.settings.custom_<id>] section. This section is required so the plugin can push and/or retrieve data from your tool.

Custom Field IDs can be obtained through the Axosoft API, as documented here.

The following is an example custom field configuration:

[field.settings.customfield_11002]
label=Customer
size=compact
type=dropdown
required=true

The following field types are supported:

Field Type
Description
bool A Yes/No dropdown menu for True/False, Yes/No, or similar binary values
date A string field which accepts a YYYY-MM-DD or similarly structured date value. Formatting may depend on the integrated tool’s requirements
dropdown A dropdown list that allows users to select one of the multiple options
multiselect Allows users to select multiple, pre-defined options
string A small free-text field for up to 250 characters
text A large free-text field without practical size limitations

 

Attachments

The Axosoft Defect Plugin supports submitting attachments to Axosoft as well. This field can be turned on and off, but cannot be customized. To submit one or more attachments to Axosoft, simply drag the attachment to the attachments or description areas of the push dialog or click on the area to choose an attachment from your file system.

Attachments

The Axosoft Defect Plugin supports submitting attachments to Axosoft as well. This field can be turned on and off, but cannot be customized. To submit one or more attachments to Axosoft, simply drag the attachment to the attachments or description areas of the push dialog or click on the area to choose an attachment from your file system.

Reference Plugin

Reference plugins can be used to retrieve additional information from IDs entered into the References field of TestRail entities, such as test cases, test runs, and milestones. The Reference Plugin is configured on the References tab of the integration settings in the same manner the Defect Plugin is configured.

The plugin supports hovering over Reference IDs but does not support a Push dialog for the References field. It is also possible to customize the fields which appear via link hovering and add custom fields, as described above.

If you have the Defect Plugin already configured for Axosoft, you can simply copy your [connection] and [hover.fields] sections from the Defect Plugin into the Reference plugin configuration. Alternatively, you can choose different fields to be displayed for References and Defects.

Additional Customizations

TestRail also supports custom defect plugins. If your team uses TestRail Server, it is possible to futther customize the defect plugin (or build your own) to support additional field types or other data. Please see out documentation here for additional information.