huskium.appium package

Submodules

huskium.appium.by module

class huskium.appium.by.ByAttr

Bases: object

Mainly used for internal validation of By. It can also be used to check the available By attributes in your current Selenium and Appium version.

NAMES = ['ACCESSIBILITY_ID', 'ANDROID_DATA_MATCHER', 'ANDROID_UIAUTOMATOR', 'ANDROID_VIEWTAG', 'ANDROID_VIEW_MATCHER', 'CLASS_NAME', 'CSS_SELECTOR', 'CUSTOM', 'FLUTTER_INTEGRATION_KEY', 'FLUTTER_INTEGRATION_SEMANTICS_LABEL', 'FLUTTER_INTEGRATION_TEXT', 'FLUTTER_INTEGRATION_TEXT_CONTAINING', 'FLUTTER_INTEGRATION_TYPE', 'ID', 'IMAGE', 'IOS_CLASS_CHAIN', 'IOS_PREDICATE', 'LINK_TEXT', 'NAME', 'PARTIAL_LINK_TEXT', 'TAG_NAME', 'XPATH', '_custom_finders', 'clear_custom_finders', 'get_finder', 'register_custom_finder']: A list of all By attribute names as strings.

OPTIONAL_VALUES = ['accessibility id', '-android datamatcher', '-android uiautomator', '-android viewtag', '-android viewmatcher', 'class name', 'css selector', '-custom', '-flutter key', '-flutter semantics label', '-flutter text', '-flutter text containing', '-flutter type', 'id', '-image', '-ios class chain', '-ios predicate string', 'link text', 'name', 'partial link text', 'tag name', 'xpath', {}, <bound method By.clear_custom_finders of <class 'appium.webdriver.common.appiumby.AppiumBy'>>, <bound method By.get_finder of <class 'appium.webdriver.common.appiumby.AppiumBy'>>, <bound method By.register_custom_finder of <class 'appium.webdriver.common.appiumby.AppiumBy'>>, None]: A list of all By attribute values with None.

VALUES = ['accessibility id', '-android datamatcher', '-android uiautomator', '-android viewtag', '-android viewmatcher', 'class name', 'css selector', '-custom', '-flutter key', '-flutter semantics label', '-flutter text', '-flutter text containing', '-flutter type', 'id', '-image', '-ios class chain', '-ios predicate string', 'link text', 'name', 'partial link text', 'tag name', 'xpath', {}, <bound method By.clear_custom_finders of <class 'appium.webdriver.common.appiumby.AppiumBy'>>, <bound method By.get_finder of <class 'appium.webdriver.common.appiumby.AppiumBy'>>, <bound method By.register_custom_finder of <class 'appium.webdriver.common.appiumby.AppiumBy'>>]: A list of all By attribute values.

huskium.appium.ecex module

Expected Conditions Extension (ECEX)

Overview:: ECEX extends official expected_conditions (EC) module.
Locator Handling:: The locator follows the same structure as EC.
Index Feature:: The index allows using the find_elements(*locator)[index] pattern. If index is None, find_element(*locator) is used instead.
Exception Handling:: ECEX separates methods for locators and WebElements to enable more robust exception handling.

class huskium.appium.ecex.ECEX

Bases: GenericECEX[WebDriver, WebElement]

static webview_is_present(switch: bool = True, index: int = -1) → Callable[[WebDriver], str | Literal[False]]

Whether WEBVIEW context is present.

Parameters:

switch – Switch to the WEBVIEW context when it exists and switch is True.
index – Switch to the specified context index, defaulting to the most recently appeared.

Returns:

Current context str when a WEBVIEW exists; otherwise, False when no WEBVIEW exists.

Return type:

(str | False)

huskium.appium.element module

Bases: GenericElement[WebDriver, WebElement]

app_drag_and_drop(target: Element, pause: float | None = None) → Self

Appium API. Drag the origin element to the destination element.

Parameters:

target – The element to drag to.
pause – How long the action pauses before moving after the tap and hold in seconds.

app_scroll(target: Element, duration: int | None = None) → Self

Appium API. Scrolls from one element to another.

Parameters:

target – The element to scroll to (center of element).
duration – Defines speed of scroll action when moving to target. Default is 600 ms for W3C spec.

flick_by(offset: Coordinate = (0.5, 0.75, 0.5, 0.25), area: Coordinate = (0.0, 0.0, 1.0, 1.0), timeout: int | float = 3, max_round: int = 10, max_align: int = 2, min_xycmp: int = 100, duration: int = 1000) → Self

Appium API. For native iOS and Android apps, it flicks the screen until the element becomes visible within the specified area.

Parameters:

