Culebra GUI
Culebra ,with its user friendly GUI, is a really powerful tool for generating ready-to-execute scripts and testcases for automating Black box testing.
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
Below is a simple way of how to lunch the GUI of the tool. After adb connect the 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 not 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
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.
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.
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.
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.
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
Happy testing with Culebra :)