Continuous Integration with CirceCI

The application infrastructure has been established and now the main body of the development can commence. Therefore it is very valuable to establish a continuous integration pipeline.

Practicalli Clojure: Continuous Integration with CircleCI covers in detail how to use Continuous Integration with Clojure projects (deps.edn and Leiningen).

Using kaocha test runner

LambdaIsland kaocha test runner is used as the unit test runner as it will also run generative tests where functions have specifications defined.

Add a :test/run alias to the deps.edn file in the root of the project.

The configuration runs Kaocha without test randomisation for a consistent test order and stops the test runner if a test fails, ensuring time is not spent running tests after a failure.

:test/run
{:extra-paths ["test"]
 :extra-deps {lambdaisland/kaocha {:mvn/version "1.60.977"}}
 :exec-fn kaocha.runner/exec-fn
 :exec-args {:randomize? false
             :fail-fast? true}}

Create the file bin/kaocha in the root of the project and make it executable (e.g. chmod a+x bin/kaocha)

#!/usr/bin/env bash

## Script to run the kaocha test runner
## for unit tests and clojure spec generative tests

clojure -X:test/run "$@"

Configure CircleCI pipeline

Configure a pipeline to use a docker image with Java 17 and the latest Clojure CLI tools

The configuration uses the Kaocha Orb to simplify the configuration required to use the Kaocha test runner from within CircleCI.

A run step will call the kaocha script that is included in the project code repository and run the unit tests. If function specifications are present in the project, generative tests will also be run.

version: 2.1  # circleci configuration version

orbs:
  kaocha: lambdaisland/kaocha@0.0.3 # Org settings > Security > uncertified orbs

jobs:    # basic units of work in a run
  build: # runs not using Workflows must have a `build` job as entry point
    working_directory: ~/build    # directory where steps will run
    docker:                       # run the steps with Docker
      - image: cimg/clojure:1.10  # image is primary container where `steps` are run
    environment:                  # environment variables for primary container
      JVM_OPTS: -Xmx3200m         # limit the maximum heap size to prevent out of memory errors
    steps:                        # commands that comprise the `build` job
      - checkout                  # check out source code to working directory
      - restore_cache:            # restores saved cache if checksum hasn't changed since the last run
          key: banking-on-clojure-webapp-{{ checksum "deps.edn" }}
      - run: clojure -X:test/runner
      - save_cache:               # generate and store cache in the .m2 directory using a key template
          paths:
            - ~/.m2
            - ~/.gitlibs
          key: banking-on-clojure-webapp-{{ checksum "deps.edn" }}
      - run: bin/kaocha --reporter kaocha.report/documentation --no-randomize --no-color --plugin kaocha.plugin.alpha/spec-test-check

Enable 3rd Party Orbs

Enable 3rd Party Orbs in Organisation > Security settings