Documentation / Introduction

Find elements by how they look.

Pyxelator is a Python library that locates UI elements from a cropped screenshot. Use it with your existing Selenium, Playwright, or Appium driver.

Run your first exampleInstallation options
Template image
Save changes
save_button.png
Your application
Profile settings
Save changes
Crop an element once. Pyxelator looks for that image in the current screen.

From screenshot to action

  1. Capture a template.

    Crop a screenshot to one distinctive button or field. Keep its size and appearance consistent with the application you test.

  2. Find it on screen.

    Pass your driver and the template path to Pyxelator. Matching compares the image with the current screenshot.

  3. Inspect the result, then continue.

    The structured API reports whether an action succeeded. If a match is unsafe or ambiguous, it performs no click or write.

A first look at the API

With a driver already open on your application and a template saved locally:

python
from pyxelator import click_result

result = click_result(driver, "save_button.png", confidence=0.8)
if result.ok:
    print("Save button clicked")
else:
    print(result.reason)

The quick start includes installation, a local demo page, and the full script.

When image matching helps

Use Pyxelator when an element is visible but difficult to target with a DOM selector, such as a canvas control or a mobile interface. Matching depends on appearance: changes in zoom, theme, or element size can require a new template.

Framework support. Selenium and Playwright are supported. Appium support is in beta; check framework support before using it for mobile tests.

Continue reading

Create reliable templates
Learn what to crop and how scaling affects a match.
Tune match confidence
Measure a match score before choosing a threshold.
Look up the API
Find parameters, return values, and compatible legacy functions.