offset – (start_x, start_y, end_x, end_y) or (sx, sy, ex, ey).
area – (x, y, width, height) or (x, y, w, h).
timeout – Maximum wait time in seconds.
max_round – Maximum number of flick attempts.
max_align – Maximum attempts to align all borders of the element within the area (view) border.
min_xycmp – Minimum x and y components to avoid being mistaken as a click during alignment. Should be considered along with duration.
duration – Alignment (not flick) duration in milliseconds. If too short, it may be mistaken as a click. Should be considered along with min_xycmp.

Examples

from huskium import Offset, Area

# Filck by default.
# Offset.UP (sx, sy, ex, ey) = (0.5, 0.75, 0.5, 0.25)
# Area.FULL (x, y, w, h) = (0.0, 0.0, 1.0, 1.0)
# offset x: Fixed 0.5 of current window width.
# offset y: From 0.75 to 0.25 of current window height.
my_page.target_element.filck_by()

# Filck to the direction using Offset.
my_page.target_element.filck_by(Offset.DOWN)
my_page.target_element.filck_by(Offset.UPPER_LEFT)

# Filck with customize relative offset.
my_page.target_element.filck_by((0.3, 0.85, 0.5, 0.35))

# Filck within a filckable range.
# Get the absolute area rect using the scrollable element.
area = my_page.scrollable_element.rect
my_page.target_element.filck_by((0.3, 0.85, 0.5, 0.35), area)

# Filck with customize absolute offset.
my_page.target_element.filck_by((250, 300, 400, 700))

# Filck with customize relative offset of customize relative area.
# The area is relative to current window rect, for example:
# current window rect = (10, 20, 500, 1000)
# area = (0.1, 0.2, 0.6, 0.7)
# area_x = 10 + 500 x 0.1 = 60
# area_y = 20 + 1000 x 0.2 = 220
# area_width = 500 x 0.6 = 300
# area_height = 1000 x 0.7 = 700
my_page.target_element.filck_by(
    (0.3, 0.85, 0.5, 0.35), (0.1, 0.2, 0.6, 0.7)
)

# Filck with customize relative offset of customize absolute area.
my_page.target_element.filck_by(
    (0.3, 0.85, 0.5, 0.35), (100, 150, 300, 700)
)

is_viewable(timeout: int | float | None = None) → bool: Appium API. This method is typically used with swipe-based element searching. Checks if the current element is visible on the mobile screen.

property location_in_view: dict[str, int]: Appium API. Retrieve the location (coordination) of the element relative to the view when it is present. For example: {‘x’: 100, ‘y’: 250}.

swipe_by(offset: Coordinate = (0.5, 0.75, 0.5, 0.25), area: Coordinate = (0.0, 0.0, 1.0, 1.0), timeout: int | float = 3, max_round: int = 10, max_align: int = 2, min_xycmp: int = 100, duration: int = 1000) → Self

Appium API. For native iOS and Android apps, it swipes the screen until the element becomes visible within the specified area.

Parameters:

offset – (start_x, start_y, end_x, end_y) or (sx, sy, ex, ey).
area – (x, y, width, height) or (x, y, w, h).
timeout – Maximum wait time in seconds.
max_round – Maximum number of swipe attempts.
max_align – Maximum attempts to align all borders of the element within the area (view) border.
min_xycmp – Minimum x and y components to avoid being mistaken as a click during alignment. Should be considered along with duration.
duration – Swipe and alignment duration in milliseconds. If too short, it may be mistaken as a click. Should be considered along with offset and min_xycmp.

Examples

from huskium import Offset, Area

# Swipe by default.
# Offset.UP (sx, sy, ex, ey) = (0.5, 0.75, 0.5, 0.25)
# Area.FULL (x, y, w, h) = (0.0, 0.0, 1.0, 1.0)
# offset x: Fixed 0.5 of current window width.
# offset y: From 0.75 to 0.25 of current window height.
my_page.target_element.swipe_by()

# Swipe to the direction using Offset.
my_page.target_element.swipe_by(Offset.DOWN)
my_page.target_element.swipe_by(Offset.UPPER_LEFT)

# Swipe with customize relative offset.
my_page.target_element.swipe_by((0.3, 0.85, 0.5, 0.35))

# Swipe within a swipeable range.
# Get the absolute area rect using the scrollable element.
area = my_page.scrollable_element.rect
my_page.target_element.swipe_by((0.3, 0.85, 0.5, 0.35), area)

# Swipe with customize absolute offset.
my_page.target_element.swipe_by((250, 300, 400, 700))

