Robolectric 3.0 and shadows

Some time ago (end of 2015), I created an open source project called RxGoogleAuthentication that aims to easily get an authentication token for the Google Apis, based on OAuth2 protocol.

As all of my open source project, I never ship a code without a certain quality, and that includes proper unit testing. Shipping a project without at least that, is a lack of responsibility I think. From my point of view, a developper should be responsible of producing good code quality, or at least trying to do so. Moreover, your code could now be integrated by others on their own projects, so this is all the more important that some quality is there.

Shadows ?

To do my Unit Testing, as most of android developers, I use the Robolectric framework. I won’t get into the benefit of this framework, so you can have a look at their landing pages, but the absolute crucial one for me is that it runs on the jvm, outside the emulator. The downside of that is that you don’t have the entire Android environment which you can’t use, which is problematic in some cases.

Indeed, your tests can require to rely upon the behavior of Android components that are not available as the Android OS is not there.

To compensate that, Robolectric gave you the ability to extend the behavior of Android classes and expose them into the testing environment. These extensions of classes are called « Shadows » .

As you can read on the documentation« When an Android class is instantiated, Robolectric looks for a corresponding shadow class, and if it finds one it creates a shadow object to associate with it. Every time a method is invoked on an Android class, Robolectric ensures that the shadow class’ corresponding method is invoked first (if there is one) »

This is really powerful in a way that you can control the behavior of a Shadow Class and also add missing Shadows.

Concrete use case 

The open source project introduced at the beginning of this article is using the GoogleAuthUtil class, and more specifically the getToken() methods.

At the time I did that shadow, Robolectric didn’t have it. But it seems to have added it 5 days ago, before writing this article.

Anyway, let’s get into the entire process of creating this shadow in concrete and practical term so this would be a great learning case.

#1 Create the shadow class

To create our shadow, the convention is to prefix « Shadow » term to our class name, in our case our shadow would be ShadowGoogleAuthUtil.

The shadow class  should be annotated with the @Implements annotation whereas the methods should be annotated with the @Implementation annotation.

In our precise case, the getToken() methods of our shadow class will return a simple token string, without caring of the internal behaviour of what the authentic GoogleAuthUtil would have done. What matters to us is the output, namely having a token string.

 

#2 Create the custom runner

We have to declare, within a custom runner, the existence of our custom Shadow classes that can be used through Robolectric within the tests classes.

In our case, we have a single custom Shadow that we want to be loaded in the place of the authentic GoogleAuthUtil class.

 

#3 Use shadow class in Unit Tests

Having our shadow class and a custom runner that will load it, we can now use it very simply in our Unit Tests.

The first thing we have to do is of course declare the custom runner to use by using the @RunWith annotation.

Then, we also have to explicitly declare which shadows the class will use thanks to the @Config annotation, through the shadows parameters.

That’s it, whenever we will call GoogleAuthUtil.getToken() method in our tests, the framework will call the method within the shadow class, and as a matter of fact, will return « token » 

 

Conclusion

Shadows are very powerful extensions that let you enhance the Robolectric framework by providing additional or missing behaviour to it.

However, its setting requires few steps that have to be carefully followed to be able to use your custom shadows.

Last thing is: if you are doing a custom shadow, please submit it to the Robolectric project so anybody can benefit from your investment. 

En passant

Android SDK Tools vs Platform Tools vs Build Tools

Well, in order to avoid being confused if you are and android developer, this is just a reminder that hopefully will makes things more clear. 

Typically, SDK Tools are platform independent whereas Platform tools, obviously, support the features of the latest Android Platform. Build Tools gather tools that will produce your signed Apk.

you can get more detailed information from the official documentation

SDK Tools

Roughly, SDK tools include all the tools that you need to develop for android; 

That includes the SDK manager (to download android SDKs), development tools such as AVD (android virtual devices), Image tools (such as draw 9 patch), Debugging tools (such as ddms), monkey runner and so…

It is not an exhaustive list of course. You can open the folder on your machine to get all of the tools.

Platform tools

These tools are updated for each new android sdks release and is backward compatible. The platform tools include for instance ADB which is a bridge that allows you to communicate with your android device or emulator. ADB has to know how to communication with the Android version that is hosted on your device.

