Author at Infinum

How to Test Custom Lint Checks

Sven Vidak — Thu, 27 Jun 2019 09:30:00 +0000

In my previous article, I’ve talked about writing Lint checks and benefits they can bring to your project. I’ve also outlined how to write custom Lint checks, but I didn’t cover how to test them.

Of course, you can always observe if Lint reports an error or warning if you make a mistake, but the problem arises if you have a bug in your implementation.

Tests help make sure the check behaves correctly in every possible case, but can also help with debugging.

Dependencies

First step is to add test dependencies in your module’s build.gradle file:

testImplementation "com.android.tools.lint:lint:$lintVersion"
testImplementation "com.android.tools.lint:lint-tests:$lintVersion"

lintVersion is defined in the same way as in the previous article – gradlePluginVersion + 23.0.0. At the moment of writing, it would be 26.4.0.

Basic test class

Lint checks are tested with the JUnit framework. The only part that’s a bit different is that your class must extend LintDetectorTest class which will force you to specify detector and issues you want to test. In the previous article, I’ve defined all components that one Lint check has to have. I’ll use those here.

When you extend LintDetectorTest class, you’ll have to implement two methods: getDetector and getIssues.

class CorrectClickListenerDetectorTest : LintDetectorTest() {
    override fun getDetector() = CorrectClickListenerDetector()
    override fun getIssues() = listOf(ISSUE_CLICK_LISTENER)
}

For each test, you’ll need a code sample that Lint will analyze. You can define those in any way you want (as a variable, read from file, etc.), but have in mind there are differences when it comes to Java and Kotlin.

Java code sample must be syntactically correct. For example, you can call non-existing methods on any object and you don’t have to specify imports for used classes, but parenthesis, keywords, etc. must be correct.

private val incorrectMethodCallJava = """
    public class Test {
        private static String s1 = "Test string 1";
        private static String s2 = "Test string 2";

        public static void main(String[] args) {
            s1.setOnClickListener();
            s2.trim();
        }
     }
    """.trimIndent()

As you can see, there are no imports and we call setOnClickListener on a String object which does not make any sense, but Lint is cool with that.

On the other hand, when defining a Kotlin sample code, you have to make sure that the code will compile if you copy it into a real project. Since we are testing method calls on Android View, you have to specify import statement for the View class and somehow obtain instance of that class so you can call a method on it. Luckily, we don’t have to drag beloved Context to our test – it’s enough to have a method that takes a View instance as a parameter.

private val incorrectMethodCallKotlin = """
    import android.view.View
    class Test {
        fun main(view: View) {
            view.setOnClickListener { }
        }
    }
  """.trimIndent()

Have in mind that having import statement in the code sample does not require you to include Android SDK as a testing dependency – all dependencies you need are the two mentioned at the beginning of the article.

First test

Each test is defined as a method annotated with @Test (same as any other JUnit test), It’s written as a chain of commands that tells Lint what to analyze, and what assertions to test.

@Test
fun incorrectMethodUsage_shouldReportAWarning() {
    // obtain Lint analyzer
    lint()
        // give it a list of files to analyze
        .files(java(incorrectMethodCallJava))
        // run analyzer
        .run()
        // make assertions
        .expectWarningCount(1)
}

Kotlin file(s) can be analyzed in the same way, you just have to pass kotlin(incorrectMethodCallKotlin) as a parameter to files method.

More assertions

In the previous article, I’ve defined a quick fix option for a check. Lint testing API allows you to test if the fix works.

private val correctMethodCallJava = """
    public class Test {
      private static String s1 = "Test string 1";
      private static String s2 = "Test string 2";

      public static void main(String[] args) {
          s1.setThrottlingClickListener();
          s2.trim();
      }
    }
""".trimIndent()

@Test
fun fix_shouldUseCorrectClickListener() {
    lint()
        .files(java(incorrectMethodCallJava))
        .run()
        // check that the fix produces the same code as the one given as a second parameter
        .checkFix(null, java(correctMethodCallJava))
}

Also, you can match exact output of your check.

private val incorrectMethodCallWarning = """
    src/Test.java:6: Warning: Use setThrottlingClickListener [UnsafeClickListener]
            s1.setOnClickListener();
            ~~~~~~~~~~~~~~~~~~~~~~~
    0 errors, 1 warnings
""".trimIndent()

