This document provides a practical, approach to diagnosing and fixing UI test failures. The goal is to help you quickly identify where a test failed, why it failed, and what to change to resolve it.
First principles of UI test troubleshooting
Every UI test failure should be analysed in the same order:
Identify the exact step where the failure occurred.
Understand what that step was attempting to do by reading the step description.
Compare the expected UI state with what is actually shown in the screenshot.
Almost all UI test failures are caused by a mismatch between the step’s intent and the UI state at the moment the step runs.
How to inspect a failed test
Go to the Test tab.
Open the relevant test job.
Click into the failed test and select View run.
Review the ordered list of steps. The failed step is highlighted in red.
Open the screenshot for the failed step to see what the UI looked like immediately before the failure.
Compare the screenshot with the written step instructions to determine what the test expected to happen versus what actually happened.
Many failures originate in an earlier step. Always review the steps leading up to the failure, not just the red step itself.
How to watch a test running
If the failure is not obvious from the screenshots:
Edit the test.
Select Run from start.
This allows you to watch each step execute in real time, making it easier to observe unexpected UI behaviour and pinpoint where the test diverges from expectations.
Common failure scenarios and how to diagnose them
“No actionable element found” / Element cannot be clicked
This error occurs when a click step (for example, “Click Accounts tab”) cannot be completed.
Common causes include:
A required prior step did not complete successfully.
A modal, popup, or secondary window is blocking the target element.
The page has not finished loading or is in an unexpected state.
To diagnose this issue, review the screenshot for the failed step to confirm the element is visible and interactable, and check earlier steps for any navigation or state changes that may have altered the page.
Example: If the Accounts tab is not visible in the screenshot, the test cannot click it and will fail.
Test fails immediately with a 403 error
If a test fails at the login step with a 403 or authentication-related error, this usually indicates a user or environment mismatch.
Check which user the test is configured to log in as, which org the test job is running against, and whether that user exists in the target org. Common causes include the test being created in one sandbox but run against another, or the configured user existing in a different org than the target. To resolve this, edit the test to use a valid user for the target org or create the missing user if appropriate.
After fixing, run the test manually to confirm the issue is resolved rather than waiting for the next scheduled run.
If the user exists and the correct org is connected, re-authorising the org connection on the Source control and services page may resolve the issue.
How to change the org a test runs is using
Select the test.
Click the three-dot menu next to Run test and choose Edit.
On the edit screen, select the org you want the test to run on.
How to change the user a test runs as
Edit the test.
Select the appropriate org connection.
Hover over the first step and click the pencil icon this will you to configure the test to run as:
A specific user
A specific profile
A user with a specific permission set
“You’ll need to enable the Administrators Can Log in as Any User Login Access Policy”
UI tests require Salesforce to allow administrators to log in as other users.
To enable this:
In Salesforce Setup, search for Login Access Policies.
Open the Login Access Policies page.
Enable Administrators Can Log in as Any User.
This setting allows Gearset to perform UI actions without requiring each user to grant access individually.
Assertion failures: fields or values not visible
Assertions define conditions that must be true for a test to pass, such as verifying that specific fields are visible on the page. A common failure occurs when a previous step saves and closes the page, causing the assertion to run against a screen that no longer contains the expected fields. To diagnose this, review the step immediately before the assertion and confirm that the UI is still displaying the data being checked. To resolve the issue, move the assertion earlier in the test or add navigation steps to return to the correct page before performing the assertion.
Summary
UI test failures are rarely random. By consistently identifying the failed step, validating the expected UI state, and reviewing prior steps, most issues can be diagnosed quickly. Watching the test run and understanding common failure patterns will significantly reduce time spent debugging.