> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# gotest/tools

Golang CI jobs and commands for CircleCI.

Source: https://github.com/dnephin/golang-orb


## Commands

### install-ssh

### install

Install a package

| Parameter | Type | Default | Description |
|---|---|---|---|
| `package` | string |  |  |

### mod-download

DEPRECATED: use 'run: go mod download' instead.

Previously this command would restore and update the Go module cache.
After measuring the cache effectiveness it turned out that 'go mod download'
is actually faster than the cache in most cache. In go1.13 'go mod download'
became even faster due to the use of the package cache.

This command no longer uses a cache, but remains for backwards compatibility.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `prefix` | string | v1 |  |
| `path` | string | /go/pkg/mod |  |

### mod-tidy-check

Run 'go mod tidy' and check that go.mod and go.sum remain unmodified.
Use this command to ensure that the go module files that are commited
are correct and tidy.


### install-gotestsum

Install gotestsum

| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string | 1.7.0 |  |
| `gobin` | string | /go/bin |  |
| `prefix` | string | v1 | Prefix for cache key to store the binary. |

### install-golangci-lint

Install golangci-lint

| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string | 1.42.0 |  |
| `gobin` | string | /go/bin |  |
| `prefix` | string | v1 | Prefix for cache key to store the binary. |

## Jobs

### test

Run tests with gotestsum.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `executor` | executor | golang |  |
| `go-test-flags` | string |  | Flags passed to go test. |
| `packages` | string | ./... | Import paths of packages to be tested. |
| `test-suite-name` | string | unit | Test suite name to report to CircleCI. |
| `gotestsum-format` | string | short | gotestsum format. https://github.com/gotestyourself/gotestsum#format |
| `coverage` | string | -coverprofile=coverage.txt | Coverage flag. Set to the empty string to disable. |
| `codecov-upload` | boolean | false | Upload coverage report to https://codecov.io/. Requires the codecov API token to be
set as an environment variable for private projects.
 |

### lint

Run golangci-lint.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `executor` | executor | golang |  |
| `golangci-lint-version` | string | 1.42.0 |  |
| `concurrency` | string | 2 | Concurrency used to run linters. Defaults to 2 because NumCPU is not
aware of container CPU limits.
 |

### godoc

Render static godoc and upload it to a remote branch. Defaults to
uploading to the gh-pages branch for using github pages.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `executor` | executor | golang |  |
| `package` | string |  | Import path to a go package in the GOPATH to render with godoc.
 |
| `target-branch` | string | gh-pages | Git branch which contains the static godoc. Set to the empty string
to disable publishing to a branch.
 |

## Executors

### golang

| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | 1.17-alpine | Image tag for golang docker image.
https://hub.docker.com/_/golang?tab=tags
 |
| `cgo-enabled` | string | 0 | Value for CGO_ENABLED |

### circleci-golang

| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | 1.17 | Image tag for circleci/golang docker image.
https://hub.docker.com/r/circleci/golang/tags
 |
| `cgo-enabled` | string | 1 | Value for CGO_ENABLED |