github.com/aexvir/courtney@v0.3.0/README.md (about)

     1  [![Build Status](https://travis-ci.org/dave/courtney.svg?branch=master)](https://travis-ci.org/dave/courtney) [![Go Report Card](https://goreportcard.com/badge/github.com/dave/courtney)](https://goreportcard.com/report/github.com/dave/courtney) [![codecov](https://codecov.io/gh/dave/courtney/branch/master/graph/badge.svg)](https://codecov.io/gh/dave/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 `// 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/dave/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/dave/a/... github.com/dave/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/dave/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/dave/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/dave/courtney
   155    - go get -t -v ./...
   156  script:
   157    - courtney
   158  after_success:
   159    - goveralls -coverprofile=coverage.out -service=travis-ci
   160  ```