This documentation is for Clover 4.1.x. Earlier versions are available here.

Skip to end of metadata
Go to start of metadata

It's always hard for us to say no to our customers. However, design decisions are not only about "Do we want to have this feature?" but also "Is this a best feature we can implement using our available resources?". We want to invest our time in making your lives (and code!) better. The fact that Google are building their Android IDE based on IntelliJ IDEA, which has a built-in coverage tool, means that you can measure code coverage for your Android apps, in an environment supported by Google. Therefore, we decided to not implement Clover for Android in the near future.

 

The following article is a rough guideline how you could "hack" Clover to run on Android. Please keep in mind that Atlassian does not provide technical support for Android. See Supported Platforms.

Integration steps

Download:

  • com.atlassian.clover:clover artifact from Maven (version 4.0.6 or higher)
  • com.atlassian.clover:clover-runtime artifact (version 4.0.6 or higher)

Integrate with your build scripts:

  • Bundle com.atlassian.clover:clover-runtime artifact into your application. Do not use com.atlassian.clover:clover - this is because of the 64k method limit on Dalvik VM - the 'clover' artifact (about 15 MB) is too large.
  • Instrument your java sources using Clover - for instance call <clover-instr> Ant task or the CloverInstr command line tool (these classes are available in 'clover' artifact)
    • Use the same path for clover.db on your development machine and on android device/emulator - typical location for data files is /data/data/<application_id>/; it also means that you shall use Linux or MacOS for development and not Windows (due to drive letters) to have the same path.
    • Ensure that the location on device will be write-able
    • Use an absolute path for initstring, e.g. "/data/data/<your_application_id>/clover.db"
    • Set flush policy to "interval" and/or add "///CLOVER:FLUSH" comment on your application shutdown event - this is necessary because by default Clover writes coverage data to disk on JVM shutdown, which doesn't happen on Android.
  • Compile these instrumented sources instead of the original ones and package the application
  • Copy clover.db to /data/data/<your_application_id>... folder - you can use 'adb copy' command for this purpose; an alternative is to use the 'growable coverage recorder'
  • Run the application and/or tests
  • As soon as application terminates, copy coverage recording files back from the device - again, you can use 'adb ls' + 'adb copy' for this purpose
  • Generate an HTML report using Clover database and coverage recording files from a developer machine

Hints

Manual testing

You can also force Clover to write coverage files to disk by putting ///CLOVER:FLUSH inline comment in your code, for example in an Activity.onDestroy() method.

Unit testing

You may need to add "CLOVER:FLUSH" directive in tear-down methods like below (in order to force writing coverage data to disk):

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

 

Troubleshooting

The following features may not work on Android:

  • Per-test coverage (when 'growable coverage recorder' is used)
  • Test Optimization
  • Distributed Coverage

Known bugs

 

  • No labels

