ci

README

go-ci

A Go package that provides utilities for detecting and handling CI/CD environments. It also has testing helper functions to conditionally skip or fail tests/benchmarks/fuzzing based on the CI/CD status.

Usage

Use IsCI or IsNotCI to check if the current environment is within a CI/CD pipeline.

go get github.com/kitabisa/go-ci@latest

[!NOTE] See CICDEnvVars for currently supported CI/CD pipelines.

Testing helper function

Import the go-ci package into your *_test.go files.

import (
	"testing"

	"github.com/kitabisa/go-ci"
	"github.com/stretchr/testify/assert"
)

func shouldSkip(t *testing.T) {
	assert.True(t, t.Skipped())
	t.Logf("Skipping '%s' test in CI/CD environment", t.Name())
}

func TestFuncShoulNotInCI(t *testing.T) {
	defer shouldSkip(t)

	t.Setenv("CI", "true")
	ci.SkipTestIfCI(t)

	// do your test...
}

[!IMPORTANT] Please note that the checking mechanism uses a cache, so do NOT simulating CI/CD environment variables in actual test cases.

Available testing helper functions

func FailBenchmarkIfCI(b *testing.B)
func FailBenchmarkIfNotCI(b *testing.B)
func FailFuzzIfCI(f *testing.F)
func FailFuzzIfNotCI(f *testing.F)
func FailTestIfCI(t *testing.T)
func FailTestIfNotCI(t *testing.T)
func SkipBenchmarkIfCI(b *testing.B)
func SkipBenchmarkIfNotCI(b *testing.B)
func SkipFuzzIfCI(f *testing.F)
func SkipFuzzIfNotCI(f *testing.F)
func SkipTestIfCI(t *testing.T)
func SkipTestIfNotCI(t *testing.T)

Benchmark

$ go test -race -run="^$" -bench .
goos: linux
goarch: amd64
pkg: github.com/kitabisa/go-ci
cpu: 11th Gen Intel(R) Core(TM) i9-11900H @ 2.50GHz
BenchmarkIsCI/true-16         	39761295	        28.22 ns/op	       0 B/op	       0 allocs/op
BenchmarkIsCI/false-16        	42846458	        34.67 ns/op	       0 B/op	       0 allocs/op
PASS
ok  	github.com/kitabisa/go-ci	3.680s

License

go-ci is released by @dwisiswant0 under the Apache 2.0 license. See LICENSE.

Documentation

Overview

Package ci provides utilities for detecting and handling CI/CD environments.

Usage

• Use IsCI or IsNotCI to check if the current environment is within a CI/CD pipeline.

• Use `SkipTest*`, `SkipBenchmark*`, `SkipFuzz*`, `FailTest*`, `FailBenchmark*`, `FailFuzz*`, to conditionally skip or fail tests/benchmarks/fuzzing based on the CI/CD status.

Index

• Variables
• func FailBenchmarkIfCI(b *testing.B)
• func FailBenchmarkIfNotCI(b *testing.B)
• func FailFuzzIfCI(f *testing.F)
• func FailFuzzIfNotCI(f *testing.F)
• func FailTestIfCI(t *testing.T)
• func FailTestIfNotCI(t *testing.T)
• func IsCI() bool
• func IsNotCI() bool
• func SkipBenchmarkIfCI(b *testing.B)
• func SkipBenchmarkIfNotCI(b *testing.B)
• func SkipFuzzIfCI(f *testing.F)
• func SkipFuzzIfNotCI(f *testing.F)
• func SkipTestIfCI(t *testing.T)
• func SkipTestIfNotCI(t *testing.T)
• type Testing

Examples

• IsCI

Variables

var CICDEnvVars = map[string]string{

	"CI": "true",

	"JENKINS_URL": "",

	"BUILD_REASON":    "",
	"AGENT_JOBSTATUS": "",

	"BITBUCKET_BUILD_NUMBER": "",

	"TEAMCITY_VERSION": "",

	"bamboo_buildKey": "",

	"APPVEYOR": "true",

	"BUILDKITE": "true",

	"SEMAPHORE": "true",

	"SHIPPABLE": "true",

	"GO_SERVER_URL": "",

	"CODEBUILD_CI": "true",

	"WERCKER": "true",

	"STRIDER": "true",
}

CICDEnvVars format follows the pattern: `environment variable`:`expected value`

Note that if the provided expected value is an empty string, it implies that the check involves ensuring the environment variable is NOT an empty string.

Functions

func FailBenchmarkIfCI

func FailBenchmarkIfCI(b *testing.B)

FailBenchmarkIfCI is a testing helper function that fails the execution of a benchmark if it is running within a CI/CD pipeline.

func FailBenchmarkIfNotCI

func FailBenchmarkIfNotCI(b *testing.B)

FailBenchmarkIfNotCI is a testing helper function that fails the execution of a benchmark if it is not running within a CI/CD pipeline.

func FailFuzzIfCI

func FailFuzzIfCI(f *testing.F)

FailFuzzIfCI is a testing helper function that fails the execution of a fuzz test if it is running within a CI/CD pipeline.

func FailFuzzIfNotCI

func FailFuzzIfNotCI(f *testing.F)

FailFuzzIfNotCI is a testing helper function that fails the execution of a fuzz test if it is not running within a CI/CD pipeline.

func FailTestIfCI

func FailTestIfCI(t *testing.T)

FailTestIfCI is a testing helper function that fails the execution of a test if it is running within a CI/CD pipeline.

func FailTestIfNotCI

func FailTestIfNotCI(t *testing.T)

FailTestIfNotCI is a testing helper function that fails the execution of a test if it is not running within a CI/CD pipeline.

func IsCI

func IsCI() bool

IsCI determines whether the current environment is within a CI/CD pipeline.

Example

os.Setenv("CI", "false")
fmt.Println(IsCI())

Output:

false

func IsNotCI

func IsNotCI() bool

IsNotCI negates the result of IsCI. It returns true if the current environment is not within a CI/CD pipeline.

func SkipBenchmarkIfCI

func SkipBenchmarkIfCI(b *testing.B)

SkipBenchmarkIfCI is a testing helper function that skips the execution of a benchmark if it is running within a CI/CD pipeline.

func SkipBenchmarkIfNotCI

func SkipBenchmarkIfNotCI(b *testing.B)

SkipBenchmarkIfNotCI is a testing helper function that skips the execution of a benchmark if it is not running within a CI/CD pipeline.

func SkipFuzzIfCI

func SkipFuzzIfCI(f *testing.F)

SkipFuzzIfCI is a testing helper function that skips the execution of a fuzz test if it is running within a CI/CD pipeline.

func SkipFuzzIfNotCI

func SkipFuzzIfNotCI(f *testing.F)

SkipFuzzIfNotCI is a testing helper function that skips the execution of a fuzz test if it is not running within a CI/CD pipeline.

func SkipTestIfCI

func SkipTestIfCI(t *testing.T)

SkipTestIfCI is a testing helper function that skips the execution of a test if it is running within a CI/CD pipeline.

Example:

func TestYourFunc(t *testing.T) {
	defer func() {
		println(t.Skipped())
		// Output: true
	}()

	t.Setenv("CI", "true")
	ci.SkipTestIfCI(t)

	// do your test...
}

func SkipTestIfNotCI

func SkipTestIfNotCI(t *testing.T)

SkipTestIfNotCI is a testing helper function that skips the execution of a test if it is not running within a CI/CD pipeline.

Types

type Testing

type Testing interface {
	FailNow()
	SkipNow()
}