Troubleshooting

Element Not Found?

1

Check the score first

This answers most cases on its own. Above 0.7 the element is there; below 0.4 it is not.

python
from pyxelator import match_score

print(match_score(driver.get_screenshot_as_png(), 'button.png'))
2

Read the failure message

It reports the score and tailors its advice to it, rather than listing every possible cause.

python
click(driver, 'button.png', debug=True)
3

Verify element visibility

Matching only sees the visible viewport, so scroll to the element first. A cookie banner or modal covering it counts as not visible.

4

Wait for rendering

A low score often just means the page had not finished painting when the screenshot was taken.

5

Crop the template tighter

Just the element, no surrounding layout. Padding pushes the centre point outside the control.

6

Check template size

Must be smaller than the viewport.

Window size no longer needs to match. Since 0.5.0 the template is tried at a range of sizes, covering roughly 0.66x to 1.54x. Only recapture if the failure message names a size outside that.

Click Not Working?

  1. Enable debug mode to see what's happening
  2. Verify element is clickable (Pyxelator validates automatically)
  3. Add retry attempts: click(driver, 'button.png', retries=5)
  4. Check if element is covered by other elements

Fill Not Working?

  1. Enable debug mode for detailed error info
  2. Ensure element is input field (Pyxelator validates this)
  3. Try clicking before filling to focus the element
  4. Recapture template focused on input field, not label