Package: telenium
TeleniumTelenium provide a framework to remote tests or automation Kivy-based application:Selector support using XPATH-like syntax (//BoxLayout[0]/Button[@text~="Close"])Create selector by touching the UIQuery or set attribute on any widgetsExecute remote codeunittestssupportIntegrate as a Kivy modulesWeb IDEPython 2 and 3 (since version 0.4, using json-rpc)Installationpip install teleniumRun the Telenium IDEIt will start a webserver onhttp://127.0.0.1:8080/and automatically open a new
tab in your favorite webbrowser. You'll be able to configure where your main.py
is, and start writing tests directly:teleniumYou can also edit telenium-json:telenium tests/test-ui-myfeature.jsonRun the application with telenium moduleIf you don't use the IDE, in order to remote control your application,
you need the Telenium client installed within your application.Method 1: Run your application with telenium clientTelenium can execute your application and manually add telenium_client to it.
Just do:python-mtelenium.executemain.pyMethod 2: Import and install telenium client in your applicationTelenium client can be imported and installed at the start of your application:If telenium is fully available:fromteleniumimportinstallinstall()If you only includedtelenium_client.pymodule:fromtelenium_clientimportinstallinstall()Method 3: Add telenium_client as a Kivy modules into your applicationJust copy/pastemods/telenium_client.pyin your application, then before
running your application, initialize it:fromos.pathimportdirnamefromkivy.modulesimportModulesfromkivy.configimportConfigModules.add_path(dirname(__file__))Config.set("modules","telenium_client","")You also need to addpython-jsonrpcin your dependencies (pip install python-jsonrpc)Remote automationYou can easily create a script that will connect to your telenium client, and do stuff.importteleniumcli=telenium.connect()# wait until the SaveCSVButton instance is in the widget tree.cli.wait_click("//SaveCSVButton")# wait that one label have Export to CSV textcli.wait("//Label[@text~=\"Export to CSV\"]",timeout=2)# make a screenshot !result=cli.screenshot()print(result["filename"])print(result["data"])Connect to a telenium-ready applicationWe have a command line client to play with. After the application is started,
you can connect with::$ python -m telenium.client localhostThen play with it.cliis the telenium client where you can invoke remote
commands. See theTelenium commandsto see what you can do:>>>id=cli.pick()# then click somewhere on the UI>>>cli.click_at(id)True>>>cli.setattr("//Label","color",(0,1,0,1))TrueIf a command returns True, it means it has been successful, otherwise it
returns None.Create unit testsTelenium have a module you can use that ease unit tests: it launch the app
and execute tests. For now, it has been tested and coded to work only
locally using subprocess.Additionnal methods:assertExists(selector, timeout=-1)andassertNotExists(selector, timeout=-1)to check if a selector exists or not
in the app. They both have atimeoutparameter that, if it reach, will fail
the test.cli.wait_click(selector, timeout=-1): easy way to wait a selector to match,
then click on the first widget.Here is a real example that launch an app (default is "main.py"):It first go in the menu to click where it need to save a CSV (SaveButton,CascadeSaveButtonthenSaveCSVButton)Then wait at maximum 2s the popup to show with a label "Export to CSV"Then click on the "Close" button in the popupThen ensure the popup is closed by checking the label is gone.Example:fromtelenium.testsimportTeleniumTestCaseclassUITestCase(TeleniumTestCase):cmd_entrypoint=["main.py"]deftest_export_csv(self):self.cli.wait_click("//SaveButton")self.cli.wait_click("//CascadeSaveButton")self.cli.wait_click("//SaveCSVButton")self.assertExists("//Label[@text~=\"Export to CSV\"]",timeout=2)self.cli.wait_click("//FitButton[@text=\"Close\"]",timeout=2)self.assertNotExists("//Label[@text~=\"Export to CSV\"]",timeout=2)Each new TeleniumTestCase will close and start the application, so you always
run from a clean app. If you always need to do something before starting the
test, you can overload theinit. This will be executed once before any
tests in the class starts:classUITestCase(TeleniumTestCase):definit(self):self.cli.wait_click("//PresetSelectionItem[@text!~=\"ttyUSB0 on mintel\"]",timeout=10)self.cli.wait_click("//Button[@text=\"Connect\"]")self.cli.wait("//BottomLabel[@text=\"Done\"]",timeout=10)You can also change few parameters to change/add things in your application for
unit testing if needed:classUITestCase(TeleniumTestCase):process_start_timeout=5cmd_env={"I_AM_RUNNING_TEST":1}Telenium commandsversion()Return the current API version. You can use it to know which methods are
available.>>>cli.version()1select(selector)Return unique selectors for all widgets that matches theselector.>>>cli.select("//Label")[u"/WindowSDL/GridLayout/Label[0]",u"/WindowSDL/GridLayout/Label[1]"]getattr(selector, key)Return the value of an attribute on the first widget found by theselector.>>>cli.getattr("//Label","text")u"Hello world"setattr(selector, key, value)Set an attribute named bykeytovaluefor all widgets that matches theselector.>>>cli.setattr("//Label","text","Plop")Trueelement(selector)ReturnTrueif at least one widget match theselector.>>>cli.element("//Label")True>>>cli.element("//InvalidButton")Falseexecute(code)Execute python code in the application. Only the "app" symbol that point to the
current running application is available. Return True if the code executed, or
False if the code failed. Exception will be print withing the application logs.>>>cli.execute("app.call_one_app_method")Truepick(all=False)Return either the first widget selector you touch on the screen (all=False,
the default), either it return the list of all the wigdets that are traversed
where you touch the screen.>>>cli.pick()u'/WindowSDL/Button[0]'>>>cli.pick(all=True)[u'/WindowSDL/Button[0]',u'/WindowSDL']click_on(selector)Simulate a touch down/up on the first widget that match theselector. Return
True if it worked.>>>cli.click_on("//Button[0]")Truescreenshot(filename=None)(>= 0.5.0)Take a screenshot of the current application in a PNG format.
Data will be saved into filename if passed, or you can have data in the result.>>>cli.screenshot("hello.png"){"filename":"hello.png","data":"base64 utf-8 encoded data..."}evaluate(expr)(>= 0.5.0)Evaluate an expression, and return the result. Only serializable result can be
fetched, if an object is sent back, you'll receive None.>>>cli.evaluate("len(app.my_list)")123evaluate_and_store(key, expr)(>= 0.5.0)Evaluate an expression, and store the result in a id-map, used byexecuteandevaluatemethod.>>>cli.evaluate_and_store("root","app.root.children[0]")True>>>cli.execute("root.do_something()")select_and_store(key, selector)(>= 0.5.0)Select the first widget returned by a selector, and store the result in a id-map, used byexecuteandevaluatemethod.>>>cli.select_and_store("btn","//Button[@title~='Login']")True>>>cli.execute("btn.disabled = True")Telenium selector syntax (XPATH)Cheat sheet about telenium XPATH-based selector implementation.Select any widget that match the widget class in the hierarchy://CLASSSelect a widget that match the tree:/CLASSSelect a widget with attributes/CLASS[<ATTR SELECTOR>,...]Index selector if there is multiple match:/CLASS[INDEX]Attribute exists:@attrAttribute equal to a value:@attr=VALUEAttribute not equal to a value:@attr!=VALUEAttribute contain a value:@attr~=VALUEAttribute does not contain a value:@attr!~=VALUEValue can be a string, but must be escaped within double quote only.Some examples:# Select all the boxlayout in the app
//BoxLayout

# Take the first boxlayout
//BoxLayout[0]

# Get the Button as a direct descendant of the BoxLayout
//BoxLayout[0]/Button

# Or get the 5th Button that are anywhere under the BoxLayout (may or may
# not a direct descandant)
//BoxLayout[0]//Button

# Select the button that is written "Close"
//BoxLayout[0]//Button[@text="Close"]

# Select the button that contain "Close"
//BoxLayout[0]//Button[@text~="Close"]Real life examplesAutomate screenshots of an appI was having an app where content is displayed randomly. But the client want to review all the texts and position of every content. Easy peasy::fromteleniumimportconnectprefix="screenshots/myapp-"cli=connect()cli.wait("//MyAppContainer")cli.select_and_store("root","//MyAppContainer")animals_count=cli.evaluate("len(root.animals)")forindexinrange(animals_count):# get one animalcli.evaluate_and_store("animal",f"root.animals[{index}]")animal_id=cli.evaluate("animal['id']")animal_name=cli.evaluate("animal['title_en']")# focus the animalcli.execute("root.focus_animal(animal)")cli.sleep(3)# take a screenshotcli.screenshot(f"{prefix}{animal_id}-{animal_name}.png")cli.sleep(3)Automate login and go directly to the right screenIf you code, close your app, restart, login, do many action before reaching the screen you are currently working on, you could automate the first part.fromteleniumimportconnectcli=connect()cli.wait('//IntroUI')cli.execute("app.username = 'username'")cli.execute("app.userpwd = 'fake'")cli.click_on('//LoginButton')cli.wait('//IntroUI')cli.click_on('//StartButton')cli.wait('//GameUI')