Jenkins shared library: Linting and unit testing the library - Part 4

Jenkins shared library: Linting and unit testing the library - Part 4

Building Jenkins Shared Library

~8 min read

A shared library is the one place where a mistake reaches every pipeline at once. A typo in syncBlog doesn't break one build, it breaks every project that calls it the next time they load the library. That makes it the code in my setup that most deserves a safety net, and so far it had none. This post adds two: CodeNarc for linting, and unit tests, both run by the library's own Jenkinsfile.

A Gradle build that only does tooling

The library itself needs no build. Jenkins loads it straight from the repo layout (vars/, src/, resources/). But both CodeNarc and the test framework I wanted are JVM tools, and Gradle is the easiest way to run them, so the repo gets a build.gradle whose only job is tooling. Its one awkward part is that Jenkins' layout isn't Gradle's, so the source sets are pointed at it:

sourceSets {
    main { groovy { srcDirs = ['src'] } }
    vars { groovy { srcDirs = ['vars'] } }
    test { groovy { srcDirs = ['test'] } }
}

main is the plain classes, which compile fine and go on the test classpath. vars exists purely so CodeNarc will scan it: the steps call pipeline methods like sh and withCredentials that don't exist on a normal compile classpath, so compileVarsGroovy is never expected to pass, and nothing runs it.

I committed the Gradle wrapper, so the only thing an agent needs is a JDK.

CodeNarc

CodeNarc is the standard static analyser for Groovy, and it runs as a Gradle task (./gradlew codenarcMain codenarcVars codenarcTest). The part that takes thought is the rule set. The default is large, and the formatting rules in particular flag stylistic things the existing code does on purpose, like aligning the = in a run of def lines. For a first pass I picked the rule sets that find real problems and nothing else: basic, braces, exceptions, imports and unused. Formatting rules can come later, once I've decided what I actually want.

A linter that passes proves little until you've seen it fail, so I dropped a file into vars/ with an unused variable and an empty catch. The build failed and pointed at the report, and the real files passed: six scanned, none with violations. Then it ran on the tests I wrote next and flagged them straight away, for putting import static lines after the normal imports. That was a two-minute fix, and the sort of thing that's nicer to learn from a tool than from a review comment.

Unit testing, in two layers

There are two kinds of code here, and they want different tests.

Classes in src/ (Versioning, Defaults) are plain Groovy, so they get ordinary JUnit tests with no Jenkins involved. Versioning is the more interesting one: it rejects anything that isn't MAJOR.MINOR.PATCH, leaves main and master as the bare version, and turns a branch like feature/Add_Login into 1.4.2-feature-add-login.9. Those are exactly the edge cases that are tedious to check by running a pipeline and trivial to check in a test.

Steps in vars/ can't be tested that way, because they call pipeline steps. This is what JenkinsPipelineUnit is for: it loads a step as a script and lets you register mock implementations of the pipeline methods it calls. For syncBlog, the mocks record what happened:

helper.registerAllowedMethod('withCredentials', [List, Closure]) { List creds, Closure body ->
    credentials = creds
    body()
}
helper.registerAllowedMethod('catchError', [Map, Closure]) { Map opts, Closure body ->
    catchErrorArgs << opts
    body()
}
helper.registerAllowedMethod('sh', [String]) { String script -> scripts << script }

and the tests assert on them. Both Ghost credentials are requested. The default version and repo come from Defaults, and a version: argument overrides the version. --apply appears before --schedule --apply, which is the ordering the step's comment says must never change. The stage is wrapped in catchError by default, and soft: false leaves it out. There are smaller tests for sayHello and notifyBuild, which also loads its template from resources/. I left out standardPipeline, because a declarative pipeline needs a different kind of test.

Three things that weren't in the docs

  • The obvious dependency is the wrong one. JenkinsPipelineUnit's Maven Central artifact stops at version 1.1, which targets Groovy 2.4.6. Current releases (I used 1.31) are published to the Jenkins repository, so build.gradle adds https://repo.jenkins-ci.org/releases/ as a repository.
  • Test against Groovy 2.4, because Jenkins does. Pipeline code on Jenkins runs on Groovy 2.4, so the tests do too, rather than the Groovy 4 Gradle itself uses. It ran fine on the JDK on my laptop.
  • Gradle will quietly skip your tests. The steps and templates are loaded at runtime, not compiled, so Gradle didn't know they were inputs to the test task. After I edited a step, ./gradlew test called itself up to date and ran nothing. I only noticed because I broke syncBlog on purpose to check the tests could fail, and they stayed green. The fix is two lines declaring vars and resources as inputs. With that in place, the same deliberate break fails exactly the two tests that should catch it: the one for ordering and the one for soft: false.

What the tests can't tell you

These tests check that a step calls the right things in the right order with the right arguments. They can't check that uvx accepts that command line, that the credentials exist in Jenkins, or that Jenkins accepts the stage at all. A step can pass every test and still fail on the first real run. Before tagging a release, I'll still point a throwaway pipeline at a branch with @Library('bb-jenkins-shared-lib@my-branch') _.

In the Jenkinsfile

The library's own pipeline now has Lint and Test stages before it publishes this blog. Both use the wrapper, Lint archives the CodeNarc reports and also publishes them with publishHTML, so each build gets a "CodeNarc" link in the job sidebar, and Test publishes the JUnit results. A library change that doesn't lint or doesn't pass its tests never reaches main's Sync blog stage.

Two things on the Jenkins side make that report usable. The HTML Publisher plugin has to be installed, and Jenkins' default Content-Security-Policy strips the report's inline styles, so it renders as unstyled text until you relax it (for example hudson.model.DirectoryBrowserSupport.CSP). That setting applies to all of Jenkins, so it's a trade-off, not a free win.


Previous: ← Shared defaults and a package name · Back to series index