appium-python-client-shadowstep
Advanced tools
Shadowstep is a modular UI automation framework for Android applications built on top of Appium.
should.have, should.be)Element)pip install appium-python-client-shadowstep
from shadowstep.shadowstep import Shadowstep
application = Shadowstep()
capabilities = {
"platformName": "android",
"appium:automationName": "uiautomator2",
"appium:UDID": "192.168.56.101:5555",
"appium:noReset": True,
"appium:autoGrantPermissions": True,
"appium:newCommandTimeout": 900,
}
application.connect(server_ip='127.0.0.1', server_port=4723, capabilities=capabilities)
command_executor directly (e.g., http://127.0.0.1:4723/wd/hub), then server_ip/port are optional.capabilities as a dict, they will be converted into UiAutomator2Options internally.Session-scoped fixture example:
import pytest
from shadowstep.shadowstep import Shadowstep
@pytest.fixture(scope='session', autouse=True)
def app():
application = Shadowstep()
APPIUM_IP = '127.0.0.1'
APPIUM_PORT = 4723
APPIUM_COMMAND_EXECUTOR = f'http://{APPIUM_IP}:{APPIUM_PORT}/wd/hub'
capabilities = {
"platformName": "android",
"appium:automationName": "uiautomator2",
"appium:UDID": "192.168.56.101:5555",
"appium:noReset": True,
"appium:autoGrantPermissions": True,
"appium:newCommandTimeout": 900,
}
application.connect(server_ip=APPIUM_IP,
server_port=APPIUM_PORT,
command_executor=APPIUM_COMMAND_EXECUTOR,
capabilities=capabilities)
yield application
application.disconnect()
Run tests:
pytest -svl --log-cli-level INFO --tb=short tests/test_shadowstep.py
Run Appium server locally:
npm i -g appium@next
appium driver install uiautomator2
appium server -ka 800 --log-level debug -p 4723 -a 0.0.0.0 -pa /wd/hub --allow-insecure=adb_shell
Element)el = app.get_element({"resource-id": "android:id/title"})
el.tap()
el.text
el.get_attribute("enabled")
Call chains
el = app.get_element({"resource-id": "android:id/title"})
el.zoom().click()
Lazy DOM navigation (declarative):
el = app.get_element({'class': 'android.widget.ImageView'}).\
get_parent().\
get_sibling({'resource-id': 'android:id/summary'}).\
get_cousin(cousin_locator={'resource-id': 'android:id/summary'}).\
get_element({"resource-id": "android:id/switch_widget"})
Key features:
Lazy evaluation: the actual find_element happens on the first interaction with an element:
el = app.get_element({'class': 'android.widget.ImageView'}) # find_element is not called here
el.swipe_left() # find_element is called here
Locators: dict and XPath (tuples default to XPath strategy)
Built-in retries and auto-reconnect on session failures
Rich API: tap, click, scroll_to, get_sibling, get_parent, drag_to, send_keys, wait_visible, and more
item = app.get_element({'text': 'Network & internet'})
item.should.have.text("Network & internet").have.resource_id("android:id/title")
item.should.be.visible()
item.should.not_be.focused()
See more examples in tests/test_element_should.py.
Base page class is PageBaseShadowstep.
A page must:
PageBaseShadowstepPageedges: Dict[str, Callable[[], PageBaseShadowstep]] — navigation graph edgesis_current_page()Example page:
import logging
from shadowstep.element.element import Element
from shadowstep.page_base import PageBaseShadowstep
class PageAbout(PageBaseShadowstep):
def __init__(self):
super().__init__()
self.logger = logging.getLogger(__name__)
def __repr__(self):
return f"{self.name} ({self.__class__.__name__})"
@property
def edges(self):
return {"PageMain": self.to_main}
def to_main(self):
self.shadowstep.terminal.press_back()
return self.shadowstep.get_page("PageMain")
@property
def name(self) -> str:
return "About"
@property
def title(self) -> Element:
return self.shadowstep.get_element(locator={'text': 'About', 'class': 'android.widget.TextView'})
def is_current_page(self) -> bool:
try:
return self.title.is_visible()
except Exception as error:
self.logger.error(error)
return False
Auto-discovery of pages:
PageBaseShadowstep and starting with Pagepage*.py (usually pages/page_*.py) in project pathsShadowstep is createdNavigation:
app.shadowstep.navigator.navigate(from_page=app.page_main, to_page=app.page_display)
assert app.page_display.is_current_page()
Two ways to perform low-level actions:
app.adb.* — direct ADB via subprocess (good for local runs)app.terminal.* — mobile: shell via Appium or SSH transport (if ssh_user/ssh_password were provided in connect())ADB examples:
app.adb.press_home()
app.adb.install_app(source="/path/app._apk", udid="192.168.56.101:5555")
app.adb.input_text("hello")
Terminal examples:
app.terminal.start_activity(package="com.example", activity=".MainActivity")
app.terminal.tap(x=1345, y=756)
app.terminal.past_text(text='hello')
image = app.get_image(image="tests/_test_data/connected_devices.png", threshold=0.5, timeout=3.0)
assert image.is_visible()
image.tap()
image.scroll_down(max_attempts=3)
image.zoom().unzoom().drag(to=(100, 100))
Under the hood it uses opencv-python, numpy, Pillow.
app.start_logcat("device.logcat")
# ... test steps ...
app.stop_logcat()
InvalidSessionIdException, NoSuchDriverException)element, elements, navigator, terminal, image, utilsTools to automatically generate PageObject classes from UI XML (uiautomator2), enrich them while scrolling, merge results, and generate baseline tests.
PageObject from current page_source via Jinja2 templatePageObjectParser
uiautomator2) into a UiElementNode treeparse(xml: str) -> UiElementNodePageObjectGenerator
UiElementNode tree using templates/page_object.py.j2title, name, optional recycler, properties, anchors/summary, etc.generate(ui_element_tree: UiElementNode, output_dir: str, filename_prefix: str = "") -> (path, class_name)PageObjectRecyclerExplorer
page_source, re-generates PO and merges themShadowstep session (scroll/adb_shell)explore(output_dir: str) -> str (path to merged file)PageObjectMerger
merge(file1, file2, output_path) -> strPageObjectTestGenerator
templates/page_object_test.py.j2)generate_test(input_path: str, class_name: str, output_dir: str) -> (test_path, test_class_name)Note: crawler.py and scenario.py are conceptual notes/ideas, not stable API.
from shadowstep.shadowstep import Shadowstep
from shadowstep.page_object.page_object_parser import PageObjectParser
from shadowstep.page_object.page_object_generator import PageObjectGenerator
app = Shadowstep.get_instance() # or Shadowstep()
xml = app.driver.page_source
parser = PageObjectParser()
tree = parser.parse(xml)
pog = PageObjectGenerator()
path, class_name = pog.generate(ui_element_tree=tree, output_dir="pages")
print(path, class_name)
from shadowstep.page_object.page_object_recycler_explorer import PageObjectRecyclerExplorer
explorer = PageObjectRecyclerExplorer(base=app, translator=None)
merged_path = explorer.explore(output_dir="pages")
print(merged_path)
from shadowstep.page_object.page_object_test_generator import PageObjectTestGenerator
tg = PageObjectTestGenerator()
test_path, test_class_name = tg.generate_test(input_path=path, class_name=class_name, output_dir="tests/pages")
print(test_path, test_class_name)
templates/page_object.py.j2 — PageObject Python class templatetemplates/page_object_test.py.j2 — Pytest class templateTo tweak generated code structure, edit these files. (The generator uses the local templates folder.)
title via text/content-descscrollable==true container as recycler if presentsummary fields, filtering structural/non-informative classestext from locators for classes where text search is not supportedPageObjectRecyclerExplorer requires an active session and mobile: shell capability; uses swipes and adb_shellexplore())shadowstep/page_object/page_object_parser.pyshadowstep/page_object/page_object_generator.pyshadowstep/page_object/page_object_recycler_explorer.pyshadowstep/page_object/page_object_merger.pyshadowstep/page_object/page_object_test_generator.pyFor some reason, jinja templates are not downloaded to the folder when installed via pip. Insert them manually from this sources into .venv/Lib/site-packages/shadowstep/page_object/templates/ I don't know how to solve this yet.
start_logcat (mobile: startLogsBroadcast) is not working with my Selenium Grid now, need experiments with plugins. Solve it later
MIT — see LICENSE.
FAQs
UI Testing Framework powered by Appium Python Client
We found that appium-python-client-shadowstep demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Socket identified 80 fake candidates targeting engineering roles, including suspected North Korean operators, exposing the new reality of hiring as a security function.
Application Security
/Research
/Security News
Socket detected multiple compromised CrowdStrike npm packages, continuing the "Shai-Hulud" supply chain attack that has now impacted nearly 500 packages.
Research
/Security News
Malicious update to @ctrl/tinycolor on npm is part of a supply-chain attack hitting 40+ packages across maintainers