Build Tools

The build-tools are used to build your application, that is to produce your APK.
Release notes here and nicely detailed build process here.

Gradle, dependency and Local Repository

If you are an android developer, working on non collaborative projects on your own computer, you have definitely faced the situation where you need to use some piece of software among many projects (mainly utils).

This situation is nothing else than a dependency requirement. So what are our choices to make it smooth ?

step 1 : create an Android library module

I am sure many of you are making copy/paste of piece of sofware from one project to another. Who didn’t, right ?
First of all, get rid of this archaic habit and simply put this reusable software into an android Library module . That’s easy and cheap. Moreover, that gives you the power to make your software evolve peacefully, with adding quality and consistency through time.

step 2 (optional) : make it public and deploy it on maven central

This module is hosted on your computer. You can make the choice to publish your library into github and make the source available to the world. Then, you can simply deploy your artifact to maven central and easily fetch it into any of your project (and let others use it too). To do so, please read my previous article where I detailed the entire process of publishing and deploying an open source project.

But you probably won’t go that far. Your need is to keep your software private but benefit from the gradle dependency mechanism.

step 2 : keep it private

You will probably keep this peace of software private for any valid reason (high end technology you haven’t patented yet oO … or … software not high quality enough …or… pure selfishness…) Whatever the reason is, it’s ok, it’s your decision 🙂
However, even if it is private, do not forget to version your source code into private repository.

step 3 : publish on local directory

The idea here is to publish your artifact into a local directory of your file system. Bear in mind that this directory (used as repository) will host many versions of the same library, and even multiple private libraries, so don’t forget to backup it (using dropbox or google drive for instance) in case you switch computer.

Based on the Gradle Repository Handler documentation, gradle supports many repositories where your project can fetch artifacts. Among them, you can find jCenter(), mavenCentral(), mavenLocal() or any maven() custom repository.

Why don’t we use directly mavenLocal() as our local repository ?
We could of course install our artifact into mavenLocal (/home/.m2/repository) but this repository has another goal. It’s mainly used for caching artifacts to save network requests. Moreover, we loose our sync-ing requirement. Indeed, there is no need to backup the the .m2 folder, it’s just non sense.

So we need to choose a local folder of our choice (for instance /Users/turhan/LocalRepository/).

step 3.1 : configure your library’s build.gradle

We have to configure our library’s build.gradle to specify the directory where to deploy our artifact

