Installation

A prototype has been tested using following software versions, but it should work on other versions as well.

• Download and install Eclipse for Java Developers from http://www.eclipse.org/downloads (recommended 4.2; use at least 3.6.2)
• Download and install Android SDK from http://developer.android.com/sdk/index.html (version 20.0.3; use at least version 8)
• Download Clover-for-Android from   http://www.atlassian.com/software/clover/downloads/binary/com.cenqua.clover.android_3.1.7.v20120920000000.zip
• Run Eclipse and install (Help > Install New Software > Add ...)
  
  • Google ADT from https://dl-ssl.google.com/android/eclipse/ update site (version 20.0.3); don't select NDK Plugins to avoid download of Eclipse CDT
    
  • Clover-for-Android from downloaded zip file
    

Note: Clover-for-Android is based on the Clover-for-Eclipse 3.1.7.

Note: Clover-for-Android is using 'adb' application to fetch coverage data from a device. It expects to find it in:

• <sdk>/platform-tools/adb.exe  (on Windows)
• <sdk>\platform-tools\adb        (on other operating systems)

Please note that location of 'adb' has changed from <sdk>/tools to <sdk>/platform-tools since SDK v 8, so please don't use older SDK versions. Value of <sdk> is being fetched from 'com.android.ide.eclipse.adt.sdk' property in Eclipse Preferences ("Window > Preferences > Android > Android SDK").

Note: Clover-for-Android has been tested on a following configuration:

• Windows7 (64-bit) + Eclipse 4.2 for Java + JDK7 + ADT 20.0.3

Clover-for-Android vs Clover-for-Eclipse

Clover for Android has following differences, compared to base Clover for Eclipse:

• The "initstring" can be expressed as URI
• The "Refresh Coverage Data" button fetches coverage data from Android device
• The "Delete Coverage Data" button deletes coverage data from Android device
• The CLOVER_RUNTIME library (plugins/com.cenqua.clover.runtime*.jar) size has been drastically reduced in order to make it deployable on android devices
• There is no need to copy clover.db and clover.jar for application execution

A following features were not tested on Clover for Android:

• Distributed Coverage feature (i.e. sending coverage data via network socket from android device)
• Test Optimization

A following features do not work currently:

• Test Coverage Contribution view does not work when tests are kept in a separate project
• Test optimization does not work if tests are kept in a separate project (this does not work in Clover-for-Eclipse too, because Clover does not support cross-project test optimization)

Usage

Building Android application with Clover

1) Run Eclipse and open your Android project.

2) Right click on the project, select "Clover > Enable on this project" from context menu. 

3) Right click on the project, select "Properties > Clover". Toggle on "Enable Clover in this project". Next select "Custom value" radio button and enter a path to Clover database in a following format:

clover+remote:file:///<path to database file on desktop>?localCoverageDir=<path to coverage directory on device>

Click OK. All Clover views shall be added to current perspective. You can also open them from "Window > Show view > Other ... > Clover".

Possible InitString formats:

• • plain path (absolute or relative) - for Java
  • URI: clover+remote:file:///<path to database file on desktop>?localCoverageDir=<path to coverage directory on device> - for Android
  • URI: clover+local:file:///<path to database file on desktop> - for Java

Keep in mind that for URIs:

• • on Windows platform you must encode ":" and "\" characters to make the initstring URI-compliant
    

    • : = %3A

    • \ = %5C

  • your must have file:/// with three slashes (because in URI format after two slashes we have a host name, which is not our case)

Examples:

• • clover+remote:file:///c%3A%5CTemp%5Candroid.db?localCoverageDir=/data/data/com.example.android.notepad/clover
    with "Relative to project dir" disabled
    remote coverage, database c:\Temp\android.db on Windows, coverage files in /data/data/com.example.android.notepad/clover on Android device,
    
    
  • clover+remote:file:///home/alice/workspace/android.db?localCoverageDir=/data/data/com.example.android.notepad/clover
    with "Relative to project dir" disabled
    remote coverage, database /home/alice/android.db on Unix/MacOS, coverage files in /data/data/com.example.android.notepad/clover on Android device,
    
    
  • clover+local:file:///c%3A%5CTemp%5Cclover.db
    with "Relative to project dir" disabled
    local coverage, database c:\Temp\clover.db on Windows
    
    
  • clover/clover.db
    with "Relative to project dir" enabled
    local coverage, database <project_directory>/clover/clover.db
    
    
  • c:\Temp\clover.db
    with "Relative to project dir" disabled
    local coverage, database c:\Temp\clover.db on Windows

