Auto-tools/Projects/Robocop/WritingTests
What's this?
Robotium is a test framework created to make it easy to write powerful and robust automatic black-box test cases for Android applications. Robocop provides a wrapper around Robotium making it even easier to write and execute UI tests for native Fennec.
Creating a new test
The best way to create a new test is to copy and modify an existing test case -- see mobile/android/base/tests.
Create a new file in the test directory named test[YourFeature].java.in.
The top of each test file must have:
#filter substitution package @ANDROID_PACKAGE_NAME@.tests
Then define a test class extending the Robotium ActivityInstrumentationTestCase2:
public class testMyFeature extends ActivityInstrumentationTestCase2
Each test class must have three methods:
protected void setUp() // Starts Fennec and sets up commonly used member variables. This is usually very similar for every test class. public void test[YourFeature]() // Your test code goes here. Use the Robocop API to access Fennec elements, click, send keys, and assert conditions. public void tearDown() // Clean up. This is usually very similar for every test class.
APIs
The main interfaces are Actions, Elements, and Driver.
Actions provides commonly used non-element specific actions that can be taken on the application, such as clicking, dragging and sending key events.
Actions //This will cause this process to spin until the gecko fires a specific JSON event, such as DOMContentLoaded void waitForGeckoEvent(String geckoEvent); //Clicks the given Key (Actions.SpecialKey.[DOWN|UP|LEFT|RIGHT|ENTER]) void sendSpecialKey(SpecialKey button) //Sends a string of characters to the system. (most have been implemented but not all) void sendKeys(String keysToSend); //Sends a drag action across the screen void drag(int startingX, int endingX, int startingY, int endingY)
Element represents each of the available UI objects in Fennec including the Awesomebar, the 'tabs' button, and different lists and menus.
Element //To click the element. void click() //Returns true if the element is currently displayed boolean isDisplayed(); //Returns the text currently displayed on the element, or direct sub-elements. String getText();
Driver finds elements and provides info about the UI.
Driver //This is used to find elements given their id's name. Element findElement(String name); //This is used for getting information on scrolls. NOTE: It must be used for the next three methods to return useful information void setupScrollHandling(); int getPageHeight(); //The total height of the page. int getScrollHeight(); //How far down the screen the client has scrolled. int getHeight(); //The height of the client's view. //The following are used to give information on the graphical location of the Gecko view on the screen. int getGeckoTop(); int getGeckoLeft(); int getGeckoHeight(); int getGeckoWidth();
Usable IDs
The following is a list of ids that can be used with Driver.findElement(). Most of the following ids have not been tested, so might have unexpeced results, or require increased APIs for them. To know how a given object is used, in mobile/android/base, grep R.id.[id-name] * (from Objdir/mobile/android/base/R.java#id)
abouthome_content add_tab addons address_bar agent_mode all_pages_list awesome_bar awesome_screen awesomebar_button awesomebar_tabs awesomebar_text background bookmark bookmark_icon bookmark_title bookmark_url bookmarks_list browser_toolbar close container doorhanger_choices doorhanger_container doorhanger_title favicon forward gecko_layout grid history_list info list main_layout notification_image notification_progressbar notification_text notification_title outline plugin_container preferences quit recommended_addon_list reload save_as_pdf screenshot select_list share site_security stop tabs tabs_count title url
Tips
A recurring issue faced when writing UI tests is the timing of events. Just to enter a URL, you probably want to click on the awesome bar and then send the key events for the text. If you click() and then immediately sendKeys(), the text probably won't get to the awesome bar. If you sleep() briefly before and after clicking, the task will probably succeed...but how long are those sleep() calls? Will the test still work on other devices, reliably? Avoid the temptation to scatter sleep() throughout your test. Whenever possible, wait for events or other feedback to verify the UI is in the required state before proceeding. For example, many tests will want to wait for startup before starting the test: driver.waitForGeckoEvent("Gecko:Ready").