qual

README

qual - Go package for quality assessment at src level

Quick start

go get github.com/gregoryv/qual

Add a unit test to your project

func Test_CodeQuality(t *testing.T) {
    qual.Standard(t)
}

or if you are really brave, do

func Test_CodeQuality(t *testing.T) {
    qual.High(t)
}

Assert

This package also provides an assert func for writing clear and concise unittests. Test code in itself if written properly is readable and very contained. It makes a good description in itself if the test should ever fail. However most packages try to solve this by providing short named func for operators within the language. E.g.

assert.Equals(t, a, b, "a and c be should be equal")

This reads fairly well but if you consider adding a couple more of these statements

a, b, c, d := SomeFancyFunc()
assert.Equals(t, a, b, "a and b be should be equal")
assert.NotEquals(t, a, c, "a and c should be different")
assert.NotNil(t, d, "d should not be nil")

now it starts to build up and get repetitive. Using the qual Assert func you can achieve the same thing

a, b, c, d := SomeFancyFunc()
Assert(t, Vars{a,b,c,d},
  a == b,
  a != c,
  d != nil,
)

As you can see there are no textual descriptions of the different assertions. We don't have to describe a == b with a and b should be equal that is how we read the operator ==. Let's assume the above test fails on the assertion a != c then the error would be printed as

> a, b, c, d := SomeFancyFunc()
  failed assert: a != c
    a = 1
	b = 1
	c = 1
	d = nil

What happens is the assert method parses out the context it's called in and prints the nearest line above it, so we know which statement we are actually testing. After that the failed assertions are listed and finaly all the vars that are of interest are printed.

Documentation

Overview

Package qual implements tests and helpers for writing highly readable tests.

Index

• func Assert(t T, v Vars, checks ...bool) (failed bool)
• func CyclomaticComplexity(max int, includeVendor bool, t T)
• func High(t T)
• func LineLength(maxChars, tabSize int, includeVendor bool, t T)
• func Standard(t T)
• type T
• type Vars

Examples

• Assert
• Assert (Nil)
• Assert (Oneline)

Functions

func Assert

func Assert(t T, v Vars, checks ...bool) (failed bool)

Example

// In this example the Assert call fails to show the output.  The
// line just above Assert(...) will be printed for context if an
// error occurs.
val, err := 1, fmt.Errorf("This is an error")
Assert(t, Vars{val, err},
	val == 2,
	err != nil,
)

Output:
> val, err := 1, fmt.Errorf("This is an error")
  failed assert: val == 2
    val = 1
    err = "This is an error"

Example (Nil)

var err error
val, err := 9, nil
Assert(t, Vars{val, err},
	val == 9,
	err != nil,
)

Output:
> val, err := 9, nil
  failed assert: err != nil
    val = 9
    err = nil

Example (Oneline)

val, err := 1, fmt.Errorf("This is an error")
Assert(t, Vars{val, err}, val == 2, err == nil)

Output:
> val, err := 1, fmt.Errorf("This is an error")
  failed assert: val == 2
  failed assert: err == nil
    val = 1
    err = "This is an error"

func CyclomaticComplexity

func CyclomaticComplexity(max int, includeVendor bool, t T)

CyclomaticComplexity fails if max is exceeded in any go files of this project.

func High

func High(t T)

High is the same as Standard, only it includes all vendor source as well.

func LineLength

func LineLength(maxChars, tabSize int, includeVendor bool, t T)

SourceWidth fails if any go file contains lines exceeding maxChars. All lines are considered, source and comments.

func Standard

func Standard(t T)

Standard tests a set of metrics which might be considered necessary for production code. This is very opinionated, but the values are based on community insights from various sources.

Types

type T

type T interface {
	Helper()
	Error(...interface{})
	Errorf(string, ...interface{})
	Log(...interface{})
}

type Vars

type Vars []interface{}

Vars groups variables which will be logged on test failures