github.com/krishnamiriyala/courtney@v0.3.2/README.md (about) 1 [![Build Status](https://travis-ci.org/krishnamiriyala/courtney.svg?branch=master)](https://travis-ci.org/krishnamiriyala/courtney) [![Go Report Card](https://goreportcard.com/badge/github.com/krishnamiriyala/courtney)](https://goreportcard.com/report/github.com/krishnamiriyala/courtney) [![codecov](https://codecov.io/gh/krishnamiriyala/courtney/branch/master/graph/badge.svg)](https://codecov.io/gh/krishnamiriyala/courtney) 2 3 # Courtney 4 5 Courtney makes your code coverage more meaningful, by excluding some of the 6 less important parts. 7 8 1. Packages are tested with coverage. 9 2. Coverage files are merged. 10 3. Some code is less important to test. This is excluded from the coverage file. 11 4. Optionally we enforce that all remaining code is covered. 12 13 # Excludes 14 What do we exclude from the coverage report? 15 16 ### Blocks including a panic 17 If you need to test that your code panics correctly, it should probably be an 18 error rather than a panic. 19 20 ### Notest comments 21 Blocks or files with a `// TODO: notest` comment are excluded. 22 23 ### Blocks returning a error tested to be non-nil 24 We only exclude blocks where the error being returned has been tested to be 25 non-nil, so: 26 27 ```go 28 err := foo() 29 if err != nil { 30 return err // excluded 31 } 32 ``` 33 34 ... however: 35 36 ```go 37 if i == 0 { 38 return errors.New("...") // not excluded 39 } 40 ``` 41 42 All errors are originally created with code similar to `errors.New`, which is 43 not excluded from the coverage report - it's important your tests hit these. 44 45 It's less important your tests cover all the points that an existing non-nil 46 error is passed back, so these are excluded. 47 48 A few more rules: 49 * If multiple return values are returned, error must be the last, and all 50 others must be nil or zero values. 51 * We also exclude blocks returning an error which is the result of a function 52 taking a non-nil error as a parameter, e.g. `errors.Wrap(err, "...")`. 53 * We also exclude blocks containing a bare return statement, where the function 54 has named result parameters, and the last result is an error that has been 55 tested non-nil. Be aware that in this scenario no attempt is made to verify 56 that the other result parameters are zero values. 57 58 # Limitations 59 * Having test coverage doesn't mean your code is well tested. 60 * It's up to you to make sure that your tests explore the appropriate edge 61 cases. 62 63 # Install 64 ``` 65 go get -u github.com/krishnamiriyala/courtney 66 ``` 67 68 # Usage 69 Run the courtney command followed by a list of packages. Use `.` for the 70 package in the current directory, and adding `/...` tests all sub-packages 71 recursively. If no packages are provided, the default is `./...`. 72 73 To test the current package, and all sub-packages recursively: 74 ``` 75 courtney 76 ``` 77 78 To test just the current package: 79 ``` 80 courtney . 81 ``` 82 83 To test the `a` package, it's sub-packages and the `b` package: 84 ``` 85 courtney github.com/krishnamiriyala/a/... github.com/krishnamiriyala/b 86 ``` 87 88 # Options 89 ### Enforce: -e 90 `Enforce 100% code coverage.` 91 92 The command will exit with an error if any code remains uncovered. Combining a 93 CI system with a fully tested package and the `-e` flag is extremely useful. It 94 ensures any pull request has tests that cover all new code. For example, [here 95 is a PR](https://github.com/krishnamiriyala/courtney/pull/5) for this project that lacks 96 tests. As you can see the Travis build failed with a descriptive error. 97 98 ### Output: -o 99 `Override coverage file location.` 100 101 Provide a custom location for the coverage file. The default is `./coverage.out`. 102 103 ### Test flags: -t 104 `Argument to pass to the 'go test' command.` 105 106 If you have special arguments to pass to the `go test` command, add them here. 107 Add one `-t` flag per argument e.g. 108 ``` 109 courtney -t="-count=2" -t="-parallel=4" 110 ``` 111 112 ### Verbose: -v 113 `Verbose output` 114 115 All the output from the `go test -v` command is shown. 116 117 # Output 118 Courtney will fail if the tests fail. If the tests succeed, it will create or 119 overwrite a `coverage.out` file in the current directory. 120 121 # Continuous integration 122 To upload your coverage to [codecov.io](https://codecov.io/) via 123 [travis](https://travis-ci.org/), use a `.travis.yml` file something like this: 124 125 ```yml 126 language: go 127 go: 128 - 1.x 129 notificaitons: 130 email: 131 recipients: <your-email> 132 on_failure: always 133 install: 134 - go get -u github.com/krishnamiriyala/courtney 135 - go get -t -v ./... 136 script: 137 - courtney 138 after_success: 139 - bash <(curl -s https://codecov.io/bash) 140 ``` 141 142 For [coveralls.io](https://coveralls.io/), use something like this: 143 144 ```yml 145 language: go 146 go: 147 - 1.x 148 notificaitons: 149 email: 150 recipients: <your-email> 151 on_failure: always 152 install: 153 - go get -u github.com/mattn/goveralls 154 - go get -u github.com/krishnamiriyala/courtney 155 - go get -t -v ./... 156 script: 157 - courtney 158 after_success: 159 - goveralls -coverprofile=coverage.out -service=travis-ci 160 ```