{"id":13489912,"url":"https://github.com/gotestyourself/gotestsum","last_synced_at":"2025-05-14T16:05:58.077Z","repository":{"id":31197976,"uuid":"126215645","full_name":"gotestyourself/gotestsum","owner":"gotestyourself","description":"'go test' runner with output optimized for humans, JUnit XML for CI integration, and a summary of the test results.","archived":false,"fork":false,"pushed_at":"2024-10-07T05:56:13.000Z","size":1134,"stargazers_count":2064,"open_issues_count":79,"forks_count":122,"subscribers_count":12,"default_branch":"main","last_synced_at":"2024-10-15T09:08:50.105Z","etag":null,"topics":["ci","go","go-test","golang","junit-xml","test","test-runner","testing"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gotestyourself.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-21T17:22:20.000Z","updated_at":"2024-10-15T08:46:03.000Z","dependencies_parsed_at":"2024-03-12T03:25:53.689Z","dependency_job_id":"b072335e-c6e0-46c8-909c-460d7e9ffcc6","html_url":"https://github.com/gotestyourself/gotestsum","commit_stats":{"total_commits":322,"total_committers":36,"mean_commits":8.944444444444445,"dds":0.1366459627329193,"last_synced_commit":"90a35cfb7751f7c6debf27f2fcf2fe07ba655176"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gotestyourself%2Fgotestsum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gotestyourself%2Fgotestsum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gotestyourself%2Fgotestsum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gotestyourself%2Fgotestsum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gotestyourself","download_url":"https://codeload.github.com/gotestyourself/gotestsum/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247953010,"owners_count":21023947,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ci","go","go-test","golang","junit-xml","test","test-runner","testing"],"created_at":"2024-07-31T19:00:37.722Z","updated_at":"2025-04-09T01:00:22.428Z","avatar_url":"https://github.com/gotestyourself.png","language":"Go","funding_links":[],"categories":["Go","Repositories"],"sub_categories":[],"readme":"# gotestsum\n\n`gotestsum` runs tests using `go test -json`, prints formatted test output, and a summary of the test run.\nIt is designed to work well for both local development, and for automation like CI.\n`gotestsum` is [used by](#who-uses-gotestsum) some of the most popular Go projects.\n\n## Install\n\nDownload a binary from [releases](https://github.com/gotestyourself/gotestsum/releases), or build from\nsource with `go install gotest.tools/gotestsum@latest`. To run without installing use\n`go run gotest.tools/gotestsum@latest`.\n\n## Documentation\n\n**Core features**\n- Change the [test output format](#output-format), from compact to verbose with color highlighting.\n- Print a [summary](#summary) of the test run after running all the tests.\n- Use any [`go test` flag](#custom-go-test-command),\n  run a script with [`--raw-command`](#custom-go-test-command),\n  or [run a compiled test binary](#executing-a-compiled-test-binary).\n\n**CI and Automation**\n- [`--junitfile`](#junit-xml-output) - write a JUnit XML file for integration with CI systems.\n- [`--jsonfile`](#json-file-output) - write all the [test2json](https://pkg.go.dev/cmd/test2json) input received by `gotestsum` to a file. The file\n  can be used as input to [`gotestsum tool slowest`](#finding-and-skipping-slow-tests), or as a way to\n  store the full verbose output of tests when less verbose output is printed to stdout using a compact [`--format`](#output-format).\n- [`--rerun-fails`](#re-running-failed-tests) - run failed (possibly flaky) tests again to avoid re-running the\n  entire suite. Re-running individual tests can save significant time when working with flaky test suites.\n\n**Local Development**\n- [`--watch`](#run-tests-when-a-file-is-saved) - every time a `.go` file is saved run the tests for the package that changed.\n- [`--post-run-command`](#post-run-command) - run a command after the tests, can be used for desktop notification of the test run.\n- [`gotestsum tool slowest`](#finding-and-skipping-slow-tests) - find the slowest tests, or automatically update the source code of\n  the slowest tests to add a conditional `t.Skip` statements. This statement allows you to skip the slowest tests using `gotestsum -- -short ./...`.\n\n\n### Output Format\n\nThe `--format` flag or `GOTESTSUM_FORMAT` environment variable set the format that\nis used to print the test names, and possibly test output, as the tests run. Most\noutputs use color to highlight pass, fail, or skip.\n\nThe `--format-icons` flag changes the icons used by `pkgname` and `testdox` formats.\nYou can set the `GOTESTSUM_FORMAT_ICONS` environment variable, instead of the flag.\nThe nerdfonts icons requires a font from [Nerd Fonts](https://www.nerdfonts.com/).\n\nCommonly used formats (see `--help` for a full list):\n\n * `dots` - print a character for each test.\n * `pkgname` (default) - print a line for each package.\n * `testname` - print a line for each test and package.\n * `testdox` - print a sentence for each test using [gotestdox](https://github.com/bitfield/gotestdox).\n * `standard-quiet` - the standard `go test` format.\n * `standard-verbose` - the standard `go test -v` format.\n\nHave an idea for a new format?\nPlease [share it on github](https://github.com/gotestyourself/gotestsum/issues/new)!\n\n#### Demo\n\nA demonstration of three `--format` options.\n\n![Demo](https://user-images.githubusercontent.com/442180/182284939-e08a0aa5-4504-4e30-9e88-207ef47f4537.gif)\n\u003cbr /\u003e\u003csup\u003e[Source](https://github.com/gotestyourself/gotestsum/tree/readme-demo/scripts)\u003c/sup\u003e\n\n### Summary\n\nFollowing the formatted output is a summary of the test run. The summary includes:\n\n * The test output, and elapsed time, for any test that fails or is skipped.\n * The build errors for any package that fails to build.\n * A `DONE` line with a count of tests run, tests skipped, tests failed, package build errors,\n   and the elapsed time including time to build.\n\n   ```\n   DONE 101 tests[, 3 skipped][, 2 failures][, 1 error] in 0.103s\n   ```\n\nTo hide parts of the summary use `--hide-summary section`.\n\n\n**Example: hide skipped tests in the summary**\n```\ngotestsum --hide-summary=skipped\n```\n\n**Example: hide everything except the DONE line**\n```\ngotestsum --hide-summary=skipped,failed,errors,output\n# or\ngotestsum --hide-summary=all\n```\n\n**Example: hide test output in the summary, only print names of failed and skipped tests\nand errors**\n```\ngotestsum --hide-summary=output\n```\n\n### JUnit XML output\n\nWhen the `--junitfile` flag or `GOTESTSUM_JUNITFILE` environment variable are set\nto a file path, `gotestsum` will write a test report, in JUnit XML format, to the file.\nThis file can be used to integrate with CI systems.\n\n```\ngotestsum --junitfile unit-tests.xml\n```\n\nIf the package names in the `testsuite.name` or `testcase.classname` fields do not\nwork with your CI system these values can be customized using the\n`--junitfile-testsuite-name`, or `--junitfile-testcase-classname` flags. These flags\naccept the following values:\n\n* `short` - the base name of the package (the single term specified by the\n  package statement).\n* `relative` - a package path relative to the root of the repository\n* `full` - the full package path (default)\n\n\nNote: If Go is not installed, or the `go` binary is not in `PATH`, the `GOVERSION`\nenvironment variable can be set to remove the \"failed to lookup go version for junit xml\"\nwarning.\n\n### JSON file output\n\nWhen the `--jsonfile` flag or `GOTESTSUM_JSONFILE` environment variable are set\nto a file path, `gotestsum` will write a line-delimited JSON file with all the\n[test2json](https://golang.org/cmd/test2json/#hdr-Output_Format)\noutput that was written by `go test -json`. This file can be used to compare test\nruns, or find flaky tests.\n\n```\ngotestsum --jsonfile test-output.log\n```\n\n### Post Run Command\n\nThe `--post-run-command` flag may be used to execute a command after the\ntest run has completed. The binary will be run with the following environment\nvariables set:\n\n```\nGOTESTSUM_ELAPSED       # test run time in seconds (ex: 2.45s)\nGOTESTSUM_FORMAT        # gotestsum format (ex: pkgname)\nGOTESTSUM_JSONFILE      # path to the jsonfile, empty if no file path was given\nGOTESTSUM_JUNITFILE     # path to the junit.xml file, empty if no file path was given\nTESTS_ERRORS            # number of errors\nTESTS_FAILED            # number of failed tests\nTESTS_SKIPPED           # number of skipped tests\nTESTS_TOTAL             # number of tests run\n```\n\nTo get more details about the test run, such as failure messages or the full list of failed\ntests, run `gotestsum` with either a `--jsonfile` or `--junitfile` and parse the\nfile from the post-run-command. The\n[gotestsum/testjson](https://pkg.go.dev/gotest.tools/gotestsum/testjson?tab=doc)\npackage may be used to parse the JSON file output.\n\n**Example: desktop notifications**\n\nFirst install the example notification command with `go get gotest.tools/gotestsum/contrib/notify`.\nThe command will be downloaded to `$GOPATH/bin` as `notify`. Note that this\nexample `notify` command only works on Linux with `notify-send` and on macOS with\n[terminal-notifer](https://github.com/julienXX/terminal-notifier) installed.\n\nOn Linux, you need to have some \"test-pass\" and \"test-fail\" icons installed in your icon theme.\nSome sample icons can be found in `contrib/notify`, and can be installed with `make install`.\n\nOn Windows, you can install [notify-send.exe](https://github.com/vaskovsky/notify-send)\nbut it does not support custom icons so will have to use the basic \"info\" and \"error\".\n\n```\ngotestsum --post-run-command notify\n```\n\n**Example: command with flags**\n\nPositional arguments or command line flags can be passed to the `--post-run-command` by\nquoting the whole command.\n\n```\ngotestsum --post-run-command \"notify me --date\"\n```\n\n**Example: printing slowest tests**\n\nThe post-run command can be combined with other `gotestsum` commands and tools to provide\na more detailed summary. This example uses `gotestsum tool slowest` to print the\nslowest 10 tests after the summary.\n\n```\ngotestsum \\\n  --jsonfile tmp.json.log \\\n  --post-run-command \"bash -c '\n    echo; echo Slowest tests;\n    gotestsum tool slowest --num 10 --jsonfile tmp.json.log'\"\n```\n\n### Re-running failed tests\n\nWhen the `--rerun-fails` flag is set, `gotestsum` will re-run any failed tests.\nThe tests will be re-run until each passes once, or the number of attempts\nexceeds the maximum attempts. Maximum attempts defaults to 2, and can be changed\nwith `--rerun-fails=n`.\n\nTo avoid re-running tests when there are real failures, the re-run will be\nskipped when there are too many test failures. By default this value is 10, and\ncan be changed with `--rerun-fails-max-failures=n`.\n\nNote that using `--rerun-fails` may require the use of other flags, depending on\nhow you specify args to `go test`:\n\n* when used with `--raw-command` the re-run will pass additional arguments to\n  the command. The first arg is a `-test.run` flag with a regex that matches the test to re-run,\n  and second is the name of a go package. These additional args can be passed to `go test`,\n  or a test binary.\n* when used with any `go test` args (anything after `--` on the command line), the list of\n  packages to test must be specified as a space separated list using the `--packages` arg.\n\n  **Example**\n\n  ```\n  gotestsum --rerun-fails --packages=\"./...\" -- -count=2\n  ```\n\n* if any of the `go test` args should be passed to the test binary, instead of\n  `go test` itself, the `-args` flag must be used to separate the two groups of\n  arguments. `-args` is a special flag that is understood by `go test` to indicate\n  that any following args should be passed directly to the test binary.\n\n  **Example**\n\n  ```\n  gotestsum --rerun-fails --packages=\"./...\" -- -count=2 -args -update-golden\n  ```\n\n\n### Custom `go test` command\n\nBy default `gotestsum` runs tests using the command `go test -json ./...`. You\ncan change the command with positional arguments after a `--`. You can change just the\ntest directory value (which defaults to `./...`) by setting the `TEST_DIRECTORY`\nenvironment variable.\n\nYou can use `--debug` to echo the command before it is run.\n\n**Example: set build tags**\n```\ngotestsum -- -tags=integration ./...\n```\n\n**Example: run tests in a single package**\n```\ngotestsum -- ./io/http\n```\n\n**Example: enable coverage**\n```\ngotestsum -- -coverprofile=cover.out ./...\n```\n\n**Example: run a script instead of `go test`**\n```\ngotestsum --raw-command -- ./scripts/run_tests.sh\n```\n\nNote: when using `--raw-command`, the script must follow a few rules about\nstdout and stderr output:\n\n* The stdout produced by the script must only contain the `test2json` output, or\n  `gotestsum` will fail. If it isn't possible to change the script to avoid\n  non-JSON output, you can use `--ignore-non-json-output-lines` (added in version 1.7.0)\n  to ignore non-JSON lines and write them to `gotestsum`'s stderr instead.\n* Any stderr produced by the script will be considered an error (this behaviour\n  is necessary because package build errors are only reported by writing to\n  stderr, not the `test2json` stdout). Any stderr produced by tests is not\n  considered an error (it will be in the `test2json` stdout).\n\n**Example: accept input from stdin**\n```\ncat out.json | gotestsum --raw-command -- cat\n```\n\n**Example: run tests with profiling enabled**\n\nUsing a `profile.sh` script like this:\n\n```sh\n#!/usr/bin/env bash\nset -eu\n\nfor pkg in $(go list \"$@\"); do\n    dir=\"$(go list -f '{{ .Dir }}' $pkg)\"\n    go test -json -cpuprofile=\"$dir/cpu.profile\" \"$pkg\"\ndone\n```\n\nYou can run:\n```\ngotestsum --raw-command ./profile.sh ./...\n```\n\n**Example: using `TEST_DIRECTORY`**\n```\nTEST_DIRECTORY=./io/http gotestsum\n```\n\n### Executing a compiled test binary\n\n`gotestsum` supports executing a compiled test binary (created with `go test -c`) by running\nit as a custom command.\n\nThe `-json` flag is handled by `go test` itself, it is not available when using a\ncompiled test binary, so `go tool test2json` must be used to get the output\nthat `gotestsum` expects.\n\n**Example: running `./binary.test`**\n\n```\ngotestsum --raw-command -- go tool test2json -t -p pkgname ./binary.test -test.v\n```\n\n`pkgname` is the name of the package being tested, it will show up in the test\noutput. `./binary.test` is the path to the compiled test binary. The `-test.v`\nmust be included so that `go tool test2json` receives all the output.\n\nTo execute a test binary without installing Go, see\n[running without go](./.project/docs/running-without-go.md).\n\n\n### Finding and skipping slow tests\n\n`gotestsum tool slowest` reads [test2json output][testjson],\nfrom a file or stdin, and prints the names and elapsed time of slow tests.\nThe tests are sorted from slowest to fastest.\n\n`gotestsum tool slowest` can also rewrite the source of tests slower than the\nthreshold, making it possible to optionally skip them.\n\nThe [test2json output][testjson] can be created with `gotestsum --jsonfile` or `go test -json`.\n\nSee `gotestsum tool slowest --help`.\n\n**Example: printing a list of tests slower than 500 milliseconds**\n\n```\n$ gotestsum --format dots --jsonfile json.log\n[.]····↷··↷·\n$ gotestsum tool slowest --jsonfile json.log --threshold 500ms\ngotest.tools/example TestSomething 1.34s\ngotest.tools/example TestSomethingElse 810ms\n```\n\n**Example: skipping slow tests with `go test --short`**\n\nAny test slower than 200 milliseconds will be modified to add:\n\n```go\nif testing.Short() {\n    t.Skip(\"too slow for testing.Short\")\n}\n```\n\n```sh\ngo test -json -short ./... | gotestsum tool slowest --skip-stmt \"testing.Short\" --threshold 200ms\n```\n\nUse `git diff` to see the file changes.\nThe next time tests are run using `--short` all the slow tests will be skipped.\n\n[testjson]: https://golang.org/cmd/test2json/\n\n\n### Run tests when a file is saved \n\nWhen the `--watch` flag is set, `gotestsum` will watch directories using\n[file system notifications](https://pkg.go.dev/github.com/fsnotify/fsnotify).\nWhen a Go file in one of those directories is modified, `gotestsum` will run the\ntests for the package that contains the changed file. By default all\ndirectories under the current\ndirectory with at least one `.go` file will be watched.\nUse the `--packages` flag to specify a different list.\n\nIf `--watch` is used with a command line that includes the name of one or more\npackages as command line arguments (ex: `gotestsum --watch -- ./...` or\n`gotestsum --watch -- ./extrapkg`), the\ntests in those packages will also be run when any file changes.\n\nWith the `--watch-chdir` flag, `gotestsum` will change the working directory\nto the directory with the modified file before running tests. Changing the\ndirectory is primarily useful when the project contains multiple Go modules.\nWithout this flag, `go test` will refuse to run tests for any package outside\nof the main Go module.\n\nWhile in watch mode, pressing some keys will perform an action:\n\n* `r` will run tests for the previous event.\n  Added in version 1.6.1.\n* `u` will run tests for the previous event, with the `-update` flag added.\n  Many [golden](https://gotest.tools/v3/golden) packages use this flag to automatically\n  update expected values of tests.\n  Added in version 1.8.1.\n* `d` will run tests for the previous event using `dlv test`, allowing you to \n  debug a test failure using [delve]. A breakpoint will automatically be added at\n  the first line of any tests which failed in the previous run. Additional\n  breakpoints can be added with [`runtime.Breakpoint`](https://golang.org/pkg/runtime/#Breakpoint)\n  or by using the delve command prompt.\n  Added in version 1.6.1.\n* `a` will run tests for all packages, by using `./...` as the package selector.\n  Added in version 1.7.0.\n* `l` will scan the directory list again, and if there are any new directories\n  which contain a file with a `.go` extension, they will be added to the watch\n  list.\n  Added in version 1.7.0.\n\nNote that [delve] must be installed in order to use debug (`d`).\n\n[delve]: https://github.com/go-delve/delve\n\n**Example: run tests for a package when any file in that package is saved**\n```\ngotestsum --watch --format testname\n```\n\n## Who uses gotestsum?\n\nThe projects below use (or have used) gotestsum.\n\n* [kubernetes](https://github.com/kubernetes/kubernetes/blob/master/hack/tools/tools.go)\n* [moby](https://github.com/moby/moby/blob/master/hack/test/unit) (aka Docker)\n* [etcd](https://github.com/etcd-io/etcd/blob/main/tools/mod/tools.go)\n* [hashicorp/vault](https://github.com/hashicorp/vault/blob/main/tools/tools.go)\n* [hashicorp/consul](https://github.com/hashicorp/consul/blob/main/.github/workflows/reusable-unit.yml)\n* [prometheus](https://github.com/prometheus/prometheus/blob/main/Makefile.common)\n* [minikube](https://github.com/kubernetes/minikube/blob/master/hack/jenkins/common.ps1)\n* [influxdb](https://github.com/influxdata/influxdb/blob/master/scripts/ci/build-tests.sh)\n* [pulumi](https://github.com/pulumi/pulumi/blob/master/.github/workflows/ci.yml)\n* [grafana/k6](https://github.com/grafana/k6/issues/1986#issuecomment-996625874)\n* [grafana/loki](https://github.com/grafana/loki/blob/main/loki-build-image/Dockerfile)\n* [telegraf](https://github.com/influxdata/telegraf/blob/master/.circleci/config.yml)\n* [containerd](https://github.com/containerd/containerd/blob/main/.cirrus.yml)\n* [linkerd2](https://github.com/linkerd/linkerd2/blob/main/justfile)\n* [elastic/go-elasticsearch](https://github.com/elastic/go-elasticsearch/blob/main/Makefile)\n* [microsoft/hcsshim](https://github.com/microsoft/hcsshim/blob/main/.github/workflows/ci.yml)\n* [pingcap/tidb](https://github.com/pingcap/tidb/blob/master/Makefile)\n* [dex](https://github.com/dexidp/dex/blob/master/Makefile)\n* [coder](https://github.com/coder/coder/blob/main/Makefile)\n* [docker/cli](https://github.com/docker/cli/blob/master/Makefile)\n* [mattermost](https://github.com/mattermost/mattermost/blob/master/server/Makefile)\n* [gofiber/fiber](https://github.com/gofiber/fiber/blob/main/.github/workflows/test.yml)\n\nPlease open a GitHub issue or pull request to add or remove projects from this list.\n\n## Development\n\n[![Godoc](https://godoc.org/gotest.tools/gotestsum?status.svg)](https://pkg.go.dev/gotest.tools/gotestsum?tab=subdirectories)\n[![CircleCI](https://circleci.com/gh/gotestyourself/gotestsum/tree/main.svg?style=shield)](https://circleci.com/gh/gotestyourself/gotestsum/tree/main)\n[![Go Recipes](https://raw.githubusercontent.com/nikolaydubina/go-recipes/main/badge.svg?raw=true)](https://github.com/nikolaydubina/go-recipes)\n[![Go Reportcard](https://goreportcard.com/badge/gotest.tools/gotestsum)](https://goreportcard.com/report/gotest.tools/gotestsum)\n\n\nPull requests and bug reports are welcome! Please open an issue first for any\nbig changes.\n\n## Thanks\n\nThis package is heavily influenced by the [pytest](https://docs.pytest.org) test runner for `python`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgotestyourself%2Fgotestsum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgotestyourself%2Fgotestsum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgotestyourself%2Fgotestsum/lists"}