it

README

It Should Be Tested.

The library implements a human-friendly syntax for assertions to validates correctness of your code. It's style allows to write BDD-like specifications: "X should Y", "A equals to B", etc.

Inspiration

This library is heavily inspired by features of ScalaTest. It tries to adapt similar syntax for Golang. There is a vision that change of code style in testing helps developers to "switch gears". It's sole purpose to write unit tests assertions in natural language.

It Ok If /* actual */ Should /* expected */

It Ok If x Should Equal 5
It Ok If x Should Not Less 5
It Ok If x Must Less 5

Key features

• assertions with user defined functions
• intercept failures
• check equality
• makes comparison and range checks
• type checks
• match failures and error to given type
• imperative keyword as defined by RFC 2119
• composition/chaining of assertions

Getting Started

The latest version of the library is available at its master branch. All development, including new features and bug fixes, take place on the master branch using forking and pull requests as described in contribution guidelines.

Import the library in your code

import (
  "github.com/fogfish/it"
)

func TestMyFeature(t *testing.T) {
  it.Ok(t).
    If(myfeature()).Should().Equal(5).
    If(myfeature()).Should().Be().Less(10)
}

func myfeature() int {
  return 5
}

See the go doc for api spec.

Syntax at Glance

Each assertion begins with phrase:

func TestMyFeature(t *testing.T) {
  it.Ok(t).If(/*...*/)
}

Then, it continues with one of imperative keyword as defined by RFC 2119 :

• Must the definition is an absolute requirement.
• MustNot the definition is an absolute prohibition.
• Should the definition is a strongly recommended requirement, however it's violation do not block continuation of testing.
• ShouldNot the definition is prohibited, however it's violation do not block continuation of testing.
• May is an optional constrain, its violation do not impact on testing flow in anyway.

The library provides a rich set of asserts

// Assertions with user-defined functions
it.Ok(t).If(three).
  Should().Assert(func(be interface{}) bool {
      (be > 1) && (be < 10) && (be != 5)
  })

// Intercept any failures in target features
it.Ok(t).If(refToCodeBlock).
  Should().Intercept(/* ... */)

// Matches equality and identity
it.Ok(t).
  If(one).Should().Equal(1).
  If(one).Should().Be().A(1)

// Matches type
it.Ok(t).If(one).
  Should().Be().Like(1)

// Matches Order and Ranges
it.Ok(t).
  If(three).Should().Be().Less(10).
  If(three).Should().Be().LessOrEqual(3).
  If(three).Should().Be().Greater(1).
  If(three).Should().Be().GreaterOrEqual(3).
  If(three).Should().Be().In(1, 10)

How To Contribute

The library is MIT licensed and accepts contributions via GitHub pull requests:

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

The build and testing process requires Go version 1.13 or later.

Build and run service in your development console. The following command boots Erlang virtual machine and opens Erlang shell.

git clone https://github.com/fogfish/gurl
cd gurl
go test -cover

commit message

The commit message helps us to write a good release note, speed-up review process. The message should address two question what changed and why. The project follows the template defined by chapter Contributing to a Project of Git book.

bugs

If you experience any issues with the library, please let us know via GitHub issues. We appreciate detailed and accurate reports that help us to identity and replicate the issue.

License

Documentation

Overview

Package it implements a human-friendly syntax for assertions to validates correctness of your code. It's style allows to write BDD-like specifications: "X should Y", "A equals to B", etc.

Inspiration

This library is heavily inspired by features of ScalaTest, see http://www.scalatest.org. It tries to adapt similar syntax for Golang. There is a vision that change of code style in testing helps developers to "switch gears". It's sole purpose to write unit tests assertions in natural language.

It Ok If /* actual */ Should /* expected */

It Ok If f() Should Equal 5
It Ok If f() Should Not Less 5
It Ok If f() Must Less 5

Syntax at Glance

Each assertion begins with phrase:

it Ok If ...

Continues with one of imperative keyword as defined by RFC 2119

Must, Must Not, Should, Should Not, May