# Swipe with customize relative offset of customize relative area.
# The area is relative to current window rect, for example:
# current window rect = (10, 20, 500, 1000)
# area = (0.1, 0.2, 0.6, 0.7)
# area_x = 10 + 500 x 0.1 = 60
# area_y = 20 + 1000 x 0.2 = 220
# area_width = 500 x 0.6 = 300
# area_height = 1000 x 0.7 = 700
my_page.target_element.swipe_by(
    (0.3, 0.85, 0.5, 0.35), (0.1, 0.2, 0.6, 0.7)
)

# Swipe with customize relative offset of customize absolute area.
my_page.target_element.swipe_by(
    (0.3, 0.85, 0.5, 0.35), (100, 150, 300, 700)
)

tap(duration: int | None = None) → Self

Appium API. Tap the center location of the element when it is present. This method can be used when click() fails.

Parameters:: duration – Length of time to tap, in ms.

huskium.appium.elements module

Bases: GenericElements[WebDriver, WebElement]

property locations_in_view: list[dict[str, int]]: Appium API. The locations relative to the view of all present elements.

huskium.appium.page module

class huskium.appium.page.Page(driver: WD, timeout: int | float = 10, reraise: bool = True, remark: str = 'Page')

Bases: GenericPage[WebDriver, WebElement]

activate_app(app_id: str) → Self

Appium API. Activates the application if it is not running or is running in the background.

Parameters:: app_id – The application id to be activated.

property context: str: Appium API. Get current context.

property contexts: list[str]: Appium API. Get current all contexts.

draw_gesture(dots: list[dict[str, int]] | list[tuple[int, int]], gesture: str, duration: int = 1000) → None

Appium 2.0 API. Nine-box Gesture Drawing.

Parameters:

dots – Define dots in order [1, 2, 3, …, 9], e.g., [{‘x’: 100, ‘y’: 100}, {‘x’: 200, ‘y’: 100}, …]; or [(100, 100), (200, 100), …]. If dots are elements, use page.elements.centers.
gesture – A string containing the actual positions of the nine dots, such as ‘1235789’ for drawing a Z shape.

draw_lines(dots: list[dict[str, int]] | list[tuple[int, int]], duration: int = 1000) → None

Appium 2.0 API. Draw lines by dots in given order.

Parameters:

dots – A list of coordinates for the target dots, e.g., [{‘x’: 100, ‘y’: 100}, {‘x’: 200, ‘y’: 300}, …]; or [(100, 100), (200, 300), …].
duration – The time taken to draw between two points.

flick(start_x: int, start_y: int, end_x: int, end_y: int) → Self

Appium API. Flick from one point to another point.

Parameters:

start_x – x-coordinate at which to start
start_y – y-coordinate at which to start
end_x – x-coordinate at which to stop
end_y – y-coordinate at which to stop

Examples

page.flick(100, 100, 100, 400)

flick_by(offset: Coordinate = (0.5, 0.75, 0.5, 0.25), area: Coordinate = (0.0, 0.0, 1.0, 1.0), times: int = 1) → Self

Flick from one point to another, allowing customization of the offset and border settings.

Parameters:

offset – Please refer to the Examples.
area – Please refer to the Examples.
times – The number of times to perform the flick.

Examples

# Swipe parameters. Refer to the Class notes for details.
from huskium import Offset, Area

# Flick down.
my_page.flick_by(Offset.DOWN)

# Flick to the right.
my_page.flick_by(Offset.RIGHT)

# Flick to the upper left.
my_page.flick_by(Offset.UPPER_LEFT)

# Default is flicking up.
# offset = Offset.UP = (0.5, 0.5, 0.5, 0.25)
# area = Area.FULL = (0.0, 0.0, 1.0, 1.0)
# offset x: Fixed 0.5 of current window width.
# offset y: From 0.75 to 0.25 of current window height.
my_page.flick_by()

# Flick within a swipeable range.
area = my_page.scrollable_element.rect
my_page.flick_by((0.3, 0.85, 0.5, 0.35), area)

# Flick with customize absolute offset.
my_page.flick_by((250, 300, 400, 700))

# Flick with customize relative offset of current window size.
my_page.target_element.flick_by((0.3, 0.85, 0.5, 0.35))

# Flick with customize relative offset of customize relative area.
# The area is relative to current window rect, for example:
# current window rect = (10, 20, 500, 1000)
# area = (0.1, 0.2, 0.6, 0.7)
# area_x = 10 + 500 x 0.1 = 60
# area_y = 20 + 1000 x 0.2 = 220
# area_width = 500 x 0.6 = 300
# area_height = 1000 x 0.7 = 700
my_page.flick_by((0.3, 0.85, 0.5, 0.35), (0.1, 0.2, 0.6, 0.7))

# Flick with customize relative offset of customize absolute area.
my_page.flick_by((0.3, 0.85, 0.5, 0.35), (100, 150, 300, 700))

get_status() → dict

Appium API. Get the Appium server status.

