When a step fails
Triage procedure for a failed step, and the before-screenshot table that maps symptom to cause to fix.
The step that failed is often not the step that is broken. Diagnosis starts at the before-screenshot of the first failing step.
Platforms
Android · iOS
Start with
The before-screenshot of the first failing step
Most common cause
The description doesn't match the app's exact on-screen wording
Second most common
An earlier step didn't do what you thought, so you're on the wrong screen
Watch out
Debug the first failing step, not the last. A cascade of red has one cause
Prerequisites
Gather these before triaging:
The report for the failed run
The first failing step in the step list, not the last
That step's before-screenshot
The healed-step count for the run
The device model and OS version the run used
Why the reported step is not always the broken step
A tap fails because the element is absent. The element is absent because the run is on the wrong screen. The run is on the wrong screen because an earlier step tapped something adjacent, ran before the screen finished loading, or was consumed by a popup. Drizz reports the failure at the point it surfaced, which is the last step in that chain.
The first question is whether the run is on the expected screen. The before-screenshot answers it.
Triage procedure
Open the debug report and locate the first failing step.
Open that step's before-screenshot.
Compare it against the screen the step expected.
If the screen is wrong, walk back up the step list to the last step whose after-screenshot looked correct. The step immediately after it is the defect. Stop here.
If the screen is correct, match the before-screenshot against the symptom table below and apply the fix.
Check whether the step carries a healed badge. A healed step has a weak description — rewrite it now — see Self-healing.
If the step resolved from cache and the UI changed recently, re-run. If it is still wrong on the third run, the description is the cause — see Caching.
Re-run the test and confirm the step passes.
If it still fails, use Report Issue in the desktop app. It bundles logs, screenshots and device state automatically.
Symptom, cause, fix
Wrong screen entirely
An earlier step didn't do what you thought
Fix the earlier step. This step is correct
Right screen, element off-screen
Missing scroll
Add Scroll down until "<target>" is visible before the step
Right screen, element present
Description doesn't match, or is ambiguous
Use the app's exact on-screen text; add neighbor or section context
Screen mid-load, spinner visible
Missing wait
Add Wait Until <n> Seconds before the step
Black or blank screen
Secure screen — the OS blocks capture on payment and PIN screens
Cannot be automated. Restructure the test around it
Step carries a healed badge
The description no longer matches the screen
Rewrite the description — see Self-healing
Cached step acting on a moved element
Stale resolution after a UI change
Re-run. If wrong on the third run, fix the description — see Caching
Fixing a description that doesn't match
Three edits, in order of how often they resolve the failure.
Paraphrasing is the most common cause of a tap landing on the wrong element. If the button reads Charge Now, write Charge Now.
Common mistakes
Debug the last red step in a cascade
You fix a symptom and the run fails one step earlier next time
Re-run and hope
A description failure is deterministic. It fails again
Add a long wait to fix a wrong-element failure
The suite gets slower and the tap still lands on the wrong element
Handle a global popup with an IF in every test
Put it in Memory once — one rule, every test
Read the after-screenshot to diagnose
It shows the aftermath. The before shows the cause
Report a black screen as a Drizz bug
Secure screens block capture for every tool. It cannot be automated
Next
Last updated: 6 August 2026
Last updated
Was this helpful?