4) Change the flush policy to "At set intervals from a Clover thread" or "At set intervals" and define interval (1000 ms for example).

Note that when you close application on Android device, JVM is still running, thus the "At JVM shutdown ..." option is not preferred.

You can also trigger Clover flush programaticaly - just put "///CLOVER:FLUSH" inline comment in your code (for example in Activity.onDestroy() method).

5) Open "Project Properties > Java Build Path > Order and Export". You will find a CLOVER_RUNTIME library on a list. Enable the checkbox so that Clover library will be exported. Perform a full rebuild of the project. You should see "red coverage" in source files and in Coverage Explorer.

Running instrumented application on a device or emulator

1) Select "Run as ... > Android application" from main menu or Package Explorer context menu. You can execute your application or unit tests on a real device or simulator. Choose device you wish to use.

There is no need to copy the clover.db to a device (yay!). Clover-for-Android is using a special coverage recorder version, which does not require presence of this database.

There is also no need to copy clover.jar to a device (yay!). Google Android Toolkit will automatically package CLOVER_RUNTIME jar file into Dalvik image during packaging.

Running unit tests on a device or emulator

Option #1

Unit tests for Android are kept in a separate Eclipse project.

For such scenario we have found a following configuration which works:

• add application project to Java Build Path in the test project ("Project Properties > Java Build Path > Projects > Add ...")
• enable Clover in the test project ("Project Properties > Clover > Enable on this project toggle")
• configure InitString ("Project Properties > Clover > Instrumentation tab > Initstring box")
  
  • use "clover+remote:" URI as for application project
  • use ?localCoverageDir= value the same as for application project (for example "/data/data/com.my.app")
    
    • we've found some problems with permissions when trying to write to default data directory for test application (for example "/data/data/com.my.app.tests")
  • use database name different than used for application project (e.g. "/tmp/clover-tests.db")
    
    • you cannot use the same database name in two Eclipse projects
      
• configure flush policy ("Project Properties > Clover > Instrumentation tab > Flush Policy box")
  
  • choose "At JVM shutdown and on special instruction"
• add the "///CLOVER:FLUSH" inline comment in tearDown() method for all JUnit test cases (or at least in the last test case executed) - see example below
  
• perform full rebuild of both projects
  

Right click on the test project and select "Run as ... > Android JUnit Test". After tests are finished, select both projects in "Coverage Explorer" view and click "Refresh Coverage Data" button for each of them.

You shall see coverage results for both projects.

Option #2

Unit tests are kept together with application code in one Eclipse project.

Configuration not tested yet.

Retrieving coverage data from a device

Just click on the "Refresh Coverage Data" button

Clover is using "adb" command to retrieve coverage files from the default device. Make sure that you're running one device only, otherwise you might fetch coverage snapshots from wrong device.

Viewing coverage results

As soon coverage data is fetched from device you can browse them using Coverage Explorer or Test Run Explorer view. It is also possible to generate HTML/XML/PDF reports, as usual.

Cleaning coverage data

When you click on the "Delete Coverage Recordings", Clover will remove files from desktop as well as from android device.

Clover is deleting coverage files from a location defined in initstring. In case when initstring has changed, you have to remove files manually - open the "File Explorer" view from "DDMS" perspective and navigate to a directory where coverage data was stored (usually it will be /data/data/com.my.application.name/clover).

Clover is using "adb" command to delete coverage files from the default device. Make sure that you're running one device only, otherwise you might delete coverage snapshots from wrong device.

Example 1 - manual testing

Open "File > New ... > Project ... > Android > Android Sample Project" and click "Next". Choose "Android 2.3.3" build target and click "Next". Choose "Notepad" sample, name it "NotePad" and click Finish.

Right click on the project, select "Clover > Enable on this project" from context menu. All Clover views shall be added to current perspective. You can also open them from "Window > Show view > Other ... > Clover".

Open "Project Properties > Java Build Path > Order and Export". You will find a CLOVER_RUNTIME on a list. Tick the checkbox so that library will be exported.

