Merge pull request #17 from dnephin/update-readme

Update README with demo

.circleci/config.yml

@@ -39,7 +39,7 @@ jobs:
       - run:
           name: "Unit Test GO 1.10"
           command: |
-            scripts/ci/test 1.10-alpine
+            scripts/ci/test 1.10.3-alpine
             mkdir -p junit/gotest
             docker cp \
                 test-$CIRCLE_BUILD_NUM:/go/src/gotest.tools/gotestsum/junit.xml \

README.md

@@ -1,65 +1,119 @@
 # gotestsum
 
+`gotestsum` runs tests, prints friendly test output and a summary of the test run.  Requires Go 1.10+.
+
+## Install
+
+Download a binary from [releases](https://github.com/gotestyourself/gotestsum/releases), or get the
+source with `go get gotest.tools/gotestsum` (you may need to run `dep ensure`).
+
+## Demo
+
+![Demo](https://raw.githubusercontent.com/gotestyourself/gotestsum/master/docs/demo.gif)
+
+## Docs
+
 [![GoDoc](https://godoc.org/gotest.tools/gotestsum?status.svg)](https://godoc.org/gotest.tools/gotestsum)
 [![CircleCI](https://circleci.com/gh/gotestyourself/gotestsum/tree/master.svg?style=shield)](https://circleci.com/gh/gotestyourself/gotestsum/tree/master)
 [![Go Reportcard](https://goreportcard.com/badge/gotest.tools/gotestsum)](https://goreportcard.com/report/gotest.tools/gotestsum)
 
-`gotestsum` runs `go test --json ./...`, ingests the test output, and prints
-customizable output:
- * print test counts: tests run, skipped, failed, package build
-   errors, and elapsed time.
- * print a summary of all failure and skip message after the tests have run
- * write a JUnit  XML, or
-   [Go TestEvent JSON](https://golang.org/cmd/test2json/#hdr-Output_Format)
-   file for ingestion by CI systems.
- * print customized test output with different formats. Formats from most condensed to most
-   verbose:
-   * `dots` - prints one character per test.
-   * `short` - prints a line for each test package (a more condensed version of the
-       `go test` default output).
-   * `standard-quiet` - prints the default `go test` format.
-   * `short-verbose` - prints a line for each test and package.
-   * `standard-verbose` - prints the standard `go test -v` format.
-   * want some other format? Open an issue!
-
-Requires Go version 1.10+
+`gotestsum` works by running `go test --json ./...` and reading the JSON
+output.
 
-## Install
+### TOC
 
-    go get gotest.tools/gotestsum
+- [Format](#format)
+- [Summary](#summary)
+- [JUnit XML](#junit-xml)
+- [JSON file](#json-file-output)
+- [Custom command](#custom-go-test-command)
 
-## Example Output
+### Format
 
-### short (default)
+Set a format with the `--format` flag or the `GOTESTSUM_FORMAT` environment
+variable.
+```
+gotestsum --format short-verbose
+```
+
+The supported formats are:
+ * `dots` - output one character per test.
+ * `short` (default) - output a line for each test package.
+ * `standard-quiet` - the default `go test` format.
+ * `short-verbose` - output a line for each test and package.
+ * `standard-verbose` - the standard `go test -v` format.
+
+Have a suggestion for some other format? Please open an issue!
+
+### Summary
 
-Prints a condensed format using relative package paths and symbols for test
-results.  Skip, failure, and error messages are printed after all the tests
-have completed.
+After the tests are done a summary of the test run is printed.
+The summary includes:
+ * A count of the tests run, skipped, failed, build errors, and elapsed time.
+ * Test output of all failed and skipped tests, and any build errors.
 
+To disable parts of the summary use `--no-summary section`.
+
+Example: hide skipped tests in the summary
+```
+gotestsum --no-summary=skipped
 ```
-✓  cmd (10ms)
-✖  pkg/do
-✓  pkg/log (11ms)
-↷  pkg/untested
 
-DONE 47 tests, 3 skipped, 5 failed in 0.120s
+Example: hide failed and skipped
+```
+gotestsum --no-summary=skipped,failed
 ```
 
-TODO: add failure and skip messages to example output
+### JUnit XML
 
-### dots
+In addition to the normal test output you can write a JUnit XML file for
+integration with CI systems. Write a file using the `--junitxml` flag or
+the `GOTESTSUM_JUNITFILE` environment variable.
 
-Prints the package name, followed by a `.` for passed tests, `✖` for failed
-tests, and `↷` for skipped tests. Skip, failure, and error messages are printed
-after all the tests have completed.
+```
+gotestsum --junitfile unit-tests.xml
+```
+
+### JSON file output
+
+In addition to the normal test output you can write a line-delimited JSON
+file with all the [test2json](https://golang.org/cmd/test2json/#hdr-Output_Format)
+output that was written by `go test --json`. This file can be used to calculate
+statistics about the test run.
+
+```
+gotestsum --jsonfile test-output.log
+```
+
+### Custom `go test` command
+
+By default `gotestsum` runs `go test --json ./...`. You can change this by
+specifying additional positional arguments after a `--`. Use `--debug` to
+echo the command before it is run.
 
+Example: set build tags
 ```
-[cmd]···↷···········[pkg/do]···↷↷✖·✖✖····✖··✖····[pkg/log]········
-DONE 47 tests, 3 skipped, 5 failed in 0.120s
+gotestsum -- -tags=integration ./...
 ```
 
-TODO: add failure and skip messages to example output
+Example: run only a single package
+```
+gotestsum -- ./io/http
+```
+
+Example: enable coverage
+```
+gotestsum -- -coverprofile=cover.out ./...
+```
+
+Example: run a script instead of `go test`
+```
+gotestsum --raw-command -- ./scripts/run_tests.sh
+```
 
+Note: when using `--raw-command` you must ensure that the stdout produced by
+the script only contains the `test2json` output. Any stderr produced will
+be considered an error (to match the behaviour of `go test --json`).
 
 ## Thanks
 

dobifiles/Dockerfile

@@ -1,6 +1,6 @@
 
 ARG     GOLANG_VERSION
-FROM    golang:${GOLANG_VERSION:-1.10.2-alpine} as golang
+FROM    golang:${GOLANG_VERSION:-1.10.3-alpine} as golang
 RUN     apk add -U curl git bash
 WORKDIR /go/src/gotest.tools/gotestsum
 ENV     CGO_ENABLED=0

internal/junitxml/testdata/junitxml-report.golden

@@ -2,15 +2,15 @@
 <testsuites>
 	<testsuite tests="0" failures="0" time="0.000s" name="github.com/gotestyourself/gotestyourself/testjson/internal/badmain">
 		<properties>
-			<property name="go.version" value="go1.10.2"></property>
+			<property name="go.version" value="go1.10.3"></property>
 		</properties>
 		<testcase classname="." name="TestMain" time="0.000s">
 			<failure message="Failed" type="">sometimes main can exit 2&#xA;FAIL&#x9;github.com/gotestyourself/gotestyourself/testjson/internal/badmain&#x9;0.010s&#xA;</failure>
 		</testcase>
 	</testsuite>
 	<testsuite tests="18" failures="0" time="0.020s" name="github.com/gotestyourself/gotestyourself/testjson/internal/good">
 		<properties>
-			<property name="go.version" value="go1.10.2"></property>
+			<property name="go.version" value="go1.10.3"></property>
 		</properties>
 		<testcase classname="good" name="TestSkipped" time="0.000s">
 			<skipped message="=== RUN   TestSkipped&#xA;--- SKIP: TestSkipped (0.00s)&#xA;&#x9;good_test.go:23: &#xA;"></skipped>
@@ -37,7 +37,7 @@
 	</testsuite>
 	<testsuite tests="28" failures="4" time="0.020s" name="github.com/gotestyourself/gotestyourself/testjson/internal/stub">
 		<properties>
-			<property name="go.version" value="go1.10.2"></property>
+			<property name="go.version" value="go1.10.3"></property>
 		</properties>
 		<testcase classname="stub" name="TestFailed" time="0.000s">
 			<failure message="Failed" type="">=== RUN   TestFailed&#xA;--- FAIL: TestFailed (0.00s)&#xA;&#x9;stub_test.go:34: this failed&#xA;</failure>