Expressive and versatile end-to-end HTTP API testing made easy.

# baloo [![Build Status](https://travis-ci.org/h2non/baloo.svg)](https://travis-ci.org/h2non/baloo) [![GitHub release](https://img.shields.io/badge/version-3.0-orange.svg?style=flat)](https://github.com/h2non/baloo/releases) [![GoDoc](https://godoc.org/github.com/h2non/baloo?status.svg)](https://godoc.org/github.com/h2non/baloo) [![Coverage Status](https://coveralls.io/repos/github/h2non/baloo/badge.svg?branch=master)](https://coveralls.io/github/h2non/baloo?branch=master) [![Go Report Card](https://goreportcard.com/badge/github.com/h2non/baloo)](https://goreportcard.com/report/github.com/h2non/baloo)

Expressive and versatile end-to-end HTTP API testing made easy in [Go](http://golang.org) (golang), built on top of [gentleman](https://github.com/h2non/gentleman) HTTP client toolkit.

Take a look to the [examples](#examples) to get started.

## Features

- Versatile built-in expectations.
- Extensible custom expectations.
- Declarative, expressive, fluent API.
- Response body matching and strict equality expectations.
- Deep JSON comparison.
- JSON Schema validation.
- Full-featured HTTP client built on top of [gentleman](https://github.com/h2non/gentleman) toolkit.
- Intuitive and semantic HTTP client DSL.
- Easy to configure and use.
- Composable chainable assertions.
- Works with Go's `testing` package (more test engines might be added in the future).
- Convenient helpers and abstractions over Go's HTTP primitives.
- Middleware-oriented via gentleman's [middleware layer](https://github.com/h2non/gentleman#middleware).
- Extensible and hackable API.

## Versions

- [v3](https://github.com/h2non/baloo) - Latest stable version with better JSON assertion. Uses `gentleman@v2`. Recommended.
- [v2](https://github.com/h2non/baloo/tree/v2.0.0) - Stable version. Uses `gentleman@v2`.
- [v1](https://github.com/h2non/baloo/tree/v1) - First version. Stable. Uses `gentleman@v1`. Actively maintained.

## Installation

```bash
go get -u gopkg.in/h2non/baloo.v3
```

## Requirements

- Go 1.7+

## Examples

See [examples](https://github.com/h2non/baloo/blob/master/_examples) directory for featured examples.

#### Simple request expectation

```go
package simple

import (
  "testing"

  "gopkg.in/h2non/baloo.v3"
)

// test stores the HTTP testing client preconfigured
var test = baloo.New("http://httpbin.org")

func TestBalooSimple(t *testing.T) {
  test.Get("/get").
    SetHeader("Foo", "Bar").
    Expect(t).
    Status(200).
    Header("Server", "apache").
    Type("json").
    JSON(map[string]string{"bar": "foo"}).
    Done()
}
```

#### Custom assertion function

```go
package custom_assertion

import (
  "errors"
  "net/http"
  "testing"

  "gopkg.in/h2non/baloo.v3"
)

// test stores the HTTP testing client preconfigured
var test = baloo.New("http://httpbin.org")

// assert implements an assertion function with custom validation logic.
// If the assertion fails it should return an error.
func assert(res *http.Response, req *http.Request) error {
  if res.StatusCode >= 400 {
    return errors.New("Invalid server response (> 400)")
  }
  return nil
}

func TestBalooClient(t *testing.T) {
  test.Post("/post").
    SetHeader("Foo", "Bar").
    JSON(map[string]string{"foo": "bar"}).
    Expect(t).
    Status(200).
    Type("json").
    AssertFunc(assert).
    Done()
}
```

#### JSON Schema assertion

```go
package json_schema

import (
  "testing"

  "gopkg.in/h2non/baloo.v3"
)

const schema = `{
  "title": "Example Schema",
  "type": "object",
  "properties": {
    "origin": {
      "type": "string"
    }
  },
  "required": ["origin"]
}`

// test stores the HTTP testing client preconfigured
var test = baloo.New("http://httpbin.org")

func TestJSONSchema(t *testing.T) {
  test.Get("/ip").
    Expect(t).
    Status(200).
    Type("json").
    JSONSchema(schema).
    Done()
}
```

#### Custom global assertion by alias

```go
package alias_assertion

import (
  "errors"
  "net/http"
  "testing"

  "gopkg.in/h2non/baloo.v3"
)

// test stores the HTTP testing client preconfigured
var test = baloo.New("http://httpbin.org")

func assert(res *http.Response, req *http.Request) error {
  if res.StatusCode >= 400 {
    return errors.New("Invalid server response (> 400)")
  }
  return nil
}

func init() {
  // Register assertion function at global level
  baloo.AddAssertFunc("test", assert)
}

func TestBalooClient(t *testing.T) {
  test.Post("/post").
    SetHeader("Foo", "Bar").
    JSON(map[string]string{"foo": "bar"}).
    Expect(t).
    Status(200).
    Type("json").
    Assert("test").
    Done()
}
```

## API

See [godoc reference](https://godoc.org/github.com/h2non/baloo) for detailed API documentation.

### HTTP assertions

#### Status(code int)

Asserts the response HTTP status code to be equal.

#### StatusRange(start, end int)

Asserts the response HTTP status to be within the given numeric range.

#### StatusOk()

Asserts the response HTTP status to be a valid server response (>= 200 && < 400).

#### StatusError()

Asserts the response HTTP status to be a valid clint/server error response (>= 400 && < 600).

#### StatusServerError()

Asserts the response HTTP status to be a valid server error response (>= 500 && < 600).

#### StatusClientError()

Asserts the response HTTP status to be a valid client error response (>= 400 && < 500).

#### Type(kind string)

Asserts the `Content-Type` header. MIME type aliases can be used as `kind` argument.

Supported aliases: `json`, `xml`, `html`, `form`, `text` and `urlencoded`.

#### Header(key, value string)

Asserts a response header field value matches.

Regular expressions can be used as value to perform the specific assertions.

#### HeaderEquals(key, value string)

Asserts a response header field with the given value.

#### HeaderNotEquals(key, value string)

Asserts that a response header field is not equal to the given value.

#### HeaderPresent(key string)

Asserts if a header field is present in the response.

#### HeaderNotPresent(key string)

Asserts if a header field is not present in the response.

#### BodyEquals(value string)

Asserts a response body as string using strict comparison.

Regular expressions can be used as value to perform the specific assertions.

#### BodyMatchString(pattern string)

Asserts a response body matching a string expression.

Regular expressions can be used as value to perform the specific assertions.

#### BodyLength(length int)

Asserts the response body length.

#### JSON(match interface{})

Asserts the response body with the given JSON struct.

#### JSONSchema(schema string)

Asserts the response body againts the given JSON schema definition.

`data` argument can be a `string` containing the JSON schema, a file path
or an URL pointing to the JSON schema definition.

#### Assert(alias string)

Assert adds a new assertion function by alias name.

Assertion function must be previosly registered
via baloo.AddAssertFunc("alias", function).

See [an example here](#custom-global-assertion-by-alias).

#### AssertFunc(func (*http.Response, *http.Request) error)

Adds a new custom assertion function who should return an
detailed error in case that the assertion fails.

## Development

Clone this repository:
```bash
git clone https://github.com/h2non/baloo.git && cd baloo
```

Install dependencies:
```bash
go get -u ./...
```

Run tests:
```bash
go test ./...
```

Lint code:
```bash
go test ./...
```

Run example:
```bash
go test ./_examples/simple/simple_test.go
```

## License

MIT - Tomas Aparicio


baloo

The minimalist generic test assertion library.

Tool for testing cli applications on windows, linux and osx.

commander

Declarative end to end functional testing.

endly

# flute

[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)
[![GoDoc](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)](https://pkg.go.dev/github.com/suzuki-shunsuke/flute/flute)
[![Go Report Card](https://goreportcard.com/badge/github.com/suzuki-shunsuke/flute)](https://goreportcard.com/report/github.com/suzuki-shunsuke/flute)
[![License](http://img.shields.io/badge/license-mit-blue.svg?style=flat-square)](https://raw.githubusercontent.com/suzuki-shunsuke/flute/main/LICENSE)

Golang HTTP client testing framework

## Presentation

https://speakerdeck.com/szksh/flute-golang-http-client-testing-framework

## Overview

`flute` is the Golang HTTP client testing framework.
The goal is

* Test request parameters such as the request path, headers and body
* Mock the HTTP server

`flute.Transport` implements [http.RoundTripper](https://golang.org/pkg/net/http/#RoundTripper).

`flute` uses [testify](https://github.com/stretchr/testify)'s assert internally.
You can test the http request parameters with assert.

For example, the following test failure message means the request header is unexpected value.

```console
=== RUN   TestClient_CreateUser
--- FAIL: TestClient_CreateUser (0.00s)
    tester.go:168:
                Error Trace:    tester.go:168
                                                        tester.go:32
                                                        transport.go:25
                                                        client.go:250
                                                        client.go:174
                                                        client.go:641
                                                        client.go:509
                                                        create_user.go:45
                                                        create_user_test.go:56
                Error:          Not equal:
                                expected: []string{"token XXXXX"}
                                actual  : []string{"token "}

                                Diff:
                                --- Expected
                                +++ Actual
                                @@ -1,3 +1,3 @@
                                 ([]string) (len=1) {
                                - (string) (len=11) "token XXXXX"
                                + (string) (len=6) "token "
                                 }
                Test:           TestClient_CreateUser
                Messages:       the request header "Authorization" should match
                                service: http://example.com
                                request name: create a user
```

Please see [the example](https://github.com/suzuki-shunsuke/flute/blob/v0.6.0/examples/create_user_test.go#L21-L48).

## Example

Please see [examples](examples).

## License

[MIT](LICENSE)


flute

Package for comparing Go values in tests.

# Package for equality of Go values

[![GoDev](https://img.shields.io/static/v1?label=godev&message=reference&color=00add8)][godev]
[![Build Status](https://github.com/google/go-cmp/actions/workflows/test.yml/badge.svg?branch=master)][actions]

This package is intended to be a more powerful and safer alternative to
`reflect.DeepEqual` for comparing whether two values are semantically equal.

The primary features of `cmp` are:

* When the default behavior of equality does not suit the needs of the test,
  custom equality functions can override the equality operation.
  For example, an equality function may report floats as equal so long as they
  are within some tolerance of each other.

* Types that have an `Equal` method may use that method to determine equality.
  This allows package authors to determine the equality operation for the types
  that they define.

* If no custom equality functions are used and no `Equal` method is defined,
  equality is determined by recursively comparing the primitive kinds on both
  values, much like `reflect.DeepEqual`. Unlike `reflect.DeepEqual`, unexported
  fields are not compared by default; they result in panics unless suppressed
  by using an `Ignore` option (see `cmpopts.IgnoreUnexported`) or explicitly
  compared using the `AllowUnexported` option.

See the [documentation][godev] for more information.

This is not an official Google product.

[godev]: https://pkg.go.dev/github.com/google/go-cmp/cmp
[actions]: https://github.com/google/go-cmp/actions

## Install

```
go get -u github.com/google/go-cmp/cmp
```

## License

BSD - See [LICENSE][license] file

[license]: https://github.com/google/go-cmp/blob/master/LICENSE


go-cmp

Hit is an http integration test framework written in golang.

go-hit

Record and replay your HTTP interactions for fast, deterministic and accurate tests.

go-vcr

Composable hamcrest-like matchers for Go assertions.

gocrest

YATSPEC-like BDD testing framework for Go.

# gogiven
An alternative BDD spec framework for go. Builds on "go test" tool and builds on the go testing package.

[![Build status](https://travis-ci.org/corbym/gogiven.svg?branch=master)](https://travis-ci.org/corbym/gogiven/builds)
[![Go Report Card](https://goreportcard.com/badge/github.com/corbym/gogiven)](https://goreportcard.com/report/github.com/corbym/gogiven)
[![GoDoc](https://godoc.org/github.com/corbym/gogiven?status.svg)](http://godoc.org/github.com/corbym/gogiven)
[![Coverage Status](https://coveralls.io/repos/github/corbym/gogiven/badge.svg?branch=master)](https://coveralls.io/github/corbym/gogiven?branch=master)

Inspired by [YATSPEC](https://github.com/bodar/yatspec). Another similar idea is [JGiven](http://jgiven.org), although both are Java based.

Check out the HTML output generator used as a default here: [htmlspec](https://github.com/corbym/htmlspec) - using go's own template/html package.

Feel free to contact me and help improve the code base or let me know if you have any issues or questions!

To contribute, please read [this first.](https://github.com/corbym/gogiven/blob/master/CONTRIBUTING.md)

## Table of Contents
1. [Introduction](#introduction)
2. [Example One - GoGivens in practice](#example)
3. [Example Two - Table Tests](#tabletest-example)
4. [Content Generation](#content-gen)
5. [List of pre-written output generators](#output-generator-list)

## Introduction <a name="introduction"></a>

Go Givens is a lightweight BDD framework for producing test specifications directly from the code you write.

Go Givens parses your test file and produces a human-readable output in a specified directory, containing all the tests, captured data and other related information regarding your test such as success or failure.

Go Givens was inspired by YATSPEC, a BDD framework employed extensively by Sky Network Services (part of Sky, a UK tv company). As mentioned above, another similar product is [JGiven](http://jgiven.org).

### Why?

Capturing your test method as test output is the only real way to show it's intention. You can refactor a test, and have the output update accordingly when the test runs. Unlike other go BDD frameworks, you can use function names to declare intent, and refactoring the function will affect the test. E.g.

```go

//Hello, spec world!
func TestMyTest(...){
	Given(testing, someData()). // This is a test
	When(fooBarBaz()).
	Then(baz())
}

```

.. will be rendered as (but in html, or json, or whatever):

```
My Test
Hello, spec world!

Specification

Given testing some data noting that this is a test
When foo bar baz
Then baz 
```

Test data (set by the func ```someData``` in the example above) can be captured in a map of interesting givens, and as the test progresses, the actuals can be captured in a map of captured inputs and outputs.


### Interesting whats?

Interesting givens are data points that you want to use in your tests that are important for it to function correctly. "Given" data is then used by your application to fulfil some sort of request or process.

Interesting givens are generated as output along side your test output in a table so interested parties can examine them.

### Captured Whos??

Captured inputs and outputs are data points that are registered by either your system under test (stubs, mocks etc) or the output from your system its self.

Captured inputs and outputs are logged along side your test, for each test, so that interested parties can view them.

### That's all great, but still.. WHY would I want to log this stuff??

In BDD, a system's inputs and outputs are important to the business. Capturing the relationships between your data and the way the system handles can be demonstrated to your client. For example, your system could call a 3rd party, and you might want to model the interaction with stubs. 

GoGivens gives you a standardised way of rendering captured data alongside your tests so you don't have to worry about it.


### Rendered how?

The test framework parses your test file, and grabs the content. It strips all non-interesting parts out and leaves the Given/When/Then format in plain text ready for a GoGivensOutputGenerator to process the text. Interesting givens and Captured inputs and outputs are maps, which are rendered alongside your test givens as table data -- interesting givens are tablulated, and captured IO is listed.

A complete example of how to write a GoGivensOutputGenerator is given in the sister project [html spec](https://github.com/corbym/htmlspec) - written in Go.

## Example One - GoGivens in Practice <a name="example"></a>
```go
import (
	"github.com/corbym/gocrest/has"
	"github.com/corbym/gocrest/then"
	"github.com/corbym/gogiven/base"
	"github.com/corbym/gogiven/testdata"
	"testing"
	"github.com/corbym/gocrest/is"
)

func TestMain(testmain *testing.M) {
	runOutput := testmain.Run()
	GenerateTestOutput() // You only need test main GenerateTestOutput() if you want to produce HTML output.
	os.Exit(runOutput)
}

func TestMyFirst(testing *testing.T) {
	Given(testing, someDataSetup).

		When(somethingHappens).

		Then(func(testing base.TestingT, actual testdata.CapturedIO, givens testdata.InterestingGivens) { // passed in testing should be used for assertions
		//do assertions
		then.AssertThat(testing, actual["actual"], is.EqualTo("some output"))
	})
}
```
Note you do not have to use "gocrest" assertions, you can still call all of testing.T's functions to fail the test or you can use any go testing assertion package compatible with testing.T.

When run, the above will produce an HTML output:

[Example Html](https://corbym.github.io/gogiven/example_test.shtml#github.com%2fcorbym%2fgogiven.TestMyFirst)

## Example Two - Table Tests <a name="tabletest-example"></a>

Table tests work the same way as normal go table tests. GoGivens will then mark which test failed, if they do, in your test output. 

Example:

```go
...
func TestMyFirst(testing *testing.T){
   var someRange = []struct {
		actual   string
		expected int
	}{
		{actual: "", expected: 0},
		{actual: "a", expected: 2},
	}
	for _, test := range someRange {
	   tst.Run(test.actual, func(weAreTesting *testing.T) {
	   	Given(weAreTesting, someDataSetup).
			When(someAction).
			Then(func(t TestingT, actual CapturedIO, givens InterestingGivens) {
			//do assertions
		AssertThat(t, actual.CapturedIO["actual"], is.EqualTo("some output"))
	   	})
	   }	
	}
}
...
```

The above test will still fail the test function as far as Go is concerned, but the test output will note that the iteration failed like this:

[Ranged Example Html](https://corbym.github.io/gogiven/example_test.shtml#github.com%2fcorbym%2fgogiven.TestMyFirst_Ranged)

**Note that comments are now rendered. Test function comments appear as part of the spec, and inline comments appear as "Noting that ..". In the above, the comment //do assertions would become "Noting that do assertions".**

### More Examples

* [Full Index](https://corbym.github.io/gogiven/index.shtml) of all tests generated by GoGiven build
* [Skipped test](https://corbym.github.io/gogiven/example_test.shtml#github.com%2fcorbym%2fgogiven.TestMyFirst_Skipped.func1)
* [Without a Given](https://corbym.github.io/gogiven/example_test.shtml#github.com%2fcorbym%2fgogiven.TestWithoutGiven)

# Content Generation <a name="content-gen"></a>

Gogivens comes defaultly configured with an html generator (```htmlspec.NewTestOutputGenerator```) that is consumed by a file generator (```generator.FileOutputGenerator```) (see the godoc for more information). The content generator implements the following interface:

```go
type GoGivensOutputGenerator interface {
	Generate(data *PageData) (output io.Reader)
	//ContentType is text/html, application/json or other mime type
	ContentType() string
}
```

The generated content ```(output io.Reader)``` is then consumed by an OutputListener:


```go
type OutputListener interface {
	Notify(testFilePath string, contentType string, output io.Reader)
}
```

If you want your own output listener just create your own and replace and/or append to the default listeners in your TestMain:

GoGiven's html spec now generates an index file, which is always stored along side the test html output.

```go
func TestMain(testmain *testing.M) {
	gogiven.OutputListeners = []generator.OutputListener{new(MyFooListener)}
	// or alternately (or inclusively!)
	gogiven.OutputListeners = append(OutputListeners, new(MyBarListener))
	runOutput := testmain.Run()
	gogiven.GenerateTestOutput() // generates the output after the test is finished.
	os.Exit(runOutput)
}
```

## Setting the test file output (for the ```generator.FileOutputGenerator```)

You can add the environment variable GOGIVENS_OUTPUT_DIR to your env properties that points to a directory you want goGivens to report the test output to.

Default is the os's tmp directory.

## List of Pre-written Ouput Generators <a name="output-generator-list"></a>

GoGiven comes with the following output generators:

* HTML Spec: https://github.com/corbym/htmlspec - generates the output used in the test example. 
* JSON Spec: https://github.com/corbym/jsonspec - generates the output in JSON format.


gogiven

Idiomatic testing framework for Behavior Driven Development.

- [testcase](#testcase)
  - [Features](#features)
  - [Guide](#guide)
  - [Official API Documentation](#official-api-documentation)
  - [Getting Started / Example](#getting-started--example)
  - [Modules](#modules)
  - [Summary](#summary)
    - [DRY](#dry)
    - [Modularization](#modularization)
  - [Stability](#stability)
  - [Case Study About `testcase` Package Origin](#case-study-about-testcase-package-origin)
  - [Reference Project](#reference-project)



[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)
[![GoDoc](https://godoc.org/go.llib.dev/testcase?status.png)](https://godoc.org/go.llib.dev/testcase)
[![Build Status](https://travis-ci.org/adamluzsi/testcase.svg?branch=master)](https://travis-ci.org/adamluzsi/testcase)
[![Go Report Card](https://goreportcard.com/badge/go.llib.dev/testcase)](https://goreportcard.com/report/go.llib.dev/testcase)
[![codecov](https://codecov.io/gh/adamluzsi/testcase/branch/master/graph/badge.svg)](https://codecov.io/gh/adamluzsi/testcase)
# testcase

The `testcase` package provides tooling to apply BDD testing conventions.

If you use Go1.20, then due to the changes in the stdlib testing package, please upgrade testcase to version `>= v0.131.0`.  

## Features

- lightweight, it has no dependency, you just import testcase, no clutter
- supports classing flattened testing style, table testing style, and nested testing style 
  - [nested testing style](/docs/nested-testing-style.md)
    * allows the usage of an immutable testing subject
    * nesting visualize code complexity
    * testing context building becomes DRY
    * immutable testing subject construction forces disciplined testing conventions
    * supports also the flattened nesting where testing context branches can to a top-level function  
- DDD based testing composition
  * testing components can be defined and reused across the whole project
  * unit tests can be converted into full-fledged E2E tests for CI/CD pipelines
  * dependency injection during testing becomes a breeze to do
  * reusable testing components increase maintainability aspects
  * reusable testing components decrease required ramp-up time for writing new tests that depend on existing components
- safe parallel testing
  * variables stored per test execution, which prevents leakage and race conditions across different tests
- repeatable pseudo-random fixture generation for test input
- repeatable pseudo-random test order shuffling
  * prevents implicit test dependency on ordering
  * ensures that tests can be added and removed freely without the fear of breaking other tests in the same coverage.
  * flaky tests which depend on test execution order can be noticed at development time

## Guide

`testcase` is a powerful TDD Tooling that requires discipline and understanding of the fundamentals of testing.
If you are looking for a guide that helps streamline your knowledge on the topics,
then please consider reading the below-listed articles.
 
- [why to test?](/docs/why-to-test.md)
- [nested testing style With testcase.Specs](/docs/nested-testing-style.md)
- [indirection and abstraction and the use in testing](/docs/interface.md)
- [testing doubles, when to use what](/docs/testing-double/README.md)
- [TDD, Role Interface and Contracts](/docs/contracts.md) [WIP-90%]
- [design system with DRY TDD for long term maintainability wins](/docs/spechelper.md) [WIP-1%]

## Official API Documentation

If you already use the framework, and you just won't pick an example,
you can go directly to the API documentation that is kept in godoc format.
- [godoc](https://godoc.org/go.llib.dev/testcase)
- [pkg.go.dev](https://pkg.go.dev/go.llib.dev/testcase).

## Getting Started / Example

Examples kept in godoc format.
Every exported functionality aims to have examples provided in the official documentation. 
- [pkg.go.dev](https://pkg.go.dev/go.llib.dev/testcase#pkg-examples)
- [godoc](https://godoc.org/go.llib.dev/testcase#pkg-examples)

A Basic examples:

```go
func Test_withTestcaseT(t *testing.T) {
	tc := testcase.NewT(t, nil)
	
	tc.Must.True(true)
	_ = tc.Random.String()
}

func Test_withTestcaseSpec(t *testing.T) {
	s := testcase.NewSpec(t)
	
	s.Test("", func(t *testcase.T) {
		t.Must.True(true)
		_ = tc.Random.String()
	})
}
```

An example with scoped test variables:

```go
package main

import (
	"testing"

	"go.llib.dev/testcase"
)

func TestMyFunc(t *testing.T) {
	s := testcase.NewSpec(t)
	s.NoSideEffect()

	var (
		input = testcase.Let[string](s, nil)
    )
	act := func(t *testcase.T) string {
		return MyFunc(input.Get(t))
	}

	s.When("input is all lowercase", func(s *testcase.Spec) {
		// testing scopes without the input being defined
		// will warn the dev about the missing specification.
		input.LetValue(s, "all lowercase")

		s.Then("it is expected to ...", func(t *testcase.T) {
			t.Must.Equal("all lowercase", act(t))
		})
	})

	s.When("input is all upcase", func(s *testcase.Spec) {
		input.LetValue(s, "ALL UPCASE")

		s.Then("it is expected to ...", func(t *testcase.T) {
			t.Must.Equal("all upcase", act(t))
		})
	})
}
```

## Modules
- [httpspec](/httpspec/README.md)
    * spec module helps you create HTTP API Specs.
- [fixtures](/fixtures/README.md)
    * fixtures module helps you create random input values for testing

## Summary

### DRY

`testcase` provides a way to express common Arrange, Act sections for the Asserts with a DRY principle in mind.

- First, you can define your Act section with a method under test as the subject of your test specification
    * The Act section invokes the method under test with the arranged parameters.
- Then you can build the context of the Act by Arranging the inputs later with humanly explained reasons
    * The Arrange section initializes objects and sets the value of the data that is passed to the method under test.
- And lastly, you can define the test expected outcome in an Assert section.
    * The Assert section verifies that the action of the method under test behaves as expected.

Then adding test edge case to the testing suite becomes easier,
as it will have a concrete place where it must be placed.

And if during the creation of the specification, an edge case turns out to be YAGNI,
it can be noted, so visually it will be easier to see what edge case is not specified for the given subject.

The value it gives is that to build a test for a certain edge case,
the required mental model size to express the context becomes smaller,
as you only have to focus on one Arrange at a time,
until you fully build the bigger picture.

It also implicitly visualize the required mental model of your production code by the nesting.
[You can read more on that in the nesting section](/docs/nesting.md).

### Modularization

On top of the DRY convention, any time you need to Arrange a common scenario about your projects domain event,
you can modularize these setup blocks in a helper function.

This helps the readability of the test while keeping the need for mocks to the minimum as possible for a given test.
As a side effect, integration tests can become low-hanging fruit for the project.

e.g.:
```go
package mypkg_test

import (
	"testing"

	"my/project/mypkg"


	"go.llib.dev/testcase"

	. "my/project/testing/pkg"
)

func TestMyTypeMyFunc(t *testing.T) {
	s := testcase.NewSpec(t)
	
	myUser := GivenWeHaveUser(s)
	// .. other givens

	myType := testcase.Let(s, func(t *testcase.T) *mypkg.MyType {
		return &mypkg.MyType{}
	})

	s.Describe(`.MyFunc`, func(s *testcase.Spec) {
		act := func(t *testcase.T) { myType.Get(t).MyFunc(myUser.Get(t)) }

		s.Then(`edge case description`, func(t *testcase.T) {
			act(t)
		})
	})
}
```

## Stability

- The package is considered stable.
- The package use rolling release conventions.
- No breaking change is planned to the package exported API.
- The package used in production development.
- The package API is only extended if the practical use case proves its necessity.

## [Case Study About `testcase` Package Origin](/docs/history.md)

## Reference Project

- [toggler project, scalable feature toggles on budget for startups](https://github.com/adamluzsi/toggler)
- [frameless project, for a vendor lock free software architecture](https://github.com/adamluzsi/frameless)
- [gorest, a minimalist REST controller for go projects](https://github.com/adamluzsi/gorest)

testcase

A helper for Rails' like test fixtures to test database applications.

# testfixtures

[![PkgGoDev](https://pkg.go.dev/badge/github.com/go-testfixtures/testfixtures/v3?tab=doc)](https://pkg.go.dev/github.com/go-testfixtures/testfixtures/v3?tab=doc)

> ***Warning***: this package will wipe the database data before loading the
fixtures! It is supposed to be used on a test database. Please, double check
if you are running it against the correct database.

> **TIP**: There are options not described in this README page. It's
> recommended that you also check [the documentation][doc].

Writing tests is hard, even more when you have to deal with an SQL database.
This package aims to make writing functional tests for web apps written in
Go easier.

Basically this package mimics the ["Ruby on Rails' way"][railstests] of writing tests
for database applications, where sample data is kept in fixtures files. Before
the execution of every test, the test database is cleaned and the fixture data
is loaded into the database.

The idea is running tests against a real database, instead of relying in mocks,
which is boring to setup and may lead to production bugs not being caught in
the tests.

## Installation

First, import it like this:

```go
import (
        "github.com/go-testfixtures/testfixtures/v3"
)
```

## Usage

Create a folder for the fixture files. Each file should contain data for a
single table and have the name `<table_name>.yml`:

```
myapp/
  myapp.go
  myapp_test.go
  ...
  fixtures/
    posts.yml
    comments.yml
    tags.yml
    posts_tags.yml
    ...
```

The file would look like this (it can have as many record you want):

```yml
# comments.yml
- id: 1
  post_id: 1
  content: A comment...
  author_name: John Doe
  author_email: john@doe.com
  created_at: 2020-12-31 23:59:59
  updated_at: 2020-12-31 23:59:59

- id: 2
  post_id: 2
  content: Another comment...
  author_name: John Doe
  author_email: john@doe.com
  created_at: 2020-12-31 23:59:59
  updated_at: 2020-12-31 23:59:59

# ...
```

An YAML object or array will be converted to JSON. It will be stored on a native
JSON type like JSONB on PostgreSQL & CockroachDB or as a TEXT or VARCHAR column on other
databases.

```yml
- id: 1
  post_attributes:
    author: John Due
    author_email: john@due.com
    title: "..."
    tags:
      - programming
      - go
      - testing
    post: "..."
```

Binary columns can be represented as hexadecimal strings (should start with `0x`):

```yaml
- id: 1
  binary_column: 0x1234567890abcdef
```

If you need to write raw SQL, probably to call a function, prefix the value
of the column with `RAW=`:

```yml
- id: 1
  uuid_column: RAW=uuid_generate_v4()
  postgis_type_column: RAW=ST_GeomFromText('params...')
  created_at: RAW=NOW()
  updated_at: RAW=NOW()
```

Your tests would look like this:

```go
package myapp

import (
        "database/sql"

        _ "github.com/lib/pq"
        "github.com/go-testfixtures/testfixtures/v3"
)

var (
        db *sql.DB
        fixtures *testfixtures.Loader
)

func TestMain(m *testing.M) {
        var err error

        // Open connection to the test database.
        // Do NOT import fixtures in a production database!
        // Existing data would be deleted.
        db, err = sql.Open("postgres", "dbname=myapp_test")
        if err != nil {
                ...
        }

        fixtures, err = testfixtures.New(
                testfixtures.Database(db), // You database connection
                testfixtures.Dialect("postgres"), // Available: "postgresql", "timescaledb", "mysql", "mariadb", "sqlite" and "sqlserver"
                testfixtures.Directory("testdata/fixtures"), // The directory containing the YAML files
        )
        if err != nil {
                ...
        }

        os.Exit(m.Run())
}

func prepareTestDatabase() {
        if err := fixtures.Load(); err != nil {
                ...
        }
}

func TestX(t *testing.T) {
        prepareTestDatabase()

        // Your test here ...
}

func TestY(t *testing.T) {
        prepareTestDatabase()

        // Your test here ...
}

func TestZ(t *testing.T) {
        prepareTestDatabase()

        // Your test here ...
}
```

Alternatively, you can use the `Files` option, to specify which
files you want to load into the database:

```go
fixtures, err := testfixtures.New(
        testfixtures.Database(db),
        testfixtures.Dialect("postgres"),
        testfixtures.Files(
                "fixtures/orders.yml",
                "fixtures/customers.yml",
        ),
)
if err != nil {
        ...
}
```

With `Paths` option, you can specify the paths that fixtures will load
from. Path can be directory or file. If directory, we will search YAML files
in it.

```go
fixtures, err := testfixtures.New(
        testfixtures.Database(db),
        testfixtures.Dialect("postgres"),
        testfixtures.Paths(
                "fixtures/orders.yml",
                "fixtures/customers.yml",
                "common_fixtures/users"
        ),
)
if err != nil {
        ...
}
```

## <a name="singleFileOnMultipleTables"></a> Single file on multiple tables

You can use the `FilesMultiTables` option, to specify which
files you want to load into the database with support multiple tables
(file name does not affect table names):

```go
fixtures, err := testfixtures.New(
        testfixtures.Database(db),
        testfixtures.Dialect("postgres"),
        testfixtures.FilesMultiTables(
                "fixtures/test_case1.yml",
                "fixtures/test_case2.yml",
                "fixtures/posts_comments.yml",
        ),
)
if err != nil {
        ...
}
```

The file would look like this (it can have as many tables and records you want):

```yml
# test_case1.yml
posts:
  - id: 1
    post_id: 1
    content: A comment...
    author_name: John Doe
    author_email: john@doe.com
    created_at: 2020-12-31 23:59:59
    updated_at: 2020-12-31 23:59:59

  - id: 2
    post_id: 2
    content: Another comment...
    author_name: John Doe
    author_email: john@doe.com
    created_at: 2020-12-31 23:59:59
    updated_at: 2020-12-31 23:59:59

comments:
  - id: 1
    post_id: 1
    content: Post 1 comment 1
    author_name: John Doe
    author_email: john@doe.com
    created_at: 2016-01-01 12:30:12
    updated_at: 2016-01-01 12:30:12
# ...
```

## Security check

In order to prevent you from accidentally wiping the wrong database, this
package will refuse to load fixtures if the database name (or database
filename for SQLite) doesn't contains "test". If you want to disable this
check, use:

```go
testfixtures.New(
        ...
        testfixtures.DangerousSkipTestDatabaseCheck(),
)
```

## Disable cleanup

If you want to disable cleanup, you can also do like below.
This is usually not recommended, and should be used mostly for debugging.

```go
testfixtures.New(
        ...
        testfixtures.DangerousSkipCleanupFixtureTables(),
)
```

## Disable checksum computation

Checksums of each table in a database are computed at the end of each `Load()`,
so subsequent calls to `Load()` do not reload the same data again, if nothing
has changed in between.

The drawback is that it can be slow for database with many tables. Also, it does not
make sense to compute checksum, if you run `Load()` only once.

```go
testfixtures.New(
        ...
        testfixtures.SkipTableChecksumComputation(),
)
```

## Sequences

For PostgreSQL and MySQL/MariaDB, this package also resets all
sequences to a high number to prevent duplicated primary keys while
running the tests.
The default is 10000, but you can change that with:

```go
testfixtures.New(
        ...
        testfixtures.ResetSequencesTo(10000),
)
```

Or, if you want to skip the reset of sequences entirely:

```go
testfixtures.New(
        ...
        testfixtures.SkipResetSequences(),
)
```

## Force `DELETE FROM ...` on ClickHouse

By default, when using ClickHouse, this library will use `TRUNCATE ...` to
clean the database. If you want to force the use of `DELETE FROM ...` you can
do it by doing:

```go
testfixtures.New(
        ...
        testfixtures.ClickhouseUseDeleteFrom(),
)
```

## Compatible databases

### PostgreSQL / TimescaleDB / CockroachDB

This package has three approaches to disable foreign keys while importing fixtures
for PostgreSQL databases:

#### With `DISABLE TRIGGER`

This is the default approach. For that use:

```go
testfixtures.New(
        ...
        testfixtures.Dialect("postgres"), // or "timescaledb"
)
```

With the above snippet this package will use `DISABLE TRIGGER` to temporarily
disabling foreign key constraints while loading fixtures. This work with any
version of PostgreSQL, but it is **required** to be connected in the database
as a SUPERUSER. You can make a PostgreSQL user a SUPERUSER with:

```sql
ALTER USER your_user SUPERUSER;
```

#### With `ALTER CONSTRAINT`

This approach don't require to be connected as a SUPERUSER, but only work with
PostgreSQL versions >= 9.4. Try this if you are getting foreign key violation
errors with the previous approach. It is as simple as using:

```go
testfixtures.New(
        ...
        testfixtures.Dialect("postgres"),
        testfixtures.UseAlterConstraint(),
)
```

#### With `DROP CONSTRAINT`

This approach is implemented to support databases that do not support above
methods (namely CockroachDB).

```go
testfixtures.New(
        ...
        testfixtures.Dialect("postgres"),
        testfixtures.UseDropConstraint(),
)
```

Tested using the [github.com/lib/pq](https://github.com/lib/pq) and
[github.com/jackc/pgx](https://github.com/jackc/pgx) drivers.

### MySQL / MariaDB

Just make sure the connection string have
[the multistatement parameter](https://github.com/go-sql-driver/mysql#multistatements)
set to true, and use:

```go
testfixtures.New(
        ...
        testfixtures.Dialect("mysql"), // or "mariadb"
)
```

Tested using the [github.com/go-sql-driver/mysql](https://github.com/go-sql-driver/mysql) driver.

### SQLite

SQLite is also supported. It is recommended to create foreign keys as
`DEFERRABLE` (the default) to prevent problems. See more
[on the SQLite documentation](https://www.sqlite.org/foreignkeys.html#fk_deferred).
(Foreign key constraints are no-op by default on SQLite, but enabling it is
recommended).

```go
testfixtures.New(
        ...
        testfixtures.Dialect("sqlite"),
)
```

Tested using the [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3) driver.

### Microsoft SQL Server

SQL Server support requires SQL Server >= 2008. Inserting on `IDENTITY` columns
are handled as well. Just make sure you are logged in with a user with
`ALTER TABLE` permission.

```go
testfixtures.New(
        ...
        testfixtures.Dialect("sqlserver"),
)
```

Tested using the `mssql` and `sqlserver` drivers from the
[github.com/denisenkom/go-mssqldb](https://github.com/denisenkom/go-mssqldb) lib.

### ClickHouse

```go
testfixtures.New(
        ...
        testfixtures.Dialect("clickhouse"),
)
```

### Spanner with GoogleSQL Dialect

It's impossible to get Spanner database name to determine whether it's a test database or not. You need to make sure that you're actually using test database and use `testfixtures.DangerousSkipTestDatabaseCheck()` to skip the check.

```go
testfixtures.New(
        ...
        testfixtures.Dialect("spanner"),
        testfixtures.DangerousSkipTestDatabaseCheck(),
)
```

## Templating

Testfixtures supports templating, but it's disabled by default. Most people
won't need it, but it may be useful to dynamically generate data.

Enable it by doing:

```go
testfixtures.New(
        ...
        testfixtures.Template(),

        // the above options are optional
        TemplateFuncs(...),
        TemplateDelims("{{", "}}"),
        TemplateOptions("missingkey=zero"),
        TemplateData(...),
)
```

The YAML file could look like this:

```yaml
# It's possible generate values...
- id: {{sha256 "my-awesome-post}}
  title: My Awesome Post
  text: {{randomText}}

# ... or records
{{range $post := $.Posts}}
- id: {{$post.Id}}
  title: {{$post.Title}}
  text: {{$post.Text}}
{{end}}
```

## Generating fixtures for a existing database

The following code will generate a YAML file for each table of the database
into a given folder. It may be useful to boostrap a test scenario from a sample
database of your app.

```go
dumper, err := testfixtures.NewDumper(
        testfixtures.DumpDatabase(db),
        testfixtures.DumpDialect("postgres"), // or your database of choice
        testfixtures.DumpDirectory("tmp/fixtures"),
        testfixtures.DumpTables( // optional, will dump all table if not given
          "posts",
          "comments",
          "tags",
        ),
)
if err != nil {
        ...
}
if err := dumper.Dump(); err != nil {
        ...
}
```

> This was intended to run in small sample databases. It will likely break
if run in a production/big database.

## Gotchas

### Parallel testing

This library doesn't yet support running tests in parallel! Running tests
in parallel can result in random data being present in the database, which
will likely cause tests to randomly/intermittently fail.

This is specially tricky since it's not immediately clear that `go test ./...`
run tests for each package in parallel. If more than one package use this
library, you can face this issue. Please, use `go test -p 1 ./...` or run tests
for each package in separated commands to fix this issue.

If you're looking into being able to run tests in parallel you can try using
testfixtures together with the [txdb][gotxdb] package, which allows wrapping
each test run in a transaction.

## CLI

We also have a CLI to load fixtures in a given database.

Grab it from the [releases page](https://github.com/go-testfixtures/testfixtures/releases)
or install with Homebrew:

```bash
brew install go-testfixtures/tap/testfixtures
```

Usage is like this:

```bash
# load
testfixtures -d postgres -c "postgres://user:password@localhost/database" -D testdata/fixtures
```

```bash
# dump
testfixtures --dump -d postgres -c "postgres://user:password@localhost/database" -D testdata/fixtures
```

The connection string changes for each database driver.

Use `testfixtures --help` for all flags.

## Contributing

We recommend you to [install Task](https://taskfile.dev/installation/) and
Docker before contributing to this package, since some stuff is automated
using these tools.

It's recommended to use Docker Compose to run tests, since it runs tests for
all supported databases once. To do that you just need to run:

```bash
task docker
```

But if you want to run tests locally, copy the `.sample.env` file as `.env`
and edit it according to your database setup. You'll need to create a database
(likely names `testfixtures_test`) before continuing. Then run the command
for the database you want to run tests against:

```bash
task test:pg # PostgreSQL
task test:crdb # CockroachDB
task test:mysql # MySQL
task test:sqlite # SQLite
task test:sqlserver # Microsoft SQL Server
```

GitHub Actions (CI) runs the same Docker setup available locally.

## Alternatives

If you don't think using fixtures is a good idea, you can try one of these
packages instead:

- [factory-go][factorygo]: Factory for Go. Inspired by Python's Factory Boy
and Ruby's Factory Girl
- [fixtory][fixtory]: go generate based type-safe, DRY, flexible test fixture factory
- [go-txdb (Single transaction SQL driver for Go)][gotxdb]: Use a single
database transaction for each functional test, so you can rollback to
previous state between tests to have the same database state in all tests
- [go-sqlmock][gosqlmock]: A mock for the sql.DB interface. This allow you to
unit test database code without having to connect to a real database
- [dbcleaner][dbcleaner] - Clean database for testing, inspired by
database_cleaner for Ruby

[doc]: https://pkg.go.dev/github.com/go-testfixtures/testfixtures/v3?tab=doc
[railstests]: http://guides.rubyonrails.org/testing.html#the-test-database
[gotxdb]: https://github.com/DATA-DOG/go-txdb
[gosqlmock]: https://github.com/DATA-DOG/go-sqlmock
[factorygo]: https://github.com/bluele/factory-go
[fixtory]: https://github.com/k-yomo/fixtory
[dbcleaner]: https://github.com/khaiql/dbcleaner


testfixtures

Quick and easy extendable assertions without introducing much boilerplate.

# Trial [![GoDoc](https://godoc.org/github.com/jgroeneveld/trial/assert?status.svg)](https://godoc.org/github.com/jgroeneveld/trial/assert) [![GoReport](https://goreportcard.com/badge/github.com/jgroeneveld/trial)](https://goreportcard.com/report/github.com/jgroeneveld/trial)

A simple assertion library for go. Also see [schema](https://github.com/jgroeneveld/schema) for easier JSON Schema testing.

[GoCover](https://gocover.io/github.com/jgroeneveld/trial/assert)

## Motivation

go-test is fine. We do not need big testing frameworks for most projects. 
One thing its lacking though is simple assertions and ability to implement simple helpers as it does not allow us to skip
test logs.

Trial gives us `th.Error(t testingT, skip int, msgs ...interface{})` allowing to skip callers to implement helpers with nice logging.

For most uses, the `trial/assert` package is enough, giving us the most basic assertions needed with nice error messages.

## trial/assert Usage

**Simple equals**

```
import "github.com/jgroeneveld/trial/assert"

assert.Equal(t, 1, 2)

Output:
unit_test.go:42: Not equal:
		Expected: 1
		  Actual: 2
```


**Additional arguments** to overwrite the message

```
assert.Equal(t, 1, 2, "numbers dont match for %q", "my param")

Output:
unit_test.go:42: numbers dont match for "my param":
		Expected: 1
		  Actual: 2
```


**Type problems** are made clear

```
assert.Equal(t, 1, int64(1))

unit_test.go:42: Not equal:
		Expected: 1
		  Actual: 1
		   Types: Expected:int, Actual:int64
```

See [example/example_test.go](example/example_test.go) for more.

### Supported Assertions

**Basic assertions**

```
Equal(expected, actual, msgf...)
MustBeEqual(expected, actual, msgf...)
NotEqual(expected, actual, msgf...)
MustNotBeEqual(expected, actual, msgf...)
DeepEqual(expected, actual, msgf...)
MustBeDeepEqual(expected, actual, msgf...)
True(expression bool, msgf...)
MustBeTrue(expression bool, msgf...)
False(expression bool, msgf...)
MustBeFalse(expression bool, msgf...)
Nil(expression, msgf...)
MustBeNil(expression, msgf...)
NotNil(expression, msgf...)
MustNotBeNil(expression, msgf...)
```

**JSON Schema assertions**

```
JSONSchema(reader, matcher, msgf...)
MustMatchJSONSchema(reader, matcher, msgf...)
```

## Writing your own assertions
`th` can be used to write simple own assertions. This for example gives you a wrapper for [schema](https://github.com/jgroeneveld/schema).MatchJSON to have simple JSON schema assertions in your tests:

```go
func AssertJSONSchema(t *testing.T, matcher schema.Matcher, r io.Reader) {
	err := schema.MatchJSON(matcher, r)
	if err != nil {
		th.Error(t, 1, err.Error())
	}
}

func MustMatchJSONSchema(t *testing.T, matcher schema.Matcher, r io.Reader) {
	err := schema.MatchJSON(matcher, r)
	if err != nil {
		th.Error(t, 1, err.Error())
		t.FailNow()
	}
}
```



trial

Mock SQL driver for testing database interactions.

[![Build Status](https://travis-ci.org/DATA-DOG/go-sqlmock.svg)](https://travis-ci.org/DATA-DOG/go-sqlmock)
[![GoDoc](https://godoc.org/github.com/DATA-DOG/go-sqlmock?status.svg)](https://godoc.org/github.com/DATA-DOG/go-sqlmock)
[![Go Report Card](https://goreportcard.com/badge/github.com/DATA-DOG/go-sqlmock)](https://goreportcard.com/report/github.com/DATA-DOG/go-sqlmock)
[![codecov.io](https://codecov.io/github/DATA-DOG/go-sqlmock/branch/master/graph/badge.svg)](https://codecov.io/github/DATA-DOG/go-sqlmock)

# Sql driver mock for Golang

**sqlmock** is a mock library implementing [sql/driver](https://godoc.org/database/sql/driver). Which has one and only
purpose - to simulate any **sql** driver behavior in tests, without needing a real database connection. It helps to
maintain correct **TDD** workflow.

- this library is now complete and stable. (you may not find new changes for this reason)
- supports concurrency and multiple connections.
- supports **go1.8** Context related feature mocking and Named sql parameters.
- does not require any modifications to your source code.
- the driver allows to mock any sql driver method behavior.
- has strict by default expectation order matching.
- has no third party dependencies.

**NOTE:** in **v1.2.0** **sqlmock.Rows** has changed to struct from interface, if you were using any type references to that
interface, you will need to switch it to a pointer struct type. Also, **sqlmock.Rows** were used to implement **driver.Rows**
interface, which was not required or useful for mocking and was removed. Hope it will not cause issues.

## Looking for maintainers

I do not have much spare time for this library and willing to transfer the repository ownership
to person or an organization motivated to maintain it. Open up a conversation if you are interested. See #230.

## Install

    go get github.com/DATA-DOG/go-sqlmock

## Documentation and Examples

Visit [godoc](http://godoc.org/github.com/DATA-DOG/go-sqlmock) for general examples and public api reference.
See **.travis.yml** for supported **go** versions.
Different use case, is to functionally test with a real database - [go-txdb](https://github.com/DATA-DOG/go-txdb)
all database related actions are isolated within a single transaction so the database can remain in the same state.

See implementation examples:

- [blog API server](https://github.com/DATA-DOG/go-sqlmock/tree/master/examples/blog)
- [the same orders example](https://github.com/DATA-DOG/go-sqlmock/tree/master/examples/orders)

### Something you may want to test, assuming you use the [go-mysql-driver](https://github.com/go-sql-driver/mysql)

``` go
package main

import (
	"database/sql"

	_ "github.com/go-sql-driver/mysql"
)

func recordStats(db *sql.DB, userID, productID int64) (err error) {
	tx, err := db.Begin()
	if err != nil {
		return
	}

	defer func() {
		switch err {
		case nil:
			err = tx.Commit()
		default:
			tx.Rollback()
		}
	}()

	if _, err = tx.Exec("UPDATE products SET views = views + 1"); err != nil {
		return
	}
	if _, err = tx.Exec("INSERT INTO product_viewers (user_id, product_id) VALUES (?, ?)", userID, productID); err != nil {
		return
	}
	return
}

func main() {
	// @NOTE: the real connection is not required for tests
	db, err := sql.Open("mysql", "root@/blog")
	if err != nil {
		panic(err)
	}
	defer db.Close()

	if err = recordStats(db, 1 /*some user id*/, 5 /*some product id*/); err != nil {
		panic(err)
	}
}
```

### Tests with sqlmock

``` go
package main

import (
	"fmt"
	"testing"

	"github.com/DATA-DOG/go-sqlmock"
)

// a successful case
func TestShouldUpdateStats(t *testing.T) {
	db, mock, err := sqlmock.New()
	if err != nil {
		t.Fatalf("an error '%s' was not expected when opening a stub database connection", err)
	}
	defer db.Close()

	mock.ExpectBegin()
	mock.ExpectExec("UPDATE products").WillReturnResult(sqlmock.NewResult(1, 1))
	mock.ExpectExec("INSERT INTO product_viewers").WithArgs(2, 3).WillReturnResult(sqlmock.NewResult(1, 1))
	mock.ExpectCommit()

	// now we execute our method
	if err = recordStats(db, 2, 3); err != nil {
		t.Errorf("error was not expected while updating stats: %s", err)
	}

	// we make sure that all expectations were met
	if err := mock.ExpectationsWereMet(); err != nil {
		t.Errorf("there were unfulfilled expectations: %s", err)
	}
}

// a failing test case
func TestShouldRollbackStatUpdatesOnFailure(t *testing.T) {
	db, mock, err := sqlmock.New()
	if err != nil {
		t.Fatalf("an error '%s' was not expected when opening a stub database connection", err)
	}
	defer db.Close()

	mock.ExpectBegin()
	mock.ExpectExec("UPDATE products").WillReturnResult(sqlmock.NewResult(1, 1))
	mock.ExpectExec("INSERT INTO product_viewers").
		WithArgs(2, 3).
		WillReturnError(fmt.Errorf("some error"))
	mock.ExpectRollback()

	// now we execute our method
	if err = recordStats(db, 2, 3); err == nil {
		t.Errorf("was expecting an error, but there was none")
	}

	// we make sure that all expectations were met
	if err := mock.ExpectationsWereMet(); err != nil {
		t.Errorf("there were unfulfilled expectations: %s", err)
	}
}
```

## Customize SQL query matching

There were plenty of requests from users regarding SQL query string validation or different matching option.
We have now implemented the `QueryMatcher` interface, which can be passed through an option when calling
`sqlmock.New` or `sqlmock.NewWithDSN`.

This now allows to include some library, which would allow for example to parse and validate `mysql` SQL AST.
And create a custom QueryMatcher in order to validate SQL in sophisticated ways.

By default, **sqlmock** is preserving backward compatibility and default query matcher is `sqlmock.QueryMatcherRegexp`
which uses expected SQL string as a regular expression to match incoming query string. There is an equality matcher:
`QueryMatcherEqual` which will do a full case sensitive match.

In order to customize the QueryMatcher, use the following:

``` go
	db, mock, err := sqlmock.New(sqlmock.QueryMatcherOption(sqlmock.QueryMatcherEqual))
```

The query matcher can be fully customized based on user needs. **sqlmock** will not
provide a standard sql parsing matchers, since various drivers may not follow the same SQL standard.

## Matching arguments like time.Time

There may be arguments which are of `struct` type and cannot be compared easily by value like `time.Time`. In this case
**sqlmock** provides an [Argument](https://godoc.org/github.com/DATA-DOG/go-sqlmock#Argument) interface which
can be used in more sophisticated matching. Here is a simple example of time argument matching:

``` go
type AnyTime struct{}

// Match satisfies sqlmock.Argument interface
func (a AnyTime) Match(v driver.Value) bool {
	_, ok := v.(time.Time)
	return ok
}

func TestAnyTimeArgument(t *testing.T) {
	t.Parallel()
	db, mock, err := sqlmock.New()
	if err != nil {
		t.Errorf("an error '%s' was not expected when opening a stub database connection", err)
	}
	defer db.Close()

	mock.ExpectExec("INSERT INTO users").
		WithArgs("john", AnyTime{}).
		WillReturnResult(sqlmock.NewResult(1, 1))

	_, err = db.Exec("INSERT INTO users(name, created_at) VALUES (?, ?)", "john", time.Now())
	if err != nil {
		t.Errorf("error '%s' was not expected, while inserting a row", err)
	}

	if err := mock.ExpectationsWereMet(); err != nil {
		t.Errorf("there were unfulfilled expectations: %s", err)
	}
}
```

It only asserts that argument is of `time.Time` type.

## Run tests

    go test -race

## Change Log

- **2019-04-06** - added functionality to mock a sql MetaData request
- **2019-02-13** - added `go.mod` removed the references and suggestions using `gopkg.in`.
- **2018-12-11** - added expectation of Rows to be closed, while mocking expected query.
- **2018-12-11** - introduced an option to provide **QueryMatcher** in order to customize SQL query matching.
- **2017-09-01** - it is now possible to expect that prepared statement will be closed,
  using **ExpectedPrepare.WillBeClosed**.
- **2017-02-09** - implemented support for **go1.8** features. **Rows** interface was changed to struct
  but contains all methods as before and should maintain backwards compatibility. **ExpectedQuery.WillReturnRows** may now
  accept multiple row sets.
- **2016-11-02** - `db.Prepare()` was not validating expected prepare SQL
  query. It should still be validated even if Exec or Query is not
  executed on that prepared statement.
- **2016-02-23** - added **sqlmock.AnyArg()** function to provide any kind
  of argument matcher.
- **2016-02-23** - convert expected arguments to driver.Value as natural
  driver does, the change may affect time.Time comparison and will be
  stricter. See [issue](https://github.com/DATA-DOG/go-sqlmock/issues/31).
- **2015-08-27** - **v1** api change, concurrency support, all known issues fixed.
- **2014-08-16** instead of **panic** during reflect type mismatch when comparing query arguments - now return error
- **2014-08-14** added **sqlmock.NewErrorResult** which gives an option to return driver.Result with errors for
interface methods, see [issue](https://github.com/DATA-DOG/go-sqlmock/issues/5)
- **2014-05-29** allow to match arguments in more sophisticated ways, by providing an **sqlmock.Argument** interface
- **2014-04-21** introduce **sqlmock.New()** to open a mock database connection for tests. This method
calls sql.DB.Ping to ensure that connection is open, see [issue](https://github.com/DATA-DOG/go-sqlmock/issues/4).
This way on Close it will surely assert if all expectations are met, even if database was not triggered at all.
The old way is still available, but it is advisable to call db.Ping manually before asserting with db.Close.
- **2014-02-14** RowsFromCSVString is now a part of Rows interface named as FromCSVString.
It has changed to allow more ways to construct rows and to easily extend this API in future.
See [issue 1](https://github.com/DATA-DOG/go-sqlmock/issues/1)
**RowsFromCSVString** is deprecated and will be removed in future

## Contributions

Feel free to open a pull request. Note, if you wish to contribute an extension to public (exported methods or types) -
please open an issue before, to discuss whether these changes can be accepted. All backward incompatible changes are
and will be treated cautiously

## License

The [three clause BSD license](http://en.wikipedia.org/wiki/BSD_licenses)



go-sqlmock

HTTP mock for Golang: record and replay HTTP interactions for offline testing.

govcr

HTTP(S) proxy for recording and simulating REST/SOAP APIs with extensible middleware and easy-to-use CLI.

![Hoverfly](https://raw.githubusercontent.com/SpectoLabs/hoverfly/master/hoverfly_logo.png)

[![Circle CI][CircleCI-Image]][CircleCI-Url] 
[![Documentation Status](https://readthedocs.org/projects/hoverfly/badge/?version=latest)](http://hoverfly.readthedocs.io/en/latest/?badge=latest)
[![Join the chat at https://gitter.im/SpectoLabs/hoverfly](https://badges.gitter.im/SpectoLabs/hoverfly.svg)](https://gitter.im/SpectoLabs/hoverfly?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

## API simulations for development and testing

Hoverfly is a lightweight, open source API simulation tool. Using Hoverfly, you can create realistic simulations of the APIs your application depends on.

* Replace slow, flaky API dependencies with realistic, re-usable simulations
* Simulate network latency, random failures or rate limits to test edge-cases
* Extend and customize with any programming language
* Export, share, edit and import API simulations
* CLI and native language bindings for [Java](https://hoverfly-java.readthedocs.io/en/latest/)
* REST API
* Lightweight, high-performance, run anywhere
* Apache 2 license

Hoverfly is developed and maintained by [iOCO Solutions](https://ioco.uk/).

## Quickstart

* [Download and installation](https://hoverfly.readthedocs.io/en/latest/pages/introduction/downloadinstallation.html)
* [Read the docs](https://hoverfly.readthedocs.io)
* [Join the mailing list](https://groups.google.com/a/specto.io/forum/#!forum/hoverfly)

## Hoverfly Cloud

Hoverfly Cloud - API simulations as a service. [Sign up here.](https://hoverfly.io/hoverfly-cloud)

## Contributing

Contributions are welcome!

To contribute, please:

1. Fork the repository
1. Create a feature branch on your fork
1. Commit your changes, and create a pull request against Hoverfly's master branch
1. In your pull request, include details regarding your change, i.e
    1. why you made it
    1. how to test it
    1. any information about testing you have performed

To read more about forking model, check out this link: [forking workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow).


## Setup for local development

### Build
1. Install Go. You should follow the download and installation instructions for your OS from [official Go website](https://golang.org/dl). If you have installed Go before 
using either `apt-get` or `homebrew`, you should uninstall those first.
1. Clone the hoverfly project:
    ```bash
    git clone https://github.com/SpectoLabs/hoverfly.git
    # or: git clone https://github.com/<your_username>/hoverfly.git
    ```
1. Finally you can run the build

    ```bash
    cd hoverfly
    make build 
    ```

Notice the binaries are in the ``target`` directory.


### Test

You should be able to execute all unit and functional tests with: 

```bash
make test
```

Some middleware tests may fail if you don't have `ruby` and `python` setup in your environment. If you are using Mac, you can install them with [Homebrew](https://brew.sh/):
```bash
brew install ruby
brew install python
``` 


## License

Apache License version 2.0 [See LICENSE for details](https://github.com/SpectoLabs/hoverfly/blob/master/LICENSE).

(c) [iOCO](https://ioco.uk/) 2024.

[CircleCI-Image]: https://circleci.com/gh/SpectoLabs/hoverfly.svg?style=shield
[CircleCI-Url]: https://circleci.com/gh/SpectoLabs/hoverfly


hoverfly

Easy mocking of HTTP responses from external resources.

httpmock

![logo](https://rawgit.com/gojuno/minimock/master/logo.svg)
[![GoDoc](https://godoc.org/github.com/gojuno/minimock?status.svg)](http://godoc.org/github.com/gojuno/minimock) 
[![Go Report Card](https://goreportcard.com/badge/github.com/gojuno/minimock)](https://goreportcard.com/report/github.com/gojuno/minimock)
[![Release](https://img.shields.io/github/release/gojuno/minimock.svg)](https://github.com/gojuno/minimock/releases/latest)
[![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/avelino/awesome-go#testing)


## Summary 
Minimock generates mocks out of Go interface declarations.

The main features of minimock are:

* It generates statically typed mocks and helpers. There's no need for type assertions when you use minimock.
* It's fully integrated with the standard Go "testing" package.
* It's ready for Go modules.
* It supports generics.
* It works well with [table driven tests](https://dave.cheney.net/2013/06/09/writing-table-driven-tests-in-go) because you can set up mocks for several methods in one line of code using the builder pattern.
* It can generate several mocks in one run.
* It can generate mocks from interface aliases.
* It generates code that passes default set of [golangci-lint](https://github.com/golangci/golangci-lint) checks.
* It puts //go:generate instruction into the generated code, so all you need to do when the source interface is updated is to run the `go generate ./...` command from within the project's directory.
* It makes sure that all mocked methods have been called during the test and keeps your test code clean and up to date.
* It provides When and Then helpers to set up several expectations and results for any method.
* It generates concurrent-safe mocks and mock invocation counters that you can use to manage mock behavior depending on the number of calls.
* It can be used with the [GoUnit](https://github.com/hexdigest/gounit) tool which generates table-driven tests that make use of minimock.

## Installation

If you use go modules please download the [latest binary](https://github.com/gojuno/minimock/releases/latest)
or install minimock from source:
```
go install github.com/gojuno/minimock/v3/cmd/minimock@latest
```

If you don't use go modules please find the latest v2.x binary [here](https://github.com/gojuno/minimock/releases)
or install minimock using [v2 branch](https://github.com/gojuno/minimock/tree/v2)

## Usage

```
 minimock [-i source.interface] [-o output/dir/or/file.go] [-g]
  -g	don't put go:generate instruction into the generated code
  -h	show this help message
  -i string
    	comma-separated names of the interfaces to mock, i.e fmt.Stringer,io.Reader
    	use io.* notation to generate mocks for all interfaces in the "io" package (default "*")
  -o string
    	comma-separated destination file names or packages to put the generated mocks in,
    	by default the generated mock is placed in the source package directory
  -p string 
        comma-separated package names,
        by default the generated package names are taken from the destination directory names
  -s string
    	mock file suffix (default "_mock_test.go")
```

Let's say we have the following interface declaration in github.com/gojuno/minimock/tests package:
```go
type Formatter interface {
	Format(string, ...interface{}) string
}
```

This will generate mocks for all interfaces defined in the "tests" package:

```
$ cd ~/go/src/github.com/gojuno/minimock/tests
$ minimock 
```

Here is how to generate a mock for the "Formatter" interface only:

```
$ cd ~/go/src/github.com/gojuno/minimock/tests
$ minimock -i Formatter 
```

Same using the relative package notation:

```
$ minimock -i ./tests.Formatter
```

Same using the full import path of the source package:

```
$ minimock -i github.com/gojuno/minimock/tests.Formatter -o ./tests/
```

All the examples above generate ./tests/formatter_mock_test.go file


Now it's time to use the generated mock. There are several ways it can be done.

### Setting up a mock using the builder pattern and Expect/Return methods:
```go
mc := minimock.NewController(t)
formatterMock := NewFormatterMock(mc).FormatMock.Expect("hello %s!", "world").Return("hello world!")
```

The builder pattern is convenient when you have more than one method to mock.
Let's say we have an io.ReadCloser interface which has two methods: Read and Close
```go
type ReadCloser interface {
	Read(p []byte) (n int, err error)
	Close() error
}
```

We can set up a mock using a simple one-liner:
```go
mc := minimock.NewController(t)
readCloserMock := NewReadCloserMock(mc).ReadMock.Expect([]byte(1,2,3)).Return(3, nil).CloseMock.Return(nil)
```

But what if we don't want to check all arguments of the read method?
Let's say we just want to check that the second element of the given slice "p" is 2.
This is where "Inspect" helper comes into play:
```go
mc := minimock.NewController(t)
readCloserMock := NewReadCloserMock(mc).ReadMock.Inspect(func(p []byte){
  assert.Equal(mc, 2, p[1])
}).Return(3, nil).CloseMock.Return(nil)

```

### Setting up a mock using ExpectParams helpers:

Let's say we have a mocking interface with function that has many arguments:
```go
type If interface {
	Do(intArg int, stringArg string, floatArg float)
}
```

Imagine that you don't want to check all the arguments, just one or two of them.
Then we can use ExpectParams helpers, which are generated for each argument:
```go
mc := minimock.NewController(t)
ifMock := NewIfMock(mc).DoMock.ExpectIntArgParam1(10).ExpectFloatArgParam3(10.2).Return()
```

### Setting up a mock using When/Then helpers:
```go
mc := minimock.NewController(t)
formatterMock := NewFormatterMock(mc)
formatterMock.FormatMock.When("Hello %s!", "world").Then("Hello world!")
formatterMock.FormatMock.When("Hi %s!", "there").Then("Hi there!")
```

alternatively you can use the one-liner:

```go
formatterMock = NewFormatterMock(mc).When("Hello %s!", "world").Then("Hello world!").When("Hi %s!", "there").Then("Hi there!")
```

### Setting up a mock using the Set method:
```go
mc := minimock.NewController(t)
formatterMock := NewFormatterMock(mc).FormatMock.Set(func(string, ...interface{}) string {
  return "minimock"
})
```

You can also use invocation counters in your mocks and tests:
```go
mc := minimock.NewController(t)
formatterMock := NewFormatterMock(mc)
formatterMock.FormatMock.Set(func(string, ...interface{}) string {
  return fmt.Sprintf("minimock: %d", formatterMock.BeforeFormatCounter())
})
```

### Setting up expected times mock was called:
Imagine you expect mock to be called exactly 10 times. 
Then you can set `Times` helper to check how many times mock was invoked.

```go
mc := minimock.NewController(t)
formatterMock := NewFormatterMock(mc).FormatMock.Times(10).Expect("hello %s!", "world").Return("hello world!")
```

There are also cases, when you don't know for sure if the mocking method would be called or not. 
But you still want to mock it, if it will be called. This is where "Optional" option comes into play:

```go
mc := minimock.NewController(t)
formatterMock := NewFormatterMock(mc).FormatMock.Optional().Expect("hello %s!", "world").Return("hello world!")
```

When this option is set, it disables checking the call of mocking method. 

### Mocking context
Sometimes context gets modified by the time the mocked method is being called.
However, in most cases you don't really care about the exact value of the context argument.
In such cases you can use special `minimock.AnyContext` variable, here are a couple of examples:

```go
mc := minimock.NewController(t)
senderMock := NewSenderMock(mc).
  SendMock.
    When(minimock.AnyContext, "message1").Then(nil).
    When(minimock.AnyContext, "message2").Then(errors.New("invalid message"))
```

or using Expect:

```go
mc := minimock.NewController(t)
senderMock := NewSenderMock(mc).
  SendMock.Expect(minimock.AnyContext, "message").Return(nil)
```

### Make sure that your mocks are being used 
Often we write tons of mocks to test our code but sometimes the tested code stops using mocked dependencies.
You can easily identify this problem by using `minimock.NewController` instead of just `*testing.T`. 
Alternatively you can use `mc.Wait` helper if your're testing concurrent code.
These helpers ensure that all your mocks and expectations have been used at least once during the test run.

```go
func TestSomething(t *testing.T) {
  // it will mark this example test as failed because there are no calls
  // to formatterMock.Format() and readCloserMock.Read() below
  mc := minimock.NewController(t)

  formatterMock := NewFormatterMock(mc)
  formatterMock.FormatMock.Return("minimock")

  readCloserMock := NewReadCloserMock(mc)
  readCloserMock.ReadMock.Return(5, nil)
}
```

### Testing concurrent code
Testing concurrent code is tough. Fortunately minimock.Controller provides you with the helper method that makes testing concurrent code easy.
Here is how it works:

```go
func TestSomething(t *testing.T) {
  mc := minimock.NewController(t)

  //Wait ensures that all mocked methods have been called within the given time span
  //if any of the mocked methods have not been called Wait marks the test as failed
  defer mc.Wait(time.Second)

  formatterMock := NewFormatterMock(mc)
  formatterMock.FormatMock.Return("minimock")

  //tested code can run the mocked method in a goroutine
  go formatterMock.Format("hello world!")
}
```

## Using GoUnit with minimock

Writing test is not only mocking the dependencies. Often the test itself contains a lot of boilerplate code.
You can generate test stubs using [GoUnit](https://github.com/hexdigest/gounit) tool which has a nice template that uses minimock.

Happy mocking!


The Best Go Libraries For Testing - Libraries for testing codebases and generating test data. (19)