Open "Project Properties > Clover". Set "clover+remote:file:///c%3A%5CTemp%5Candroid.db?localCoverageDir=/data/data/com.example.android.notepad/clover" initstring. Disable "Relative to project dir" checkbox. Set flush policy to "At set intervals from a Clover thread" with 1000 ms interval. Click OK.

Perform full rebuild. You should see red coverage in Coverage Explorer and text editors as on picture below.

Now let's run the application on Android device. Right click on the project, select "Run as > Android application". Wait few minutes until emulator starts and installs our app.

Add new notes, delete it, change title etc. Exit application.

Click "Refresh Coverage Data" button in Coverage Explorer view. After few seconds you shall see coverage data like on picture below:

You can browse coverage in IDE as well as generate XML/PDF/HTML reports, for example:

Example 2 - unit testing

Prerequisite: "NotePad" project configured as in Example 1.

Open "File > New ... > Project ... > Android > Android Sample Project" and click "Next". Choose "Android 2.3.3" build target and click "Next". Choose "Notepad > tests" sample, name it "NotePadTests" and click Finish.

Right click on the NotePadTests project in Package Explorer. Open "Project Properties > Java Build Path > Projects". Add "NotePad" project to the list.

Click on the "Order and Export" tab, select NotePad checkbox. Click OK.

Open "Project Properties > Clover". Select "Enable Clover in this project" checkbox.

Set "clover+remote:file:///c%3A%5CTemp%5Candroid-tests.db?localCoverageDir=/data/data/com.example.android.notepad/clover" initstring. Disable "Relative to project dir" checkbox.

Set flush policy to "At JVM shutdown and on special instruction". Click OK and close Properties window.

Note that there is no need to export CLOVER_RUNTIME library, because it's already exported in the NotePad project.

Open NotePadTest class and add a tearDown() method like below:

public void tearDown() throws Exception {
    ///CLOVER:FLUSH
    super.tearDown();
}

Open NotePad/AndroidManifest.xml file and increase required API Level to 8 (it's required by ActivityInstrumentationTestCase2):

<uses-sdk android:minSdkVersion="8" android:targetSdkVersion="8"/>

Perform full rebuild.

Right click on the NotePadTest project, select "Run as ... > Android JUnit Test" from context menu. Wait until tests are finished.

Select NotePad and NotePadTests project in Coverage Explorer and for each of them click on the "Refresh Coverage Data" button.

After few seconds you shall see coverage results similar to those:

Troubleshooting

In case of problems, you can search for more information in following places:

Open "Window > Preferences > Clover". Set "Clover plugin logging output level" to Debug or Verbose. Open Error Log console ("Window > Show view > Error Log"). You can track Clover messages like:

• retrieval of coverage data from device

Executing 'D:\Soft\Android\android-sdk\platform-tools\adb.exe pull 
/data/data/com.example.android.notepad/clover/android-test.dbh3wa8ogtz4si_0_hut67c_h7aira7g.s
 c:\Temp\android-test.dbh3wa8ogtz4si_0_hut67c_h7aira7g.s'

• removal of outdated files

deleting out of date coverage recording file: android-test.dbhut67c_h7air9v5, timestamp < 1348064838148

• loading coverage snapshots

Read header for "c:\Temp\android-test.dbhut7iw_h7aj0xtu": Header[dbVersion=1348064838148, writeTimeStamp=1348064886310, format=0]

•  loading per-test coverage snapshots

Recording data for file "c:\Temp\android-test.dbh4ffemvct3pe_0_hut7iw_h7aj0y4l.s": 
PerTestRecordingTranscript[coverage.size=64, testTypeName='com.example.android.notepad.NotePadTest', 
testMethodName='com.example.android.notepad.NotePadTest.testActivityTestCaseSetUpProperly',
 exitMessage='null', stackTrace='null', exitStatus='Normal', start=1348064884677]

Open "Window > Open perspective > DDMS".

• check messages in the LogCat view
• check if coverage files are written as specified in the FileExplorer view

Known bugs

• CLOV-1194 - Getting issue details... STATUS

Android Project

We are waiting for your feedback! Feel free to vote on implementing full Android support in:

CLOV-569 - Getting issue details... STATUS Clover for Ant

CLOV-570 - Getting issue details... STATUS Clover for Maven 2&3

CLOV-1122 - Getting issue details... STATUS Clover for Eclipse

CLOV-1127 - Getting issue details... STATUS Clover for IDEA

CLOV-1126 - Getting issue details... STATUS Clover Commandline Tools