From 733873e3446b562ae14ff5a19223b1b534061720 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=ABl=20Stemmer?= Date: Tue, 22 Mar 2022 21:59:40 +0000 Subject: [PATCH] Update README.md for changes made in v2 --- README.md | 64 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 48 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index d774e64..c858943 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,18 @@ # go-junit-report -go-junit-report is a tool that converts [`go test`] output to an XML report, -suitable for applications that expect JUnit-style XML reports (e.g. [Jenkins]). - -The test output [parser] and JUnit report [formatter] are also available as Go -packages. +go-junit-report is a tool that converts [`go test`] output to a JUnit compatible +XML report, suitable for use with applications such as [Jenkins]. [![Build status][github-actions-badge]][github-actions-link] +The test output parser and JUnit XML report generator are also available as Go +packages. This can be helpful if you want to create your own custom JUnit +reports for example. See the package documentation on pkg.go.dev for more +information: + +- [go-junit-report/v2/pkg/parser/gotest] +- [go-junit-report/v2/pkg/junit] + ## Install from package (recommended) Pre-built packages for Windows, macOS and Linux are found on the [Releases] @@ -23,24 +28,50 @@ go install github.com/jstemmer/go-junit-report@latest ## Usage -go-junit-report reads the full `go test` output from stdin and writes JUnit -compatible XML to stdout. In order to capture build errors as well as test -output, redirect both stdout and stderr to go-junit-report. +By default, go-junit-report reads the `go test -v` output generated by the +standard library [testing] package from `stdin` and writes a JUnit XML report to +`stdout`. Go benchmark output and general Go build and runtime errors are also +supported. Note that in order to capture build and runtime errors, `stderr` +needs to be redirected to go-junit-report as well. + +### Examples + +Run tests for all packages in the current directory and its subdirectories, +write the output to a file called `report.xml` and exit with a non-zero exit +code when encountering any test failures or build errors. ```bash -go test -v 2>&1 | go-junit-report > report.xml +go test -v 2>&1 ./... | go-junit-report -set-exit-code > report.xml ``` -Parsing benchmark output is also supported, for example: +Run benchmarks for the package in the current directory, write the output to a +file called `report.xml`. ```bash -go test -v -bench . -count 5 2>&1 | go-junit-report > report.xml +go test -v -bench . -count 5 2>&1 | go-junit-report -out report.xml ``` -If you want go-junit-report to exit with a non-zero exit code when it encounters -build errors or test failures, set the `-set-exit-code` flag. +Read test input from a file called `tests.txt`, copy the input directly to +stdout and write the report to a file called `report.xml`. -Run `go-junit-report -help` for a list of all supported flags. +```bash +go-junit-report -in tests.txt -iocopy -out report.xml +``` + +### Options + +Run `go-junit-report -help` for a list of all supported options. + +| Flag | Description | +| -------------------- | ----------- | +| `-in file` | read go test log from `file` | +| `-iocopy` | copy input to stdout; can only be used in conjunction with -out | +| `-no-xml-header` | do not print xml header | +| `-out file` | write XML report to `file` | +| `-package-name name` | specify a default package name to use if output does not contain a package name | +| `-prop key=value` | add property to generated report; properties should be specified as `key=value` | +| `-set-exit-code` | set exit code to 1 if tests failed | +| `-version` | print version and exit | ## Contributing @@ -48,9 +79,10 @@ See [CONTRIBUTING.md]. [`go test`]: https://pkg.go.dev/cmd/go#hdr-Test_packages [Jenkins]: https://www.jenkins.io/ -[parser]: https://pkg.go.dev/github.com/jstemmer/go-junit-report/parser -[formatter]: https://pkg.go.dev/github.com/jstemmer/go-junit-report/formatter [github-actions-badge]: https://github.com/jstemmer/go-junit-report/actions/workflows/main.yml/badge.svg [github-actions-link]: https://github.com/jstemmer/go-junit-report/actions +[go-junit-report/v2/pkg/parser/gotest]: https://pkg.go.dev/github.com/jstemmer/go-junit-report/v2/pkg/parser/gotest +[go-junit-report/v2/pkg/junit]: https://pkg.go.dev/github.com/jstemmer/go-junit-report/v2/pkg/junit [Releases]: https://github.com/jstemmer/go-junit-report/releases +[testing]: https://pkg.go.dev/testing [CONTRIBUTING.md]: https://github.com/jstemmer/go-junit-report/blob/master/CONTRIBUTING.md