We have here created the uploadArchives task by defining the repository url where the artifact will be deployed by maven(here it is a local file:// path).
As you can see, we have to include the maven plugin  (highlighted on the first line) so the mavenDeployer can work.
Finally, don’t forget to specify a group, an archiveBaseName as well as a version. And for each release, do not forget to increment the version  (better put it into a variable inside grade).

step 3.2 : upload your artifact

So now, to deploy our artifact into our local directory called LocalRepository, we simply call the task

step 4 : fetch your artifact into your project

step 4.1 : configure the repository url

On any other other project of yours, open the top build.gradle. We will specify there the path to our local repository

step 4.2 : import the dependency

Now, we can easily define our library as a dependency, such any other dependency. Gradle will look into each repositories we have defined (mavenCentral() and or custom local repository)

Conclusion

We could have installed a Nexus repository locally, but to be honest with you, this is overkill (credentials + web server & so) for our need (non collaborative projects). We need something that could be setup quickly, something that could be backuped easily.
The setup detailed here is not complicated at all and gives you the opportunity to manage your private dependencies easily.
I hope you could save some time with that and make your development process more smooth.

Enjoy 🙂

 

AlarmManager Unit Test using Robolectric 3.0

Alarm Manager feature

AlarmManager is an Android component available since API level 1.

I wanted to use this component in the following scenario :
– automatic and repeated triggers that ignite an operation n times a day
– any new scheduling should cancel previous ones (to avoid unconsistent multiple calls)
– when the device restarts (boot completed), the scheduling should be activated without running the app hosting the AlarmManager.
– the BootComplete operation is not enabled by default, but programatically.

AlarmManager Unit Tests

# Setting alarm

So I created an AlarmController that simply set repeated alarm and activate/desactivate scheduling on bootcomplete

The setAlarm() function simply triggers a broadcast at the given interval (here one hour).

To test this with Robolectric 3.0, we have to use a shadowAlarmManager that will store the parameters of the scheduled Alarm. We can thus simply test the interval set, the trigger time as well as the alarm type (here elapsed_realtime) of the ScheduledAlarm.

# Ensuring one Alarm at a time

Let’s say we call setAlarm() api multiple times (if called for instance during a lifecycle callback). Then, we have to ensure that only one alarm dealing with the same operation is set, avoiding thus any unconsistent and unnecessary mutliple wakes up.

# Checking Operation triggered by the Alarm

To test which PendingIntent operation is triggered by the Alarm, we have to use now a ShadowPendingIntent which will give, once again, extra information, especially regarding the component.

# Checking Operation triggered by the BroadcastReceiver

Our broadcast receiver has 2 goals : setting the alarm if BootCompleted and triggering a service (hosting the operation).

To Unit Test that the service is properly started when broadcast is received, we have, once again, to shadow application so we can access to startedServices.

# Checking BroadcastReceiver will init Alarm on BootCompleted

To Unit Test that the Alarm is properly set onBootComplete, we simply verify, using mockito, the colloboration between the System Under Test (namely the BroadcastReceiver) and the AlarmController

#Activating / Desactivating Broadcast receiver on Demand

As you know, a Broadcast Receiver is a main component of Android Architecture and any receivers should be declared in the Android Manifest. However, let’s suppose we want to activate our broadcast receiver only in a particular scenario  (after an in-app purchase for instance  or only during specific lifecycle callbacks), then how to proceed ?

To do so, we have to declare the Broadcast receiver with the enable=false flag. This gives us the control on programatically enabling/disabling the receiver. Then, we can use the Android PackageManager and set the state of our component (namely the receiver) on demand, as follow :

To Unit Test this with Robolectric 3.0+, we rely on the RobolectricPackageManager accessible through the RuntimeEnvironment object. This will give access to any component state, especially the one we are interested in (our receiver).

 

Android Unit Test : source code on Github

I have create a new Open Source Project called Android Unit Test including this Alarm Manager testing. This project will gather interesting Android Unit Test scenario using Robolectric 3.0, Juni4.+, Mockito 1.9.+

Writing quality Unit Tests on Android requires sometimes quite struggling. This is why this open source project will help you save some time hopefully.

Reactive Directory Chooser – An Open Source journey

I am developing applications for years now, but only in professional area, where everything you produced is proprietary, and does not belong to you, but to the client who paids or employs you…
So I have decided to publish a simple Android library, just to experiment the journey of open source. But you’ll see, this journey is not as marvelous as it looks like, but definitely worth it, especially for the learning process.

The library

Most of the android applications save data to the external storage of the device. The storage location is often empirically defined by the application itself. It would be better to give back the control to the user; the latter should be able to choose the folder in which he wants to save his data. To do so, the user should be able to navigate through the external storage, create custom folders if he needs to and select the appropriate one for his needs.
The library I have created, called Reactive Directory Chooser, answers these needs; It is available on GitHub and Maven Central.
There is, of course, no need to reinvent the wheel, so obviously I checked first. Others libraries exist out there but were not exactly matching my requirements.

The requirements

The required functionalities are basic :
– listing folder’s content (content should be folders only)
– navigating from one folder to another
– creating folder
– notifying client of the selected folder.

Based on the current Android Dashboard (march 2015), it worths supporting back from android API 10 (gingerbread, almost 6% of the market) to the latest known API 22.
The others available libraries on the market are only supporting starting from honeycomb (API 11), which is sadly a waste.

Technical side

– RxJava (Observers, Observable, Operation)

The operations of listing a folder and creating a folder are quite simple. But obviously, these operations have to be processed asynchronously. More over, as we wanted to only display folders (and not regular files), there is here a process of filtering.
Technically speaking, Reactive Programming is a proper answer to these operations : indeed, we can easily trigger operation in an IO thread for instance and also filter the stream to keep only folder type files.
I am a convinced advocate of Reactive Programming (check my conference given in 2014 during AndroidDeveloperDays). Many frameworks exist out there, but the only one I have tested so far is RxJava.
How I proceed ? I isolate the Observable, which produces items asynchronously , from the Observer, that consumes the items in the Android main Thread. These object are encapsulated into Operation objects that trigger the computation on demand, with canceling the previous one if still processing.

– Clean code

As a developer, I try to continuously improve myself as much as possible, and believe me, producing clean code is not easy but so challenging, a life long journey.
The first question I ask myself is « what is the responsibility of this object ? », trying to keep in mind the Single Responsibility Principle. This really is a starting point that will keep your code from being insignicantly polluted. When I review code, from other open source projects for instance, I am really upset/sad/annoyed to see classes that are very long, mixing all kind of non sense operations… This should end! As open source developer, we have a huge responsibility. Our duty is to try to donate to the community good examples of codes, otherwise how will we improve ? Remember, improve every single day if you could. I am not saying the code I produce is clean nor perfect, I’m just saying that I try to make the effort in that way.

Another point that I try to give importance is to keep modules of your software independent from each other as much as possible; in other word, uncoupling objects. For this part, using a Bus, such as EventBus, is a proper answer from my point of view. It lets independent objects producing event and others consuming events.

– Coding

I first started to develop the backend side, then the UI and finally wiring up all.
I like this approach in the fact that they are independent, and force you to properly split your modules. This also gives you the freedom to adapt or change your UI more easily. Also, most of the time, when you deal with UI, you have a great chance to apply the MVC or MVP pattern.
Keep in mind that Fragment or Activity are not exactly controller, their main responsability is to deal with lifecycle callbacks as well as saving/restoring ui states (if not delegated to the low level UI widget).

– Unit Testing

I shouldn’t dissociate Unit Test from coding, because Unit Test are important piece of code. On the contrary, I’ve done that to highlight its importance. Applied in Test Driven Development practice, it gives you a high level of understanding of your object and gives you pointers on how to properly apply Single Responsibility Principle. I am a huge fan of TDD even if, I confess, I’m not applying it everytime, especially when dealing with Android components. However, depending on the quality of the code you want to produce, Unit Test are mandatory. It’s also a good documentation for the developer and could prevent from breaking code. So lots of benefits as you can see.
For the Unit tests, I am using Robolectric in combination with Mockito.
The latest Version of Android Studio as well as the Android Gradle Plugin brings support for Unit Testing within the IDE. However, you need to follow this process first. As an android developer, I start feeling annoyed when I have constantly to configure my IDE whenever a new release is on the air.
Then, you need to explicitly add the roboletric gradle plugin to your root build.gradle file, such as :

It’s not finished; you have to apply the ‘org.robolectric’ plugin to the build.gradle file of your module, as described in the documentation.

Also, in order to let Robolectric find the Manifest and properly plays the tests, we need to annotate our testing classes such as :

Finally, if you are a mac user, you need to make another configuration to the IDE, as follow.

Some configuration again that is a waste, blocking you to directly create value.

– Fresh UI

This open source library has been the opportunity to properly implement fresh and interesting components such as RecyclerView, CardView, FloatingActionButton.

– Code Review

I was working alone on the project. So it is important that you ask to friends or other developer to try to review your code. This gives you a very important feedback that could considerably improve the quality of your code.

Continous Integration

It’s very important, when you change your code (and this will happen a lot) that you prevent your change from integration issues. This could easily be detected, with modern and common practice called Continuous Integration. Of course, with no or few tests on your code, continuous integration is useless. But once set up, it’s very convenient.
My Open Source library is hosted on github. I decided to go with TravisCI service, cause it is free, integrated with GitHub and support Android.
Travis is very easy to use. After being signed and linked your github account to the service, you just have to add a « .travis.yml » file to your repository such as described in the documentation. As an example, my travis.yml file looks like :

It simply says to use or to install required version of android, extras & so… Very easy. Then, whenever you push a commit to your repository, a travis job will be triggered.

Publishing on Maven Central

– Process

Pushing your code publicly to github is one step. To make it available on Maven Central as Open Source Software Repository Hosting (OSSRH) is another step. The process requires few steps that could unfortunately take some time. The precise process is as follow :
– First, we need to create an account and a Ticket to provide project information. This will create you a dedicated groupId.
– Then we need to generate signing keys as explained in the requirement pages . To do so, we need to download and install gpg
– We need then to configure our build.gradle to define the uploadTask, as described here.
– Then, we can upload our AAR module by calling the uploadArchives task :

Finally, once deployed to OSSRH, we need to get the component public by closing and releasing the artifact.

As you can see, the process is quite long for the first time. But once set up, you only need to call the uploadArchives task (of course, increase your build version first inside your build.gradle) then make your component public and that’s it.

– Issues and Solutions

#1 SemVer

When trying to release for the first time, the deployment fails. It was due to the fact that the dependencies of my module was using the Semantic Versioning + notation for the patch, such as :

To fix this failure, we have to explicitly set the version, without permissivity, such as :

Unfortunately, by doing this, we loose all the benefits of being permissive with dependency.

#2 transitive dependency

Once deployed publicly, I try to include the freshly released AAR artifact inside another empty android project, by adding this dependency :

However, no matter what, the dependencies of my dependencies were not present. There is probably an issue between the android studio version vs the gradle version of the wrapper vs the android gradle plugin version… The only solution I have found so far is to explicitely enable transitivity when setting dependency, such as :

#3 Unit Testing not working first time

It could happen that the tests are not working on the first launch. This is a know bug. Simply run on your terminal $ ./gradlew clean test

The License

Just for fun, I have decided to create my own license instead of going with traditional license such as gpl or so. This new license is called the « THE VIRGIN-MOJITO-WARE LICENSE » and is highly inspired from the BeerWare License.

Conclusion

Woaa! It’s done now, I can feel released to have gone through all this process.
There is a huge difference between coding on your own computer and hiding the software somewhere in the hard drive, versus making the code available to anyone. Your code belongs now to anyone. The way you code and you designed your application is open to any review. Constructive or not. If you have a big ego, this could be disturbing. But from my point of view, we have to be very humble and I think that any kind of review could only gives you one step forward for self improvement.
It has actually been a very pleasant exercice, even if I was frustrated of the development environment. I spend more time setting up environment (especially for testing, deployment and transitive dependency issue) than creating my code, the value. To be honest with you, I probably have spent 3,5 mornings for coding the entire library and sample (from unit test, designing software architecture, coding in a reactive programming paradigm, learning components that I haven’t used before (such as RecyclerView) to the entire UI).
I hope you’ll find useful information in this post and also hope that the issues I’ve gone through could save you some time. Do not hesitate to use the library, or even better, to review and improve it 🙂

Saving Fragment State on Configuration Change

prerequisite
Fragment Component
Fragment lifecycle

What I needed :
As you know (if not, please read the prerequisite first), the Fragment lifecycle is highly tied to the activity lifecycle. That said, my need was simply to retain some state of my Fragment and restore it later on after a recreation. A typical scenario is when user rotates screen.
To do so, one needs to override onSaveInstanceState method of the Fragment and save any value into a Bundle, as follow :

The saved Bundle could be retrieved during either onCreate(), onCreateView(), onViewCreated(), onActivityCreated() or onViewStateRestored() callbacks.

What was the problem ?
In my case, the saved bundle was always null in any of the callbacks listed above, although I properly called onSaveInstanceState().

How to solve it ?
Firstly, my Activity’s layout looked like this :

What was missing here is an android:id field within my fragment so Android could recognize the stored Fragment! We simply correct the layout as follow :

As described in the documentation,

Each fragment requires a unique identifier that the system can use to restore the fragment if the activity is restarted (and which you can use to capture the fragment to perform transactions, such as remove it). There are three ways to provide an ID for a fragment:
Supply the android:id attribute with a unique ID.
Supply the android:tag attribute with a unique string.
If you provide neither of the previous two, the system uses the ID of the container view.

Conclusion
In a word, always feed your fragment with an identifier !