limgo

Limgo

Don't let your test coverage drop

A tool for defining and enforcing test coverage thresholds locally as well as in CI pipelines - similar to the coverage thresholds in JavaScripts popular Testing Framework Jest.

limgo builds on top of the code coverage file generated by go test and extends it by a configuration file to define thresholds on directories and files using regular expressions. If those thresholds are not met, limgo will exit with code 1.

Currently, a coverage percentage as threshold can be defined for

• Statements
• Lines of Code
• Branches

Installation

To get started, install the pre-compiled limgo binary either manually or via go install. Alternatively, build it directly from source.

Manually

The limgo binary can be downloaded manually from the releases section. The binaries have no dependencies and should run without any problems on any of the listed operating systems.

Using go install

The limgo binary can be installed using go install:

go install github.com/GoTestTools/limgo@latest

Building from source

First, clone this repository via

git clone https://github.com/GoTestTools/limgo.git

Then navigate into the limgo directory and build the binary:

# via make
make build

# or via go directly
go build -o <output-name> cmd/main.go

Usage

The following snippet shows a basic example usage of limgo:

# run tests and generate coverage file
go test ./... -coverprofile=cov.out

# verify that the coverage is not below the thresholds defined in .limgo.json
limgo -coverfile=cov.out -config=.limgo.json -v=1

An overview as well as a short description of all supported flags can be displayed via

limgo -help

The configuration file

Coverage thresholds are defined in a configuration file. By default, limgo will search for a file named .limgo.json. This can be overridden by the -config flag.

Currently, coverage thresholds for statements and functions are supported. In the configuration file example below, thresholds are defined

• on a global (project) level
• for all files in the "coverage" directory
• for all files in the "gosrc" directory starting with g

{
"coverageThreshold": {
    "global": {
        "statements": 50,
        "functions": 50
    },
    "matcher": {
        "pkg/coverage": {
            "statements": 70,
            "functions": 80
        },
        "pkg/gosrc/g.*": {
            "statements": 10,
            "functions": 20
        }
    },
    "excludes": [
        "vendor/.*"
    ]
}

Every matchers key is parsed as a regular expression and it's threshold is applied to all the files that match it. Within the excludes array directories and files can be excluded - this overrides any matches.

Setup in a CI system

As limgo is a simple binary, it is easy to set it up in any CI system. The following snippet shows an Github Action example:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: checkout repo
        uses: actions/checkout@v2.3.4

      # Checkout your project with git
      - name: Checkout
        uses: actions/checkout@v2

      # Install Go on the VM running the action
      - name: Set up Go
        uses: actions/setup-go@v2
        with:
          go-version: 1.19
      
      # Option 1: 
      # install using go install
      - name: Set up limgo - option 1
        run: go install github.com/GoTestTools/limgo@latest
      
      # Option 2:
      # install via GitHub Action
      - name: Set up limgo - option 2
        uses: GoTestTools/limgo-action@v1.0.0
        with:
          version: "v0.0.0-beta"
          install-only: true

      # Run tests with coverprofile
      - name: Run tests
        run: |
          go test ./... -coverprofile=test.cov
      
      # Pass the coverprofile to limgo for coverage evaluation
      - name: Check test coverage
        run: |
          limgo -covfile=test.cov -v=2

The repository limgo-action-example contains an example on how to use the limgo GitHub Action.