Assertions with user-defined functions is a technique to define arbitrary boolean expression.

  it.Ok(t).If(three).
    Should().Assert(func(be interface{}) bool {
	     (be > 1) && (be < 10) && (be != 5)
    })

Intercept any failures in target features

it.Ok(t).If(refToCodeBlock).
   Should().Intercept(/* ... */)

Matches equality and identity

it.Ok(t).
  If(one).Should().Equal(1).
  If(one).Should().Be().A(1)

Matches type

it.Ok(t).If(one).
  Should().Be().Like(1)

Matches Order and Ranges

it.Ok(t).
  If(three).Should().Be().Less(10).
  If(three).Should().Be().LessOrEqual(3).
  If(three).Should().Be().Greater(1).
  If(three).Should().Be().GreaterOrEqual(3).
  If(three).Should().Be().In(1, 10)

Index

• type Be
  • func (t Be) A(expect interface{}) Expr
  • func (t Be) Eq(expect interface{}) Expr
  • func (t Be) Greater(expect interface{}) Expr
  • func (t Be) GreaterOrEqual(expect interface{}) Expr
  • func (t Be) In(a, b interface{}) Expr
  • func (t Be) Less(expect interface{}) Expr
  • func (t Be) LessOrEqual(expect interface{}) Expr
  • func (t Be) Like(expect interface{}) Expr
• type Expr
  • func Ok(t *testing.T) Expr
  • func (t Expr) If(x interface{}) Value
  • func (t Expr) IfFalse(x bool) Expr
  • func (t Expr) IfNil(x interface{}) Expr
  • func (t Expr) IfNotNil(x interface{}) Expr
  • func (t Expr) IfTrue(x bool) Expr
• type Fail
• type Imperative
  • func (t Imperative) Assert(f func(interface{}) bool) Expr
  • func (t Imperative) Be() Be
  • func (t Imperative) Eq(expect interface{}) Expr
  • func (t Imperative) Equal(expect interface{}) Expr
  • func (t Imperative) Equiv(expect interface{}) Expr
  • func (t Imperative) Fail() Expr
  • func (t Imperative) Intercept(err error) Expr
• type Value
  • func (t Value) Equal(expect interface{}) Expr
  • func (t Value) May() Imperative
  • func (t Value) Must() Imperative
  • func (t Value) MustNot() Imperative
  • func (t Value) NotEqual(expect interface{}) Expr
  • func (t Value) Should() Imperative
  • func (t Value) ShouldNot() Imperative

Types

type Be

type Be struct {
	// contains filtered or unexported fields
}

Be is a term of assert expression See Be keyword

func (Be) A

func (t Be) A(expect interface{}) Expr

A matches expected values against actual

it.Ok(t).If(actual).Should().Be().A(expected)

func (Be) Eq

func (t Be) Eq(expect interface{}) Expr

Eq is an alias of A

func (Be) Greater

func (t Be) Greater(expect interface{}) Expr

Greater compares actual against expected value.

it.Ok(t).If(actual).Should().Be().Greater(expected)

func (Be) GreaterOrEqual

func (t Be) GreaterOrEqual(expect interface{}) Expr

GreaterOrEqual compares actual against expected value.

it.Ok(t).If(actual).Should().Be().Greater(expected)

func (Be) In

func (t Be) In(a, b interface{}) Expr

In checks that actual value fits to range

it.Ok(t).If(actual).Should().Be().In(from, to)

func (Be) Less

func (t Be) Less(expect interface{}) Expr

Less compares actual against expected value.

it.Ok(t).If(actual).Should().Be().Less(expected)

func (Be) LessOrEqual

func (t Be) LessOrEqual(expect interface{}) Expr

LessOrEqual compares actual against expected value.

it.Ok(t).If(actual).Should().Be().LessOrEqual(expected)

func (Be) Like

func (t Be) Like(expect interface{}) Expr

Like matches type of expected and actual values. The assert fails if types are different.

it.Ok(t).If(actual).Should().Be().Like(expected)

