gotestfmt: go test output for humans

⚠️ Action required: gotestfmt has moved to the GoTestTools organization and you need to update your references. Please see the announcement. The old repository will be deleted on January 1, 2023.

Are you tired of scrolling through endless Golang test logs in GitHub Actions (or other CI systems)?

Then this is the tool for you. Run it locally, or in any CI system with the following command line like this:

set -euo pipefail
go test -json -v ./... 2>&1 | tee /tmp/gotest.log | gotestfmt

Tadam, your tests will now show up in a beautifully formatted fashion. Plug it into your CI and you're done. Installation is also easy:

Note: Please always save the original log. You will need it if you have to file a bug report for gotestfmt.

Table of Contents

• Installing
• Setting it up in your CI system
• GitHub Actions
• GitLab CI
• CircleCI
• Add your own CI
• FAQ
  • How do I make the output less verbose?
  • How do I format the log lines within a test?
  • Why does gotestfmt exit with a non-zero status?
  • Can I use gotestfmt without -json?
  • Does gotestfmt work with Ginkgo?
  • I don't like gotestfmt. What else can I use?
  • Who uses gotestfmt?
• Architecture
• Building
• License

Installing

You can install gotestfmt using the following methods.

Manually

You can download the binary 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

You can install gotestfmt using the go install command:

go install github.com/gotesttools/gotestfmt/v2/cmd/gotestfmt@latest

You can then use the gotestfmt command, provided that your Go bin directory is added to your system path.

Using a container

You can also run gotestfmt in a container. For example:

go test -json ./... | docker run ghcr.io/gotesttools/gotestfmt:latest

If you have a high volume of requests you may want to mirror the image to your own registry.

Setting it up in your CI system

We have support for several CI systems, and you can also customize the output to match your system. Gotestfmt detects the CI system based on environment variables. If it can't detect the CI system it will try to create a generic colored test output. You can force the CI output with the -ci github|gitlab|... option.

• GitHub Actions
• GitLab CI
• CircleCI
• Add your own

GitHub Actions

For GitHub Actions we provide gotestfmt-action, making it easy to use. Here's how you can set it up:

jobs:
  build:
    name: Test
    runs-on: ubuntu-latest
    steps:
      # 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.16

      # Install gotestfmt on the VM running the action.
      - name: Set up gotestfmt
        uses: gotesttools/gotestfmt-action@v2
        with:
          # Optional: pass GITHUB_TOKEN to avoid rate limiting.
          token: ${{ secrets.GITHUB_TOKEN }}

      # Alternatively, install using go install
      - name: Set up gotestfmt
        run: go install github.com/gotesttools/gotestfmt/v2/cmd/gotestfmt@latest

      # Run tests with nice formatting. Save the original log in /tmp/gotest.log
      - name: Run tests
        run: |
          set -euo pipefail
          go test -json -v ./... 2>&1 | tee /tmp/gotest.log | gotestfmt

      # Upload the original go test log as an artifact for later review.
      - name: Upload test log
        uses: actions/upload-artifact@v2
        if: always()
        with:
          name: test-log
          path: /tmp/gotest.log
          if-no-files-found: error

Gotestfmt provides specialized output for GitHub Actions based on the presence of the GITHUB_WORKFLOW environment variable. You can also set gotestfmt to run in GitHub Actions mode by providing the -ci github option.

In GitHub Actions mode gotestfmt will look for the rendering templates in the .gotestfmt/github and .gotestfmt folders, which can be customized.

GitLab CI

There are multiple ways to run gotestfmt in GitLab CI. You can simply download it from the releases section and use it that way, but we would recommend creating a custom container image to run the tests as follows:

# Include gotestfmt as a base image for building
FROM ghcr.io/gotesttools/gotestfmt:latest AS gotestfmt

# Use the golang base image
FROM golang
# Copy gotestfmt into the golang image
COPY --from gotestfmt /gotestfmt /usr/local/bin/

You can then run the tests within this image with the following command:

go test -json -v ./... | /usr/local/bin/gotestfmt

To put it all together, you can use the following .gitlab-ci.yaml:

docker-build:
  image: docker:latest
  stage: build
  services:
    - docker:dind
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
  script:
    - |
      docker build -t gotestfmt .
      docker run \
        -v $(pwd):/source \
        -v /tmp:/tmp |
        -e GITLAB_CI=${GITLAB_CI} \
        gotestfmt \
        /bin/sh -c "cd /source; go test -json -v ./... 2>&1 | tee /tmp/gotest.log | /usr/local/bin/gotestfmt"
  artifacts:
    paths:
      - /tmp/gotest.log
    expire_in: 1 week
  rules:
    - if: $CI_COMMIT_BRANCH
      exists:
        - Dockerfile

You can, of course, customize this to your liking. We also recommend mirroring the gotestfmt image to your local registry to avoid rate limiting errors. See the GitLab blog on how to do this.

Gotestfmt detects running in GitLab CI based on the GITLAB_CI environment variable. You can also force gotestfmt to run in GitLab CI mode by passing the -c gitlab option.

CircleCI

There is no special template for CircleCI since it doesn't support advanced features like log folding. You can set up Circle CI by using the gotestfmt container directly:

version: 2
jobs:
  test:
    docker:
      - image: circleci/golang:1.16
    steps:
      - checkout
      - setup_remote_docker:
          version: 19.03.13
      - run:
          name: Run tests
          command: go test -json -v ./... 2>&1 | tee /tmp/gotest.log | docker run -i ghcr.io/gotesttools/gotestfmt:latest
      - store_artifacts:
          path: /tmp/gotest.log
          destination: gotest.log
workflows:
  version: 2
  build-workflow:
    jobs:
      - test

Add your own CI

You can, of course, customize the output to match your CI system. You can do this creating a folder named .gotestfmt in your project and adding the go template files below. You can find the default templates in the .gotestfmt folder in this repository.

When running on a well-known CI system, such as GitHub Actions, gotestfmt will detect that and look in the specific subfolder. If you think a specific CI system should have a custom template, please send us a pull request to this repository.

downloads.tpl

This file contains the output fragment showing the package downloads in the Go template format. It has the following variables available:

The Package items have the following format:

package.tpl

This template is the output format for the results of a single package and the tests in it. If multiple packages are tested, this template is called multiple times in a row. It has the following fields:

Test cases have the following format:

Render settings

Render settings are available in all templates. They have the following fields: