RubyMotion Testing Guide for Android

This document describes how to write functional tests for an existing RubyMotion Android app. Tests provide a set of specifications an application is supposed to conform to and can be used to catch regressions after an unfortunate change in the code.

1. Getting Started

RubyMotion integrates Bacon, a small clone of the popular RSpec framework written by Christian Neukirchen.

More specifically, RubyMotion uses a version of Bacon called MacBacon which has been extended for runloop-based platforms. MacBacon is maintained by Eloy Duran.

1.1. Spec Files

Spec files are responsible to contain the tests of your project.

Spec files are created under the spec directory of a RubyMotion project.

By default, a RubyMotion project has a spec/main_spec.rb file which contains a single test that ensures that the main activity has a title.

$ cat spec/main_spec.rb
describe "Main activity" do
  it "has a title" do
    main_activity.title.should == "Hello"

Assuming the main activity is properly implemented to follow that specification, rake spec will gracefully exit with a status error of 0.

$ rake spec
I/com/yourcompany/hello( 2024): Main activity
I/com/yourcompany/hello( 2024):   - has a title
I/com/yourcompany/hello( 2024): 1 specifications (1 requirements), 0 failures, 0 errors

1.2. Spec Helpers

Spec helpers can be used to extend the testing framework, for instance by introducing a common set of classes or methods that will be used by the spec files. Spec helpers will be compiled and executed before the actual spec files.

Spec helpers are created under the spec/helpers directory of a RubyMotion project. An example could be spec/helpers/extension.rb.

By default, a RubyMotion project has no spec helper.

1.3. Running the Tests

The spec Rake task can be used to run the test suite of a RubyMotion project.

$ rake spec
$ rake spec:emulator
$ rake spec:device

This command compiles a special version of your app that includes the spec framework, helpers and files and executes it in the emulator in the background, or in the connected device.

Once the specs are performed, the program yields back to the command-line prompt with a proper status code (0 in case of success, 1 otherwise).

1.4. Run Selected Spec Files

Sometimes you may not want to run the entire test suite but only one or more isolated spec files.

The files environment variable can be set to a series of comma-delimited patterns in order to filter the spec files that should be executed. Patterns can be either the basename of a spec file (without the file extension) or its path.

As an example, the following command will only run the spec/foo_spec.rb and spec/bar_spec.rb files.

$ rake spec files=foo_spec,spec/bar_spec.rb

1.5. Output Format

It is possible to customize the output format of rake spec by specifying a value for the output environment variable. Possible output formats are: spec_dox (default), fast, test_unit, tap and knock.

$ rake spec output=test_unit

2. Basic Testing

You can refer to MacBacon’s README file for a list of assertions and core predicates that the framework supports.

3. Activity Testing

The spec framework exposes a reference to the main Android activity with the main_activity method.

This method is always available in the context of a spec, and you can use it to retrieve references to UI elements in your project, and start testing them.

we will provide a higher-level library for Android UI testing (similar to what we have for iOS) in a future version of RubyMotion.