Skip to content

Culebra GUI

Jump to bottom Edit New page
Diego Torres Milano edited this page May 7, 2017 · 99 revisions

General documentation about culebra, not just its GUI, can be found in its own page

Culebra ,with its user friendly GUI, is a really powerful tool for generating ready-to-execute scripts and testcases for automating Black box testing.

Important
If you are looking for CulebraTester web based UI and the new Java UiAutomator, Java Espresso, javascript and python generators please visit culebra.dtmilano.com, this page is about the python and Tkinter UI.

The GUI has many features that help testers and developers manipulating their devices or test-agents by just using a (mouse & keyboard) while creating ready-to-execute script in the background and save it as a python file.

It's really beneficial here to mention that, even users with a zero-knowledge in scripting can use the tool to record their test cases as scripted files and re-run them later easily on the test agents. Simply because they don't really need to edit, change or even know what's in those files.

The generated script files are just ready for execution! after recording.

AndroidViewClient GUI

Usage

Below is a simple way of how to launch the GUI of the tool. After adb connects to the test agent/device, run the following command line in the terminal:

culebra -G

You should get a window that looks similar to the following:

In case the window is a bit large or larger than the screen then use the scaling option -which is set to 1 by default- to make it fits into your screen. Again from the command line run the following command:

culebra --scale=0.5 -UG

Please note that the scaling value can be any number between 0-1. However, from experience a 0.5 scale would be almost perfect for all devices and screen sizes.

This is basically the very simple way of launching the GUI of Culebra. However, there are a lot of other features available for users to take advantage of that can be listed by simply typing in terminal the following:

culebra --help

In-depth Usage

The main idea of the GUI is to give users (like, testers and developers) the power and flexibility of controlling any android-based device (such as, smartphones, tablets, TVs, etc..) using only a standard mouse and a keyboard. At the same time while controlling the targeted device it generates a python script file that includes every step has been performed by the user. The output file is considered as test case that is ready to be executed from the command line.

  • First, in order to enable the unit test generation with the GUI use the following command:

culebra -UG

The -U will generate a unit test class and script and display it on the screen.

  • Second, to be able to save the script to a file add the -o option and the name of the file that you want the script to save into, like:

culebra --scale=0.5 -UG -o myTestCase.py

In the output file, there will be two kind of scripts. The steps that have been performed by the user and the dump view of each state. When running the file it will repeat the steps and verify the screen state after dump.

if you don't want the script to verify the screen state then add -u to the command line:

culebra --scale=0.5 -uUG -o myTestCase.py

  • One of the important features that all users would use is logging the actions. To enable it add the -L option to the command line as shown below,

To show the logging info on the terminal then run this command:

culebra --scale=0.5 -L -uUG

Please note that the actions also will be included in the adb logcat command output.

But in order to save the logging actions to the file along with the script then run the follow:

culebra --scale=0.5 -L -uUG -o myTestCase.py

  • The orientation (Portrait/Landscape) is locked by default to the portrait mode. To unlock it add -O to the command line:

culebra --scale=0.5 -O -uUG

By unlocking the orientation, the window which displays the current snapshot of the test device will change if the orientation of the device has changed.

To understand this feature, try to start your test with a portrait mode for instance then rotate the device and press F5 to refresh the snapshot which is displayed in the window on your computer. The window will change from portrait to a landscape mode to fit in the actual device new orientation.

  • When generating the script with the test runner -U option, Culebra injects the script file with some very useful options that can be listed using --help.

For instance, generate the script with the logging -L and unit test -U options enabled as shown below:

culebra -LGU -o ~/myTestCase.py

Then, type in terminal the name of the output file followed with --help. You should get something similar to this:

$ ./myTestCase.py --help
Usage: myTestCase.py [options] [test] [...]

Options:
  -h, --help       Show this message
  -v, --verbose    Verbose output
  -q, --quiet      Minimal output
  -s, --serialno s The serial number[s] to connect to or 'all'
  -f, --failfast   Stop on first failure
  -c, --catch      Catch control-C and display results
  -b, --buffer     Buffer stdout and stderr during test runs

Examples:
  myTestCase.py                               - run default set of tests
  myTestCase.py MyTestSuite                   - run suite 'MyTestSuite'
  myTestCase.py MyTestCase.testSomething      - run MyTestCase.testSomething
  myTestCase.py MyTestCase                    - run all 'test*' test methods
                                               in MyTestCase

One of the interesting options shown above is --verbose. It makes the script more talkative which helps users to see what the script is actually running and most importantly, where the test failed in case it did.

Example

Here is an example of the expected output when the test case passes:

