Creating Template Images

Best Practices

Screenshot ONE element

Focus on a single button, field, or icon

Keep it small

50x50 to 300x200 pixels works best

Choose unique elements

Avoid generic buttons or repeated patterns

Crop tightly

Remove unnecessary surrounding content

Use descriptive names

login_button.png, email_field.png, etc.

How to Create Templates

python

# Helper script to create templates
from selenium import webdriver
import time

driver = webdriver.Chrome()
driver.get('https://yoursite.com')
time.sleep(2)

# Take full screenshot
driver.save_screenshot('fullpage.png')

# Now open fullpage.png in image editor
# Crop the specific element you want
# Save as: login_button.png, email_field.png, etc.

Tip: Use tools like Snipping Tool (Windows), Screenshot (macOS), or GIMP for cropping.

Window Size & Scaling

Template matching is very sensitive to size. A template captured at one window size scores near zero against the same page rendered even 4% wider, which is why "recapture at the same window size" used to be the standard advice.

Since 0.5.0 the template is tried at a range of sizes automatically, so one captured on your laptop generally still works on a wider monitor or in CI:

Template vs page	Result
0.66x - 1.54x	Found, nothing to configure
exactly 0.5x / 2.0x	Found. Covers a display with a different device pixel ratio
below 0.66x, above 1.54x	Not found. Recapture the template

Two narrow bands, around 1.06x and 1.55x, score just under the 0.7 default;confidence=0.65 covers them.

Cost: a template that matches at its captured size short-circuits, so the common case is unaffected. A template that matches at no size pays for the whole range: roughly 1s instead of 110ms on a 1920px screenshot. That only affects the not-found path, but it is worth knowing if you call find() in a loop as a presence check.

To match only at the captured size:

python

from pyxelator import find_image_in_screenshot

find_image_in_screenshot(shot, 'button.png', scales=(1.0,))

# Or globally, before your tests run:
import pyxelator.core
pyxelator.core.DEFAULT_SCALES = (1.0,)

One limitation: the winning size is whichever candidate scores highest. When the real element sits between two candidate sizes and a similar-looking element sits exactly on one, the look-alike can win. Cropping tightly around something visually distinctive avoids it.