This page explains which settings to change, and how, when detection does not work as expected.
How to Approach Tuning
Detection stability depends on the combination of the screen, the device and the detection image. It cannot be perfect in every environment. Keep the following in mind while tuning.
- Change only one setting at a time
If you change several settings at once, you will not be able to tell which change made the difference.
- Play the scenario after every change
The practice screens in the tutorial provide consistent conditions, which makes it easier to judge whether a change actually helped.
First, Check Whether the Screen Can Be Read at All
Some apps restrict reading of their screen contents. In that case, no setting will make Image Detection or Text Detection work.
Take a screenshot of the target screen using Android's screenshot feature. If the area you want to detect is blacked out, that app is blocking screen reading. TapEzy cannot read the screen contents either, so Image Detection and Text Detection cannot be used. In this case, consider Screen Element Detection, which does not require screen capture.
Tuning Image Detection
Nothing Is Detected at All
Start by re-cropping the detection image. If parts that change from screen to screen — a counter, a level badge — are included in the detection image, it will not match. Crop only the parts that stay the same.
Detection can also fail when the scale of the detection image and the image on the screen differ too much. If possible, capture the detection image again so that the scales match.
Detection Fails Occasionally
Raise Error Tolerance in small steps. The default is 70, and it can be set from 0 to 100. A higher value makes it easier to match the detection image, but also increases false positives. Do not raise it too far at once — play the scenario and check after each adjustment.
It Detects the Wrong Place
Narrow the Detection Area to the region where the detection image appears. Lowering Error Tolerance also reduces false positives.
Detection Fails When Colour or Brightness Changes
Check whether Detection in Grayscale is turned on. This setting is on by default. When it is on, the image is converted to grayscale during detection, so targets whose colour alone changes — selected states, theme switches — can still be matched. If you have turned it off, turn it back on.
Detection Is Slow
Start by narrowing the Detection Area. The larger the detection area, the longer detection takes. If you know in advance where the detection image appears, always set the area. Narrowing the detection area helps accuracy as well as speed, so try it first.
If detection still feels slow after narrowing the Detection Area, reduce the Scaling Factor. For Image Detection, the Scaling Factor ranges from x1/16 to x1 and can only be reduced, not enlarged. Unless the target is a complex image, reducing the size improves efficiency.
Tuning Text Detection
Nothing Is Detected at All
Start by shortening the Detected Text. This is the most effective change. Trim it down to the most distinctive fragment that will not be confused with anything else.
Enter the Detected Text exactly as it appears on the screen. A difference in upper and lower case can also prevent detection.
The Text Is Too Small to Detect
If the text on screen is too small, detection is less likely to succeed. Raise the Scaling Factor. For Text Detection, the Scaling Factor ranges from x1/16 to x16, so it can be both reduced and enlarged.
Note that enlarging increases memory usage and may make operation unstable. When enlarging, consider also narrowing the Detection Area to reduce the processing load.
It Detects the Same Text Somewhere Else
Narrow the Detection Area to the region where the target text appears.
It Matches a Fragment Inside a Longer Sentence
Turn on Restrict to Element-Level Matching. When it is on, detection succeeds only when a word matches the Detected Text exactly. This excludes matches buried inside a longer sentence, and also prevents the detected position from shifting to the centre of the whole line.
Note that when the entire line matches the Detected Text exactly, it is detected regardless of whether this setting is on or off. This setting only affects matches that occur as part of a longer line.
Nothing Is Detected After Turning On "Restrict to Element-Level Matching"
Turn it back off. When it is on, a word within the line must match the Detected Text exactly. If the Detected Text spans a larger unit than a single word — a string covering several words, for example — it will not match.
The Detected Text is always matched case-sensitively, whether this setting is on or off. When it is off, however, the whole line is returned as the result even when the matching position cannot be identified, so detection still succeeds. When it is on there is no such behaviour, so a difference in upper and lower case means nothing is detected. For example, if the screen shows Login but the Detected Text is set to login, nothing is detected while this setting is on.
Detection Is Slow
Start by narrowing the Detection Area. If you know in advance where the target text appears, always set the area. Narrowing the detection area helps accuracy as well as speed, so try it first.
If detection still feels slow after narrowing the Detection Area, and the text is large, reducing the Scaling Factor improves efficiency as well.
The Control Has No Visible Text
Controls with no text visible on screen — icon-only buttons, input fields without a label — cannot be found with Text Detection. Switch to Screen Element Detection. It does not require screen capture permission, and it also works with Playback Reservation.
General Notes on Detection
Detection Fails After the Screen Orientation Changes
The Detection Area is stored as coordinates on the screen. If the orientation changes and the Detection Area you set no longer overlaps the screen at all, detection will always fail.
If the orientation may change, either leave the Detection Area unset so that the full screen is used, or split the scenario by orientation.
Detecting Several Images or Pieces of Text in Sequence
Add as many detection steps as you need and they will be processed in order from the top.
For Text Detection, entering multiple lines in the Detected Text makes each line a separate candidate. Flows such as "jump to another step when found" or "move to another scenario" can be built with the Step Jump and Scenario Jump steps.
Image, Text and Number Detection Do Not Work With Playback Reservation
Image Detection, Text Detection and Number Detection all require screen capture. Screen capture is not available to Playback Reservation, so a scenario containing these steps will not run from a reservation and is recorded as "Failed: Requires screen capture".
This check also follows Scenario Jump into the scenarios it targets. Disabled steps are excluded from the check.
If you want a scenario to run automatically at a specified time, consider Screen Element Detection, which does not require screen capture.
