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. 

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 🙂

Mocking Bound Services on Android

Let’s suppose we have a Fragment that we want to unit test.
However, let’s also suppose that this fragment binds to/unbinds from a service through its lifecycle callback (onStart(), onStop()).

The main advantage of Bound Service  is that the latter lives only if at least one client is bound to it. By binding to/unbinding from a Service through a Fragment or Activity’s lifecycle, we are in full control of the existence of that Service and triggers it only when the user needs it.

To use a bound service, you mainly need 2 classes : an Android Service and a ServiceConnection that monitors the state of the service connection (Service connected/disconnected).

Below a very simple Service and ServiceConnection :

 

As you can see, as soon as the service is created, an expensive task is triggered within the onCreate() callback.

To bind to the service, we will make proper use of the ServiceConnector within our Fragment’s life cycle :

The Unit Test

As we have already seen, as soon as the service is created, an expensive task is triggered within the onCreate() callback. This could lead to pollute and add uncertainty to the result of our unit test (such as the IBinder being null within the onServiceConnected() callback). Just to remind you, a good unit test should be consistent, which means that it should always return the same result for the same test.

So in order not to be disrupted by the Service, we are goind to mock not only the Service, but also stub the IBinder. Thus, anytime a client (the fragment in our case) wants to bind to the Service, it will receive a stub IBinder that will return a mock Service.
Let’s have a look to the Unit Test (we will use Robolectric and Mockito to do so ) and specifically to the mockBoundLocalService() method:

The Robolectric’s ShadowApplication object has a method called setComponentNameAndServiceForBindService() that allows to set a IBinder for the given Service ComponentName. Using this setter, we are able to pass a stub IBinder within the onServiceConnected() callback whenever a client tries to bind to our service.

 

Custom attributes for custom Android Component

Let’s suppose you need to create a custom view or a custom fragment.

These components could be inflated by xml or instancited programmatically.
In case they are inflated, you could have the need to pass custom attributes to define a initial state of your component.

For example : you wanted to create a custom Fragment (call it MyFragment) that manipulates a string and an integer.

#1. declare your attributes in res/attrs.xml as follow:

As you can see, each attribute requires a format, which can be one of the followings :


#2. In you layout (where you declare your fragment), add your custom attributes to your component:

There, you need to be carefull to add a new namespace :

The value of the namespace (‘options’) could be anything you want.

#3. Extract these attributes from your fragment :
If you check the Fragment API reference, the only callback where you could deal with custom attributes is the onInflate() method

As described, this callback should only be responsible for extracting the attributes :

 » all you should do here is parse the attributes and save them away. »

Let’s suppose I have a Business Object called Company

All I have to do is parsing the attributes and creating my Company BO within onInflate() method as follow:

 

#4. Testing
I should have started by writing in TDD but I wanted to describe the attributes definition and parsing first. The following Unit Tests will use Junit4, Mockito as well as Robolectric (tested with 2.2).

The onInflate() method needs an activity instance to properly fetch the attributes. So we will create an Activity instance first.

Our Unit Test will consist in testing that the Company BO is properly created when onInflate() method is called.

To do so, we will populate a list of attributes that we will pass as parameter to onInflate by using RoboAttributeSet;


# How about custom views ?

The previous steps remain identical (attrs.xml, extraction) for views apart from the method where the parsing occurs. Indeed, in Views, you can parse the custom attributes from the constructor itself .

# Conclusion

Creating custom components often requires custom attributes to precisely initiate that component. What is really interesting here is the ability to properly test the parsing of the attributes using RoboAttributeSet component.

What are you doing Google ? #3

This is the third post of a looooong list regarding what I do not agree with the Android source code.
I have the chance to create Android applications, so I regularly read codes, good ones as well as bad ones…

What is my goal of doing so ?
I give myself the freedom to criticize what Google do because, as a developer, we have to improve days after days! Improving means not only practicing, but also
exploring and studying quality open source projects. So either we have to study the right stuff, or we have to highlight what is wrong!
Btw, don’t misunderstand me, I like Google projects !

Naming consistency
Let’s talk in this post about naming consistency. To do so, we will take the MotionEvent class from the android project.
As stated in the documentation, « [MotionEvent is] used to report movement (mouse, pen, finger, trackball) events »
I am currently writing another post which will deeply describe the android touch mechanism (some teasing now 🙂 but here is the big picture :
A MotionEvent holds an action (down, up, move…). It also holds a set of axis values which represent individual fingers position(in multi touch environment).
Each finger in the set has an unique id, called pointerId. However, each finger in that set has also an index that could vary within 2 MotionEvents.

So as you can second guess, the MotionEvent object exposes methods to get the pointerId (unique value) from a varying pointerIndex.
This method is the following : public final int getPointerId (int pointerIndex)

Here, the method is quiet clean and explicite : it requires a pointerIndex as a parameter and returns the pointerId. So your sense of developer will naturaly guide you to look
for a method called getPointerIndex() from the MotionEvent object, so you could feed the previous getPointerId(int pointerIndex) method.

Guess what? No such method!
At least, no such method having this name. Yeah, why being simple and consistent when we can complexify things?
Just dig a bit and you will find a method called public final int getActionIndex ()
The documentation says : « [getActionIndex ()] returns the associated pointer index. » Well, this is exactly what we are looking for but why on earth
the name of the method (actionIndex) is unconsistent with the value returned (pointerIndex) as well as from the documentation ? This is all the more frustrating as the parameter of the previous method needs this value named differently.

So, the code we need is the following :
int pointerIndex = event.getActionIndex();
int pointerId = event.getPointerId(pointerIndex) ;

A good code is a code which has lots of specificities. Readability, naming, consistency.

As much as possible, be rigorous with yourself and don’t neglect these simple little naming consistencies.

What do you think ?