Manage failure reasons


You need to be an admin user to be able to manage failure reasons.

The Failure Reasons tab displays a list of failure reasons on the left and steps on how to add custom failure reasons on the right. You recognize system-supplied failure reasons by the Perfecto logo preceding them.


Blocked failure reasons do not appear in the list. They are not configurable.

To access the administration panel:

  1. Log in to Perfecto at https://<cloud-name>
  2. On the UI landing page, click Assets and Setup.

  3. Click Failure reasons.

Failure reason names

Perfecto pre-defines several failure reasons, including:

  • Application crashed
  • Element not found
  • Invalid expression
  • Invalid XPath syntax
  • Multiple elements found
  • Popup handling

Each name is associated with an ID and a color. In the Smart Reporting UI, the color helps identify the different failure reasons for the test reports. You can rename system-supplied failure reasons, change their color, or define additional failure reasons.

In automation scripts, you can group failures under the same system-supplied or custom failure reason by supplying the failure reason ID in the TestResultFactory's createFailure()method.

Blocked failure reasons

Following is a list of blocked failure reasons. They provide insights into why a test could not start.

You cannot view or configure blocked failure reasons in this view.


Blocked failure reason


  • App not found

  • Install app failure

  • Launch app failure

Device allocation

  • Device in use

  • Device not connected

  • Device not found

  • Device reserved

  • Device not available

  • Device in error


  • Capability not supported


  • All licenses in use

  • No licenses found

Custom failure reasons

You can add up to 8 custom failure reasons. 

To add a custom failure reason:

  1. At the bottom of the failure reasons list, click Add another failure reason . You may need to scroll down to see this option.

  2. In the text box, enter the name string for the new failure reason. The string cannot exceed 25 characters.

  3. Select a color for the failure reason.
  4. To add the name, click the check mark. To cancel, click the X.

Custom failure reason IDs

Perfecto assigns each custom failure reason string a unique ID, as displayed in the ID column. You can copy-paste this ID into your tests scripts or into a text file used by the test scripts to indicate what caused a test to fail.

To copy a failure reason ID:

  1. Move your pointer over the ID to display the copy icon .
  2. Click the icon to copy the ID to the clipboard.
  3. Paste the ID into the destination text (or code) file.

Use failure reasons in test scripts

The Smart Reporting SDK and the External Test Information SDK support supplying the failure reason for a test script or report using the TestResultFactory's createFailure() method. This applies to both system-supplied and custom failure reasons.

The method supports the following parameters:

  • A failure message that is added to the test report
  • The actual error notification (throwable entity)
  • A failure reason ID string
    The string must match one of the defined failure reason IDs as shown in the UI. If the provided string does not match any of the defined failure reasons, it will be ignored.

The following example shows how to create the failure TestResult with a failure reason (one of the basic failure reasons supplied by Perfecto):

TestResult testResult = TestResultFactory.createFailure("Test stop failure", e, "bEC3xAdMTz");  
//Paste the failure reason ID after copying from the Failure reasons tab

See the full example test code here.