type Expr

type Expr struct {
	// contains filtered or unexported fields
}

Expr is a term of assert expression See Ok keyword

func Ok

func Ok(t *testing.T) Expr

Ok creates assertion expression, it takes a reference to standard *testing.T interface to setup the evaluation context.

func (Expr) If

func (t Expr) If(x interface{}) Value

If stashes an actual value for evaluation in further statements

func (Expr) IfFalse

func (t Expr) IfFalse(x bool) Expr

IfFalse is an alias to If().Should().Equal(false)

func (Expr) IfNil

func (t Expr) IfNil(x interface{}) Expr

IfNil is an alias to If().Should().Equal(nil)

func (Expr) IfNotNil

func (t Expr) IfNotNil(x interface{}) Expr

IfNotNil is an alias to .Should().Equal(nil)

func (Expr) IfTrue

func (t Expr) IfTrue(x bool) Expr

IfTrue is an alias to If().Should().Equal(true)

type Fail

type Fail struct {
	// contains filtered or unexported fields
}

Fail is a term is assert expression See Fail keyword

type Imperative

type Imperative struct {
	// contains filtered or unexported fields
}

Imperative is a term of assert expression See imperative keywords (Must, MustNot, Should, ShouldNot, May)

func (Imperative) Assert

func (t Imperative) Assert(f func(interface{}) bool) Expr

Assert with user-defined functions is a technique to define arbitrary boolean expression. The stashed value is fed as argument to the function. It fails if the function return false.

  it.Ok(t).If(x).
    Should().Assert(func(be interface{}) bool {
	     (be > 1) && (be < 10) && (be != 5)
    })

func (Imperative) Be

func (t Imperative) Be() Be

Be creates comparison asserts

Should().Be()

func (Imperative) Eq

func (t Imperative) Eq(expect interface{}) Expr

Eq is an alias of Equal

func (Imperative) Equal

func (t Imperative) Equal(expect interface{}) Expr

Equal compares left and right sides. The assert fails if values and types are not equal.

it.Ok(t).If(1).
  Should().Equal(1)

func (Imperative) Equiv

func (t Imperative) Equiv(expect interface{}) Expr

Equiv compares equivalence (same value) of left and right sides. The assert fails if values are not equal but it relaxes types requirements

it.Ok(t).If(1).
  Should().Equiv(1)

func (Imperative) Fail

func (t Imperative) Fail() Expr

Fail catches any errors caused by the function under the test. The assert fails if error is not nil.

func (Imperative) Intercept

func (t Imperative) Intercept(err error) Expr

Intercept catches any errors caused by the function under the test. The assert fails if expected failure do not match.

it.Ok(t).If(refToCodeBlock).
   Should().Intercept(/* ... */)

type Value

type Value struct {
	// contains filtered or unexported fields
}

Value is a term of assert expression See If keyword

func (Value) Equal

func (t Value) Equal(expect interface{}) Expr

Equal is an alias to .Should().Equal(true)

func (Value) May

func (t Value) May() Imperative

May is an optional imperative constrain. Its violation do not impact on testing flow in anyway. The informative warning message is produced to console. Error message will be printed only if the test fails or the -test.v

func (Value) Must

func (t Value) Must() Imperative

Must is imperative keyword. The assert definition is an absolute requirement. It terminates execution of tests if assert is false.

func (Value) MustNot

func (t Value) MustNot() Imperative

MustNot is imperative keyword. The assert definition is an absolute prohibition. It terminates execution of tests if assert is true.

func (Value) NotEqual

func (t Value) NotEqual(expect interface{}) Expr

NotEqual is an alias to .Should().Equal(true)

func (Value) Should

func (t Value) Should() Imperative

Should is imperative keyword. The assert definition is a strongly recommended requirement. However it's violation do not block continuation of testing.

func (Value) ShouldNot

func (t Value) ShouldNot() Imperative

ShouldNot is imperative keyword. The assert definition is prohibited. However it's violation do not block continuation of testing.