10 Comments

  1. Hello!

    I understand that Clover-for-Android is on hold, but I have the following questions:

    1. What is missing from this "prototype"?
    2. Does the current clover for java need an important effort to have it running on Android?
    3. Is it possible to use the current clover for instrumentation of an Android application? If no, why?
    4. Up to which level would this prototype be usable in an production environment? (the simplest scenario possible including a single project with coverage reporting. No optimisation features needed.)

    Thank you

    Best regards,

    Cristian

    1. Hi Christian,

      What is missing from this "prototype"?


      This prototype works, although per-test code coverage does not work for larger projects due to a bug. However:  

      • This prototype has been prepared for Eclipse. Now the Android Studio is based on IntelliJ IDEA. So completely new plugin would be required. 
      • Android projects are now based on Gradle build system. Clover does not support Gradle yet - although we plan to add Gradle support in 2016. 

       

      Does the current clover for java need an important effort to have it running on Android?

      If you would like to use standard Clover to run it on Android, then you would have to do the following:

      • bundle com.atlassian.clover:clover-runtime artifact (available since Clover 4.0.6) into your application instead of the com.atlassian.clover:clover - this is because of the 64k method limit on Dalvik VM - the 'clover' artifact (about 15 MB) is too large
      • instrument your java sources using Clover - for instance to call <clover-instr> from a Gradle script
        • you shall set flush policy to "interval" and/or add "///CLOVER:FLUSH" comment on your application shutdown event - this is necessary because by default Clover writes coverage data to disk on JVM shutdown, which doesn't happen in Android
      • compile these instrumented sources instead of the original ones and package the application
      • use the same path for clover.db on your development machine and on android device/emulator - typical location for data files is /data/data/<application_id>; it means that you'd have to use Linux or MacOS for development to have the same path
      • after deploying instrumented application to your android device you'd have to copy clover.db to /data/data/... folder - you could use 'adb' command for this purpose; an alternative is to use the 'growable coverage recorder'
      • as soon as application terminates, you'd have to copy coverage recording files back from the device - again, you could use 'adb ls' + 'adb copy' for this purpose (this is what this prototype does btw)
      • generate HTML report using Clover database and coverage recording files

      As you can see, it is doable, although it requires a lot of scripting.  

       

      Up to which level would this prototype be usable in an production environment?

      As this prototype is based on Eclipse, it won't work with the latest Android Studio.

      1. Hello Marek,

        Thank you for your detailed answer.

        1. If I understand, one could use the latest Clover software, but in order to have it working, some scripting is needed without any modification of the Clover framework. Am I right?
        2. Also, in our development environment we are still using Eclipse. Would the latest release of Clover-for-Eclipse be adaptable for usage with Android? If so, what is missing?

        Thank you again

        Best regards,
        Cristian

         

        1. If I understand, one could use the latest Clover software, but in order to have it working, some scripting is needed without any modification of the Clover framework. Am I right?

          Correct. There shall be no need to modify Clover itself. Just some scripting to properly handle database and coverage recording files. 

           

          Also, in our development environment we are still using Eclipse. Would the latest release of Clover-for-Eclipse be adaptable for usage with Android? If so, what is missing?

          Probably yes. The Clover-for-Eclipse 4.0.6 has reduced size of the CLOVER_RUNTIME library (you can find this library in project's classpath when Clover is enabled). For this reason it should not exceed Dalvik VM limits (as older Clover versions do). Steps to use Clover-for-Eclipse would be similar as described above: use interval flush policy and/or add ///CLOVER:FLUSH, set proper path to clover.db, copy clover.db to device, deploy app and run tests; as soon as it's finished download coverage recording files, click "Refresh" button in the "Coverage Explorer" view. 

          1. Hello Marek,

            Thank you again for your help.

            We did manage to get the hook running even with ant.

            I have some last questions regarding using standard Clover for Android:

            1. Should the "com.atlassian.clover.eclipse.runtime_4.1.1.v20151207000000.jar" be replacing the "com.cenqua.clover.runtime_3.1.7.v20120920000000.jar" runtime provided with the prototype?
            2. We intend to use the runtime from scripting, with ant. Can you please clarify what should be the usage ? Does the clover-for-eclipse suffice or is the clover-for-ant adding new features?
            3. Finally, how does the Clover Command Line Tools fit into the process?

            Thank you.

            Best regards,

            Cristian

            1. ad 1. Yes. The com.cenqua.clover.runtime JAR was renamed to com.atlassian.clover.eclipse.runtime in Clover 4.0.

               

              ad 2. Clover has several components.

              The Clover Core (com.atlassian.clover:clover Maven artifact) contains all classes necessary for compilation (instrumenting code - both Java and Groovy), runtime (collecting coverage data) and report generation; the Clover Core contains also Ant tasks.

              The Clover Runtime (com.atlassian.clover:clover-runtime Maven artifact) is a subset of Clover Core classes; it contains classes used at runtime only and as such cannot be used to instrument code or generate reports.

              The Clover-for-Eclipse plugin contains classes from Clover Core and Clover Runtime as well as IDE-specific code (views etc).

              In case you would like to use Clover from Ant, then I suggest to just download the Clover-for-Ant ZIP and take clover.jar from it (alternatively, fetch the com.atlassian.clover:clover artifact from Maven) and use it for compilation and reporting. In addition to this, use the Clover runtime (com.atlassian.clover:clover-runtime) JAR to bundle it into your application.

               

              ad 3. Clover command line tools perform exactly the same tasks as other Clover integrations. So the most probably you won't need them, unless need to run Clover without Ant/Maven/Eclipse.

              1. Hello Marek,

                Some more thoughts:

                ad 1. Yes. The com.cenqua.clover.runtime JAR was renamed to com.atlassian.clover.eclipse.runtime in Clover 4.0.

                So, after unziping, one finds under : com.atlassian.clover.eclipse.updatesite_4.1.1.v20151207000000\plugins\com.atlassian.clover.eclipse.runtime_4.1.1.v20151207000000.jar which includes clover-runtime.jar. Is it enough to include the clover-runtime.jar in the project as a resource for having it run?

                ad 2. Clover has several components.

                I have the impression that Clover for eclipse would still be the best point to start from for porting the latest clover for usage on Android. I say this as the different .jar files are already separated and the only task to be done in Ant would be the instrumentation and report generation. Does this make sense?

                ad 3. Clover command line tools perform exactly the same tasks as other Clover integrations.

                Ok, can you please indicate it the following operations could work:

                1. Instrument the source code using clover-instr command line tools :
                  1. --flushinterval and/or --flushpolicy use interval flush policy and/or add ///CLOVER:FLUSH in a function which is for example activity-destroy
                  2. --relative set proper relative initstring path to clover.db
                  3. --distributedCoverage ON : Does this step create the clover.db database on the PC?
                2. include in the apk which will be under test the clover-runtime.jar (704kB) from within com.atlassian.clover.eclipse.updatesite_4.1.1.v20151207000000\plugins\com.atlassian.clover.eclipse.runtime_4.1.1.v20151207000000.jar
                3. build the new apk (based on the instrumented code and the including the clover-runtime.jar)
                4. copy clover.db (created at step 1.c ?) to device, under /data/data/aplication.name/clover.db
                5. deploy app and run tests; as soon as it's finished download coverage recording files, which are stored on the Android device under /data/data/aplication.name/clover.db to the  PC
                6. Optionally run clovermerge in order to merge data from the test run with previous runs
                7. Generate report either by running any of the following:
                  1. ConsoleReporter
                  2. HtmlReporter
                  3. PDFReporter

                Finally, is there a way to have each of the components print their version in command line somehow?

                We intend to use Clover in multiple environments so we might at a certain moment have multiple versions, so we would need to be able know from the test-report which runtime and which command-line programs have been used.

                Thank you for your reply.

                Best regards,
                Cristian

                 

                 

                1. Is it enough to include the clover-runtime.jar in the project as a resource for having it run?

                  Yes. 


                  I have the impression that Clover for eclipse would still be the best point to start from for porting the latest clover for usage on Android. I say this as the different .jar files are already separated and the only task to be done in Ant would be the instrumentation and report generation. 

                  We always aim to release Clover-for-Ant, Clover-for-Eclipse and Clover-for-IDEA at the same time and being compatible with each other. Thus, I don't see a need to use JARs unpacked from Clover-for-Eclipse in your integration in Ant. But it's up to you.



                  1. Instrument the source code using clover-instr command line tools : 
                    1. --flushinterval and/or --flushpolicy use interval flush policy and/or add ///CLOVER:FLUSH in a function which is for example activity-destroy
                    2. --relative set proper relative initstring path to clover.db
                    3. --distributedCoverage ON : Does this step create the clover.db database on the PC?

                   

                  1a. OK

                  1b. I'd recommend using an absolute path. I don't know what is the working directory for apps running on Android. It can be something different than /data/data/...

                  1c. Please don't enable distributed coverage. I did not test it on Android and there's no need to enable it. It won't create a database on PC. Instead of this it will attempt to launch an additional thread listening on specific network port. More details: About Distributed Per-Test Coverage.

                   

                  Points 2-5

                  Sounds OK. Although please note that I recommend using Linux or Mac, not Windows (as there may be a problem with resolving "/data/data/application.name/clover.db" path on Windows - due to a drive letter).

                   

                  6. Optionally run clovermerge in order to merge data from the test run with previous runs

                  Rather not. In case you compile once and run tests many times, then it's enough to just put all coverage recording files in the same folder. In case you recompile the code, then you can re-use the clover.db from a previous build - Clover will update the database accordingly. The CloverMerge tool may be useful if you have many databases (created from different projects) and you'd like to have a single, consolidated report.

                   

                  Point 7. 

                  Sounds OK.

                2. Finally, is there a way to have each of the components print their version in command line somehow?

                  When you call the <clover-setup> / <clover-instr> / CloverInstr it prints information about Clover version, e.g.:

                  [clover-setup] Clover Version 4.1.1, built on ...