$ ./myTestCase.py --verbose
testSomething (__main__.CulebraTests) ... CULEBRA: dumping content of window=-1
CULEBRA: finding view with id=id/no_id/1
CULEBRA: finding view with id=id/no_id/2
CULEBRA: finding view with id=id/no_id/3
CULEBRA: finding view with id=id/no_id/4
CULEBRA: finding view with id=id/no_id/5
CULEBRA: finding view with id=id/no_id/6
CULEBRA: finding view with id=id/no_id/7
CULEBRA: finding view with id=id/no_id/8
CULEBRA: finding view with id=id/no_id/9
CULEBRA: finding view with id=id/no_id/10
CULEBRA: finding view with id=id/no_id/11
CULEBRA: finding view with id=id/no_id/12
CULEBRA: finding view with id=id/no_id/13
CULEBRA: finding view with id=id/no_id/14
CULEBRA: finding view with id=id/no_id/15
CULEBRA: finding view with id=id/no_id/16
CULEBRA: finding view with id=id/no_id/17
CULEBRA: finding view with id=id/no_id/18
CULEBRA: finding view with id=id/no_id/19
CULEBRA: finding view with id=id/no_id/20
CULEBRA: finding view with id=id/no_id/21
CULEBRA: finding view with id=id/no_id/22
CULEBRA: finding view with id=id/no_id/23
CULEBRA: finding view with id=id/no_id/24
CULEBRA: finding view with id=id/no_id/25
CULEBRA: finding view with id=id/no_id/26
CULEBRA: finding view with id=id/no_id/27
CULEBRA: finding view with id=id/no_id/28
CULEBRA: finding view with id=id/no_id/29
CULEBRA: finding view with id=id/no_id/30
CULEBRA: finding view with id=id/no_id/31
CULEBRA: finding view with id=id/no_id/32
CULEBRA: finding view with id=id/no_id/33
CULEBRA: finding view with id=id/no_id/34
CULEBRA: finding view with id=id/no_id/35
CULEBRA: finding view with id=id/no_id/36
CULEBRA: finding view with id=id/no_id/37
CULEBRA: finding view with id=id/no_id/38
CULEBRA: finding view with id=id/no_id/39
CULEBRA: finding view with id=id/no_id/40
CULEBRA: finding view with id=id/no_id/41
CULEBRA: finding view with id=id/no_id/42
CULEBRA: finding view with id=id/no_id/43
CULEBRA: finding view with id=id/no_id/44
CULEBRA: finding view with id=id/no_id/45
CULEBRA: finding view with id=id/no_id/46
CULEBRA: finding view with id=id/no_id/47
CULEBRA: finding view with id=id/no_id/48
CULEBRA: finding view with id=id/no_id/49
CULEBRA: finding view with id=id/no_id/50
CULEBRA: finding view with id=id/no_id/51
CULEBRA: touching view with content-description=u'''Settings'''
CULEBRA: dumping content of window=-1
CULEBRA: finding view with id=id/no_id/1
CULEBRA: finding view with id=id/no_id/2
CULEBRA: finding view with id=id/no_id/3
CULEBRA: finding view with id=id/no_id/4
CULEBRA: finding view with id=id/no_id/5
CULEBRA: finding view with id=id/no_id/6
CULEBRA: finding view with id=id/no_id/7
CULEBRA: finding view with id=id/no_id/8
CULEBRA: finding view with id=id/no_id/9
CULEBRA: finding view with id=id/no_id/10
CULEBRA: finding view with id=id/no_id/11
CULEBRA: finding view with id=id/no_id/12
CULEBRA: finding view with id=id/no_id/13
CULEBRA: finding view with id=id/no_id/14
CULEBRA: finding view with id=id/no_id/15
CULEBRA: finding view with id=id/no_id/16
CULEBRA: finding view with id=id/no_id/17
CULEBRA: finding view with id=id/no_id/18
CULEBRA: finding view with id=id/no_id/19
CULEBRA: finding view with id=id/no_id/20
CULEBRA: finding view with id=id/no_id/21
CULEBRA: finding view with id=id/no_id/22
CULEBRA: finding view with id=id/no_id/23
CULEBRA: finding view with id=id/no_id/24
CULEBRA: finding view with id=id/no_id/25
CULEBRA: finding view with id=id/no_id/26
CULEBRA: finding view with id=id/no_id/27
CULEBRA: finding view with id=id/no_id/28
CULEBRA: finding view with id=id/no_id/29
CULEBRA: finding view with id=id/no_id/30
CULEBRA: finding view with id=id/no_id/31
CULEBRA: finding view with id=id/no_id/32
CULEBRA: finding view with id=id/no_id/33
CULEBRA: finding view with id=id/no_id/34
CULEBRA: finding view with id=id/no_id/35
CULEBRA: finding view with id=id/no_id/36
CULEBRA: finding view with id=id/no_id/37
CULEBRA: finding view with id=id/no_id/38
CULEBRA: finding view with id=id/no_id/39
CULEBRA: finding view with id=id/no_id/40
CULEBRA: finding view with id=id/no_id/41
CULEBRA: finding view with id=id/no_id/42
CULEBRA: finding view with id=id/no_id/43
CULEBRA: finding view with id=id/no_id/44
CULEBRA: finding view with id=id/no_id/45
CULEBRA: finding view with id=id/no_id/46
CULEBRA: finding view with id=id/no_id/47
CULEBRA: finding view with id=id/no_id/48
CULEBRA: finding view with id=id/no_id/49
CULEBRA: finding view with id=id/no_id/50
CULEBRA: finding view with id=id/no_id/51
CULEBRA: finding view with id=id/no_id/52
CULEBRA: finding view with id=id/no_id/53
CULEBRA: finding view with id=id/no_id/54
CULEBRA: finding view with id=id/no_id/55
CULEBRA: finding view with id=id/no_id/56
CULEBRA: finding view with id=id/no_id/57
CULEBRA: finding view with id=id/no_id/58
CULEBRA: finding view with id=id/no_id/59
CULEBRA: finding view with id=id/no_id/60
CULEBRA: finding view with id=id/no_id/61
CULEBRA: finding view with id=id/no_id/62
CULEBRA: finding view with id=id/no_id/63
CULEBRA: finding view with id=id/no_id/64
ok

