• Android SDK (Make sure to add SDK/tools and SDK/platform-tools to your PATH)
  • apktool
  • ant
  • A running Android emulator, or a plugged in Android device

The Build Process

Acouchi needs to make some tweaks to your APK to allow functional testing. This is roughly the process:

  • Temporarily add some source files, and the Robotium jar file to your project
  • Build your project in debug mode with ant
  • Hack the APK file and inject some need elements in your AndroidManifest.xml

Please note that the build only has to happen again if your java code for the application under test changes.

How It Works

Acouchi builds Robotium and a HTTP server into your Android application. Robotium is an API that has some amazing functionality for functional testing on Android. In the Ruby API we post method calls via HTTP to the server on your device, which in turn returns meaningful data.



require "acouchi"
require "acouchi/cucumber"
require "acouchi/rspec/matchers"

configuration = Acouchi::Configuration.from_json("acouchi_configuration.json"))
configuration.device =ENV["ACOUCHI_DEVICE"] if ENV["ACOUCHI_DEVICE"]
configuration.port =ENV["ACOUCHI_PORT"] if ENV["ACOUCHI_PORT"]


def page


      "target_package": "com.acouchi.sample",
      "activity"      : "com.acouchi.sample.StartupActivity",
      "project_path"  : ".",
      "apk"           : "AcouchiSample-debug.apk"


    require "acouchi/rake/tasks

Running the tests

rake build #only if you modify the application code

Pressing Keys

page.send_key Acouchi::Solo::MENU
page.send_key Acouchi::Solo::LEFT
page.send_key Acouchi::Solo::RIGHT

Modifying Text

# Enter text into the only text area on the page
page.enter_text "Hello"

# This enters text into the fifth text area
page.enter_text "Hello", 5

# Clear text from the only edit text area on the page

# Clear text from the fourth edit text area
page.clear_text 4

Searching Text

# Check if page has_text
page.has_text? "Bla"

# has_text? default options
page.has_text?("Text", {
  :scroll          => true, # Scroll down the page searching for text
  :minimum_matches => 0,    # Zero means you don't care how many matches there are.
  :must_be_visible => true  # Whether you care if the text is visible or not.

# List all content currently on the page

# List all content currently on the page and scroll up and down
# to find any content which may have been missed

Clicking Things

# Check if button with text exists
page.has_button? "Clicky"

# Click on some text
page.click_text "Hello"

# click_text default options
page.click_text("Text", {
  :match       => 1, # The match of the text that should be clicked
  :auto_scroll => true # Auto scroll to find text to click on

# Click on a view by id
page.click_view 123

# Click on an image by index
page.click_image 5

Finding Views

# List the buttons currently on the page

# List the text views currently on the page



# Scroll up or down the only list on the page

# Scroll up or down a list by its index
page.scroll_up_list 4
page.scroll_down_list 4

# Scroll to left or right
# Press the back button


Most methods in acouchi will wait for a while until an element is available.

# Wait for the text "Bla Bla" to appear. Returns true if the text appears.
page.wait_for_text "Bla Bla"

# wait_for_text default options
page.wait_for_text "Bla Bla", {
  # The minimum amount of matches you want to appear
  :minimum_number_of_matches => 0,
  # How long to wait for, in seconds
  :timeout                   => 20,
  # Scroll the page in search of text
  :scroll                    => true,
  # Only take into account visible text
  :must_be_visible           => true


require "acouchi/rspec/matchers"

# The have_text matcher will now output all page content
# if the assertion fails
page.should have_text "Bla"


Problems clicking on buttons and text

If it seems that buttons/text aren't being clicked properly, you need to add the following xml to your AndroidManifest.xml:

<uses-sdk android:targetSdkVersion="SDK_VERSION" />

Where SDK_VERSION is the version of the Android SDK you are using. Version numbers can be found here

For example, Android 4.0 uses version 14, Android 4.0.3 uses version 15 and Android 4.1 uses version 16.