Welcome to the Robolectric Annotation Processor project.
The Robolectric Annotation Processor (RAP) is an annotation processor that uses Java's built-in annotation processing capability (introduced in Java 6) to make Robolectric development easier. It does this in two ways:
These are discussed in more detail below.
Robolectric has a large amount of boilerplate code in the form of the shadowOf() methods that form a convenient type-safe wrapper around the shadowOf_() base method. This is boilerplate code that must be kept in sync with the actual state of the shadows and imposes extra maintenance overhead. RAP can generate these methods automatically using the information contained in the annotations on the shadows.
The test-driven development process typically takes the form of a series of concentric circles:
Each of these stages may uncover problems that require looping back to the first stage (development). As each of these stages represents a progressively more advanced stage of development, with correspondingly higher overheads involved if a return to the development stage is required. So in the interests of maximizing development efficiency it is best to catch as many bugs as possible as early as possible in the cycle. Why wait to find a bug at integration test time that could have been tested for at unit testing time, or better still at compile time?
RAP employs this philosophy and attempts to shorten the development cycle by moving some tests to compile time. There are a number of usages and constraints implicit in Robolectric's annotation model that cannot be expressed using the simple type system in the annotations themselves. RAP detects violations of these constraints and enforces them at compile time, short-circuiting the need for unit tests or integration tests.
Constraints currently enforced by RAP are:
As an added bonus, when RAP reports an error to its tooling environment, the tooling environment will give feedback on where in the source the error is. In Eclipse (and presumably other modern IDEs like IntelliJ), errors detected by RAP will be reported in the editor with the standard error markers, and mouse-overing them will tell you what the error is. This typically happens immediately when you save a document.
One of the benefits of RAP is that it enables things to be done at compile time instead of runtime. For example, there are two ways that global reset can be implemented:
The first is more efficient at runtime but imposes an extra maintenance burden, because the developer needs to remember to add calls to reset methods here when they add new resets. The second is requires less maintenance, but imposes an extra runtime overhead.
RAP allows you to have the best of both worlds - it will automatically find all reset methods and generate a global reset() method that statically invokes them all. Because reset() is called for each and every individual test, improvements in its performance can make a noticeable difference to a fixture's performance.
There are likely other opportunities for this sort of optimization in Robolectric using RAP, which could be the subject of a future expansion.
In this early stage, RAP is mostly targeted at those contributing to Robolectric itself. Those who wish to do so will simply need to check out the relevant branch of the Robolectric repository, which will already have the pom.xml file configured appropriately.
However, with some few modifications some of the features (such as the constraint enforcement, or custom shadowOf()/global reset() methods) could also be of benefit to users of Robolectric who are developing their own custom shadows. This feature may be added in a future version
In developing RAP I forsaw a number of enhancements that would be potentially useful:
A special thanks to the Robolectric team (both its original authors and current maintainers) for producing such a useful tool for test-driven Android development.
I started my professional career as a software engineer, and more recently was ordained an Orthodox Christian priest. For now I still works as a software engineer while assisting at my parish in a part-time capacity. I try to employ my engineering experience in ways that might assist my parish (the Holy Monastery of St Nectarios, Adelaide).
Like Robolectric itself, RAP is free software distributed under the MIT license.
However, as a priest I feel that everything I do must be in service of my ministry, and so I also developed RAP partially in the hope that appreciative users might find it in their hearts to make a financial contribution to our parish as an expression of their appreciation. Please visit our website for details: the Holy Monastery of St Nectarios, Adelaide.