----------------------------------------------------------------------
Ran 1 test in 23.694s

OK

In case of a failure, like running the same generated script on the wrong screen you should get something similar to the following:

$ ./myTestCase.py --verbose
testSomething (__main__.CulebraTests) ... CULEBRA: dumping content of window=-1
CULEBRA: finding view with id=id/no_id/1
CULEBRA: finding view with id=id/no_id/2
CULEBRA: finding view with id=id/no_id/3
CULEBRA: finding view with id=id/no_id/4
CULEBRA: finding view with id=id/no_id/5
CULEBRA: finding view with id=id/no_id/6
CULEBRA: finding view with id=id/no_id/7
CULEBRA: finding view with id=id/no_id/8
CULEBRA: finding view with id=id/no_id/9
ERROR

======================================================================
ERROR: testSomething (__main__.CulebraTests)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "./myTestCase.py", line 78, in testSomething
    id_no_id_9 = self.vc.findViewWithTextOrRaise(u'Play Store')
  File "/usr/local/lib/python2.7/dist-packages/androidviewclient-9.0.1-py2.7.egg/com/dtmilano/android/viewclient.py", line 2303, in findViewWithTextOrRaise
    raise ViewNotFoundException("text", text, root)
ViewNotFoundException: Couldn't find View with text='Play Store' in tree with root=ROOT

----------------------------------------------------------------------
Ran 1 test in 4.183s

FAILED (errors=1)

As you can see from above, it's very easy to know what is the problem and the cause of the failure. As in this case, the test failed with the ERROR message at CULEBRA: finding view with id=id/no_id/9 which is the Play Store icon.

Which means the script was executed on a different screen other than the one that has been previously generated for.

  • Sometimes, you might encounter a case where you want the tool to use a specific touching method in the scripted output file when touching the views on the screen. Like, finding a view using one or more of the following options:

findViewWithContentDescription findViewWithText findViewById

In this case all you need to do is to turn the one(s) you don't need off.

For instance you want to perform the touches on the screen using "text" and "id" only then you can turn the "description" option off:

culebra --scale=0.5 -d off -uG -o script.py

Same applies to the other two. Also note that you can turn more than one off at the same time in case you want to use one of them only.

Main Menu

File

View

Tree

View Details

UiDevice

Help

Context menu

Culebra GUI has a context menu that helps you with some common actions. Depending on whether the place clicked with the secondary mouse button contains a View or not the menu offers different actions.

View actions

Take View snapshot

Saves the snapshot of the View to a file. Take into account that it is important where you click to display the context menu because this will be the View used.

UiScrollable submenu

If the View is scrollable, or if its parent is scrollable too, as sometimes when you click you do it on the children, so culebra redirects the scrolling actions to the parent to keep things simple, the UiScrollable submenu provides:

  • Fling backward
  • Fling forward
  • Flind to beginning
  • Fling to end

Global actions

Drag dialog

Take snapshot and save to file

Control Panel

Long touch point using PX

Touch using DIP

Touch using PX

Generates a sleep() on output script

Toggle generating Test Condition

Touch Zones

Refresh

culebra actions

Quit

Happy testing with Culebra :)

Sidebar

Clone this wiki locally