@Test
fun incorrectMethodUsage_shouldShowCorrectWarningMessage() {
    lint()
        .files(java(incorrectMethodCallJava))
        .run()
        /* this check is sensitive to indentation so you might have to adjust warning variable a bit due to article formatting */
        .expect(incorrectMethodCallWarning)
}

And, of course, you want to check that your check won’t report any issues.

@Test
fun correctMethodUsage_shouldNotShowAnyWarningMessages() {
    lint()
        .files(java(correctMethodCallJava))
        .run()
        .expectClean()
}

A good starting point

There are many more assertions that enable you to verify the correctness of your check (you can even check whole reports).

The checks in this article can cover a lot of cases which are a good starting point for every type of a check that exists. For those eager to learn more, here you can find tests for XML checks. That’s all folks. Happy testing.

The post How to Test Custom Lint Checks appeared first on Infinum.

What Is Android Lint and How It Helps Write Maintainable Code

Sven Vidak — Thu, 04 Apr 2019 13:00:00 +0000

When developers are not careful enough, things can go south. Classic developer oversights include the usage of an API added in the newer version that is not supported in the old versions, actions that require specific permissions, missing translations, just to name a few.

On top of that, Java, Kotlin, as well as any other programming languages have their own set of programming constructs that might result in poor performance.

Hello, Lint

We use a tool called Lint (or Linter) to prevent such issues. Lint is a tool for static code analysis that helps developers catch potential issues before the code even compiles. It runs multiple checks on the source code that can detect issues like unused variables or function arguments, condition simplification, wrong scopes, undefined variables or functions, poorly optimized code, etc. When we talk about Android development, there are hundreds of existing Lint checks available out-of-the-box.

But sometimes, we need to detect specific issues in our codebase that are not covered by those existing checks.

Hello, custom Lint check

Before we start coding, let’s define our goal and see how to implement each part of that goal in terms of a Lint API. The goal is to create a check to detect the wrong method call on an object. The idea of this check is to detect if the method for setting click listener on an Android View component is the one that will throttle multiple consecutive clicks so we can avoid opening the same activity, or calling an API multiple times.

Custom Lint checks are written as a part of the standard Java (or Kotlin) module. The easiest way to start is to create a simple Gradle-based project (it doesn’t have to be an Android project).

Next, you’d want to add Lint dependencies. In your module’s build.gradle file add:

compileOnly "com.android.tools.lint:lint-api:$lintVersion"
compileOnly "com.android.tools.lint:lint-checks:$lintVersion"

Now, there’s a trick I’ve learned by researching this topic. lintVersion should be gradlePluginVersion + 23.0.0. gradlePluginVersion is a variable defined in root build.gradle project when you create an Android project using Android Studio and at this moment, the latest stable version is 3.3.0. That means that lintVersion should be 26.3.0.

Each Lint check consists of 4 parts:

Issue – the problem in our code we are trying to prevent from happening. When Lint check fails, this is what is reported to the user
Detector – a tool for finding a problem that exposes parts of the source code to us in terms of a Lint API classes
Implementation – scope in which a problem might happen (source file, XML file, compiled code, …)
Registry – custom Lint check registry, which will be used alongside the existing registry that contains predefined checks

Implementation

Let’s start by creating an implementation for our custom check. Each implementation consists of a class that implements a detector and a scope.

val correctClickListenerImplementation = Implementation(CorrectClickListenerDetector::class.java, Scope.JAVA_FILE_SCOPE)

Have in mind that Scope.JAVA_FILE_SCOPE will also work for Kotlin classes.

Issue

The next step is to use this implementation for defining an issue. Each issue consists of several parts:

ID – unique identifier
Description – short (5-6 words) summary of an issue
Explanation – full issue explanation with a suggestion on how to fix it
Category – category of an issue (performance, translation, security, etc.)
Priority – the importance of the issue, in a range from 1 to 10 with 10 being the highest. This will be used to sort issues in a report generated by running Lint task
Severity – a severity of an issue (fatal, error, warning, info, or ignore)
Implementation – implementation that will be used to detect this issue