Examples

page.get_status()

swipe(start_x: int, start_y: int, end_x: int, end_y: int, duration: int = 0) → Self

Swipe from one point to another point, for an optional duration.

Parameters:

start_x – x-coordinate at which to start
start_y – y-coordinate at which to start
end_x – x-coordinate at which to stop
end_y – y-coordinate at which to stop
duration – defines the swipe speed as time taken to swipe from point a to point b, in ms, note that default set to 250 by ActionBuilder.

Examples

page.swipe(100, 100, 100, 400)

swipe_by(offset: Coordinate = (0.5, 0.75, 0.5, 0.25), area: Coordinate = (0.0, 0.0, 1.0, 1.0), duration: int = 1000, times: int = 1) → Self

Swipe from one point to another, allowing customization of the offset and border settings.

Parameters:

offset – Please refer to the Examples.
area – Please refer to the Examples.
duration – Defines the swipe speed as the time taken to swipe from point A to point B, in milliseconds. The default is set to 250 by ActionBuilder.
times – The number of times to perform the swipe.

Examples

# Swipe parameters. Refer to the Class notes for details.
from huskium import Offset, Area

# Swipe down.
my_page.swipe_by(Offset.DOWN)

# Swipe to the right.
my_page.swipe_by(Offset.RIGHT)

# Swipe to the upper left.
my_page.swipe_by(Offset.UPPER_LEFT)

# Default is swiping up.
# offset = Offset.UP = (0.5, 0.75, 0.5, 0.25)
# area = Area.FULL = (0.0, 0.0, 1.0, 1.0)
# offset x: Fixed 0.5 of current window width.
# offset y: From 0.75 to 0.25 of current window height.
my_page.swipe_by()

# Swipe within a swipeable range.
area = my_page.scrollable_element.rect
my_page.swipe_by((0.3, 0.85, 0.5, 0.35), area)

# Swipe with customize absolute offset.
my_page.swipe_by((250, 300, 400, 700))

# Swipe with customize relative offset of current window size.
my_page.swipe_by((0.3, 0.85, 0.5, 0.35))

# Swipe with customize relative offset of customize relative area.
# The area is relative to current window rect, for example:
# current window rect = (10, 20, 500, 1000)
# area = (0.1, 0.2, 0.6, 0.7)
# area_x = 10 + 500 x 0.1 = 60
# area_y = 20 + 1000 x 0.2 = 220
# area_width = 500 x 0.6 = 300
# area_height = 1000 x 0.7 = 700
my_page.swipe_by((0.3, 0.85, 0.5, 0.35), (0.1, 0.2, 0.6, 0.7))

# Swipe with customize relative offset of customize absolute area.
my_page.swipe_by((0.3, 0.85, 0.5, 0.35), (100, 150, 300, 700))

switch_to_app() → str: Appium API. Switch to native app. Return the current context after judging whether to switch.

switch_to_context(context: str | None) → str: Appium API. Sets the context for the current session. Passing None is equal to switching to native context. Returns the current context.

switch_to_flutter() → str: Appium API. Switch to flutter app.

switch_to_webview(switch: bool = True, index: int = -1, timeout: int | float | None = None, reraise: bool | None = None) → str | Literal[False]

Appium API. Wait for the webview is present and determine whether switch to it.

Parameters:

switch – If True, switches to WEBVIEW when it becomes available.
index – Defaulting to -1 which targets the latest WEBVIEW.
timeout – The timeout duration in seconds for explicit wait.
reraise – If True, re-raises a TimeoutException upon timeout; if False, returns False upon timeout.

Returns:

str for current context; False for no any WEBVIEW in contexts.

Return type:

(str | False)

tap(positions: list[tuple[int, int]], duration: int | None = None) → Self

Appium API. Taps on an particular place with up to five fingers, holding for a certain time.

Parameters:

positions – an array of tuples representing the x/y coordinates of the fingers to tap. Length can be up to five.
duration – length of time to tap, in ms. Default value is 100 ms.

Examples

page.tap([(100, 20), (100, 60), (100, 100)], 500)

tap_window_center(duration: int | None = None) → Self

Tap window center coordination.

Parameters:: duration – length of time to tap, in ms. Default value is 100 ms.

terminate_app(app_id: str, **options: Any) → bool

Appium API. Terminates the application if it is running.

Parameters:

app_id – the application id to be terminates.
**options – timeout (int), [Android only] how much time to wait for the uninstall to complete. 500ms by default.

Returns:

True if the app has been successfully terminated.

Return type:

bool

huskium.appium package

Submodules

huskium.appium.by module

huskium.appium.ecex module

huskium.appium.element module

huskium.appium.elements module

huskium.appium.page module

Module contents