API Reference

Module Functions (Recommended)

find(driver, image, confidence=0.7)

Check if an element exists on the page.

Parameters:

  • driver - Selenium WebDriver, Playwright Page, or Appium driver
  • image - Path to template image (str)
  • confidence - Match confidence 0.0-1.0 (default: 0.7)

Returns:

bool - True if found, False otherwise

python
if find(driver, 'button.png'):
    print("Button found!")

# With custom confidence
if find(driver, 'button.png', confidence=0.8):
    print("Button found with high confidence!")

locate(driver, image, confidence=0.7)

Get the coordinates of an element.

Parameters:

  • driver - Selenium WebDriver, Playwright Page, or Appium driver
  • image - Path to template image (str)
  • confidence - Match confidence 0.0-1.0 (default: 0.7)

Returns:

tuple | None - (x, y) coordinates or None if not found

python
coords = locate(driver, 'button.png')
if coords:
    x, y = coords
    print(f"Button at ({x}, {y})")
Since 0.5.0: coordinates come back in CSS pixels, not raw screenshot pixels. Identical on a standard-DPI screen. On a retina or 4K display the screenshot is 2-3x larger than the viewport, and returning those raw numbers is what made clicks miss. If you were correcting for that yourself, drop the workaround.

match_score(screenshot_bytes, image, grayscale=True)

Report how close a template came, ignoring any threshold. Use it to pick aconfidence value instead of guessing at one.

Parameters:

  • screenshot_bytes - Screenshot as bytes
  • image - Path to template image (str)
  • grayscale - Match on luminance only (default: True)

Returns:

float | None - score from -1.0 to 1.0, or None if the template cannot be matched at all

python
from pyxelator import match_score

score = match_score(driver.get_screenshot_as_png(), 'button.png')
print(score)
# 0.92  ->  solid match
# 0.62  ->  element is there but renders differently; try confidence=0.6
# 0.13  ->  not on screen; changing the template will not help
# None  ->  unusable template: solid colour, or bigger than the screen

Appium Only

swipe_app(driver, image, direction='up', distance=200, confidence=0.7, duration=0.2, debug=False)

Swipe starting from the centre of the matched element.

Parameters:

  • driver - Appium driver
  • image - Path to template image (str)
  • direction - 'up', 'down', 'left' or 'right'
  • distance - Distance in pixels (default: 200)
  • confidence - Match confidence 0.0-1.0 (default: 0.7)
  • duration - Seconds spent travelling (default: 0.2). Raise it if the app treats the gesture as a fling.
  • debug - Enable debug logging (default: False)

Returns:

bool - True if swiped, False if the element was not found, the direction is invalid, or the gesture failed

python
from pyxelator import swipe_app

# Swipe up 300px from the matched element
swipe_app(driver, 'list_item.png', 'up', 300)

# Slower drag, for apps that ignore a quick flick
swipe_app(driver, 'slider_handle.png', 'right', 200, duration=0.6)

A swipe that would run past the screen edge is clamped to it. If clamping leaves nowhere to move, the swipe is refused rather than performed as a gesture that quietly does nothing.

click(driver, image, confidence=0.7, retries=3, delay=0.5, debug=False)

Click an element by matching a template image.

Parameters:

  • driver - Selenium WebDriver, Playwright Page, or Appium driver
  • image - Path to template image (str)
  • confidence - Match confidence 0.0-1.0 (default: 0.7)
  • retries - Number of retry attempts (default: 3, Selenium/Playwright only)
  • delay - Delay between retries in seconds (default: 0.5, Selenium/Playwright only)
  • debug - Enable debug logging (default: False)

Returns:

bool - True if clicked successfully, False otherwise

python
# Simple click
click(driver, 'submit_button.png')

# With retry and debug
click(driver, 'button.png', retries=5, delay=1.0, debug=True)

fill(driver, image, text, confidence=0.7, debug=False)

Fill text into an input element.

Parameters:

  • driver - Selenium WebDriver, Playwright Page, or Appium driver
  • image - Path to template image (str)
  • text - Text to fill (str)
  • confidence - Match confidence 0.0-1.0 (default: 0.7)
  • debug - Enable debug logging (default: False)

Returns:

bool - True if filled successfully, False otherwise

python
# Simple fill
fill(driver, 'email_field.png', 'user@example.com')

# With debug mode
fill(driver, 'password.png', 'secret123', debug=True)

Class API

Pyxelator(driver)

Object-oriented interface for Pyxelator.

python
from pyxelator import Pyxelator

px = Pyxelator(driver)
px.find('button.png')          # Same as find(driver, 'button.png')
px.click('button.png')          # Same as click(driver, 'button.png')
px.fill('input.png', 'text')    # Same as fill(driver, 'input.png', 'text')

Methods:

  • find(image, confidence=0.7) → bool
  • locate(image, confidence=0.7) → tuple | None
  • click(image, confidence=0.7) → bool
  • fill(image, text, confidence=0.7) → bool