val ISSUE_CLICK_LISTENER = Issue.create(
    id = "UnsafeClickListener",
    briefDescription = "Unsafe click listener", 
    explanation = """"
        This check ensures you call click listener that is throttled 
        instead of a normal one which does not prevent double clicks.
        """.trimIndent(),
    category = Category.CORRECTNESS,
    priority = 6,
    severity = Severity.WARNING,
    implementation = correctClickListenerImplementation
)

Detector

Lint API offers interfaces for each scope you can define in the implementation. Each of these interfaces exposes methods that you can override and access parts of the code you are interested in.

UastScanner – Java or Kotlin files (UAST – Unified Abstract Syntax Tree)
ClassScanner – compiled files (bytecode)
BinaryResourceScanner – binary resources like bitmaps or res/raw files
ResourceFolderScanner – resources folders (not specific files in them)
XmlScanner – XML files
GradleScanner – Gradle files
OtherFileScanner – everything else

Also, Detector class is a base class that has dummy implementations of all the methods each of the above interfaces exposes so you are not forced to implement a complete interface in case you need only one method.

Now, we are ready to implement a detector that will check the correct method call on an object.

private const val REPORT_MESSAGE = "Use setThrottlingClickListener"

/**
 * Custom detector class that extends base Detector class and specific
 * interface depending on which part of the code we want to analyze.
 */
class CorrectClickListenerDetector : Detector(), Detector.UastScanner {

/**
* Method that defines which elements of the code we want to analyze.
* There are many similar methods for different elements in the code,
* but for our use-case, we want to analyze method calls so we return
* just one element representing method calls.
*/
override fun getApplicableUastTypes(): List<Class<out UElement>>? {
    return listOf<Class<out UElement>>(UCallExpression::class.java)
}

/**
    * Since we’ve defined applicable UAST types, we have to override the
    * method that will create UAST handler for those types.
    * Handler requires implementation of an UElementHandler which is a
    * class that defines a number of different methods that handle
    * element like annotations, breaks, loops, imports, etc. In our case,
    * we’ve defined only call expressions so we override just this one method.
    * Method implementation is pretty straight-forward - it checks if a method
    * that is called has the name we want to avoid and it reports an issue otherwise.
    */
    override fun createUastHandler(context: JavaContext): UElementHandler? {
        return object: UElementHandler() {

            override fun visitCallExpression(node: UCallExpression) {
                if (node.methodName != null && node.methodName?.equals("setOnClickListener", ignoreCase = true) == true) {
                    context.report(ISSUE_CLICK_LISTENER, node, context.getLocation(node), REPORT_MESSAGE, createFix())
                }
            }
        }
    }

    /**
     * Method will create a fix which can be trigger within IDE and
     * it will replace incorrect method with a correct one.
     */
    private fun createFix(): LintFix {
        return fix().replace().text("setOnClickListener").with("setThrottlingClickListener").build()
    }
}

The last thing we need to do is add issues to our registry and tell Lint there is a custom registry of issues that it should use alongside a default one.

class MyIssueRegistry : IssueRegistry() {
    override val issues: List<Issue> = listOf(ISSUE_CLICK_LISTENER)
}

In module’s build.gradle:

jar {
    manifest {
        attributes("Lint-Registry-v2": "co.infinum.lint.MyIssueRegistry")
    }
}

where co.infinum.lint is package of MyIssueRegistry class. Now, you can run jar task using gradlew script and library should appear in build/libs directory.

There is another example of a custom Lint check here where you can see how to process XML files. The general idea is the same for this as for any other check – extend, specify and override functionality you need for the parts of the code that should be analyzed.

Usage

Your brand new Lint check is ready to be used on a project. If this check can be applied to all projects, you can put it in ~/.android/lint folder (you can create it if it doesn’t exist).

Also, you can develop your check as a module in your project and include that module as any other dependency using thelintChecks method. This can also be used if you upload thejar file to Bintray.

Is it worth the trouble?

Lint is a really nice tool every developer should use. The ability to detect potential issues with your code upfront comes in handy. While custom checks are not the easiest to write, mostly due to the complexity of the API, they’re definitely worth it and can save a lot of time and effort down the road.

The post What Is Android Lint and How It Helps Write Maintainable Code appeared first on Infinum.