sqlmock

package module
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 1, 2017 License: BSD-3-Clause Imports: 12 Imported by: 0

README

Build Status GoDoc codecov.io

Sql driver mock for Golang

sqlmock is a mock library implementing 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.

Install

go get gopkg.in/DATA-DOG/go-sqlmock.v1

Documentation and Examples

Visit godoc 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 all database related actions are isolated within a single transaction so the database can remain in the same state.

See implementation examples:

Something you may want to test
package main

import "database/sql"

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
package main

import (
	"fmt"
	"testing"

	"gopkg.in/DATA-DOG/go-sqlmock.v1"
)

// 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 expections: %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 expections: %s", err)
	}
}

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 interface which can be used in more sophisticated matching. Here is a simple example of time argument matching:

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 := 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(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 expections: %s", err)
	}
}

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

Run tests

go test -race

Change Log

  • 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.
  • 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
  • 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. 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 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

Documentation

Overview

Package sqlmock is a mock library implementing 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.

It does not require any modifications to your source code in order to test and mock database operations. Supports concurrency and multiple database mocking.

The driver allows to mock any sql driver method behavior.

Example 
// Open new mock database
db, mock, err := New()
if err != nil {
	fmt.Println("error creating mock database")
	return
}
// columns to be used for result
columns := []string{"id", "status"}
// expect transaction begin
mock.ExpectBegin()
// expect query to fetch order, match it with regexp
mock.ExpectQuery("SELECT (.+) FROM orders (.+) FOR UPDATE").
	WithArgs(1).
	WillReturnRows(NewRows(columns).AddRow(1, 1))
// expect transaction rollback, since order status is "cancelled"
mock.ExpectRollback()

// run the cancel order function
someOrderID := 1
// call a function which executes expected database operations
err = cancelOrder(db, someOrderID)
if err != nil {
	fmt.Printf("unexpected error: %s", err)
	return
}

// ensure all expectations have been met
if err = mock.ExpectationsWereMet(); err != nil {
	fmt.Printf("unmet expectation error: %s", err)
}

Output:

Index

Examples

Constants

This section is empty.

Variables

View Source 
var CSVColumnParser = func(s string) []byte {
	switch {
	case strings.ToLower(s) == "null":
		return nil
	}
	return []byte(s)
}

CSVColumnParser is a function which converts trimmed csv column string to a []byte representation. currently transforms NULL to nil

View Source 
var ErrCancelled = errors.New("canceling query due to user request")

Functions

func NewErrorResult 

func NewErrorResult(err error) driver.Result

NewErrorResult creates a new sql driver Result which returns an error given for both interface methods

Example 
db, mock, _ := New()
result := NewErrorResult(fmt.Errorf("some error"))
mock.ExpectExec("^INSERT (.+)").WillReturnResult(result)
res, _ := db.Exec("INSERT something")
_, err := res.LastInsertId()
fmt.Println(err)

Output:

some error

func NewResult 

func NewResult(lastInsertID int64, rowsAffected int64) driver.Result

NewResult creates a new sql driver Result for Exec based query mocks.

Example 
var lastInsertID, affected int64
result := NewResult(lastInsertID, affected)
mock.ExpectExec("^INSERT (.+)").WillReturnResult(result)
fmt.Println(mock.ExpectationsWereMet())

Output:

there is a remaining expectation which was not matched: ExpectedExec => expecting Exec or ExecContext which:
  - matches sql: '^INSERT (.+)'
  - is without arguments
  - should return Result having:
      LastInsertId: 0
      RowsAffected: 0

Types

type Argument 

type Argument interface {
	Match(driver.Value) bool
}

Argument interface allows to match any argument in specific way when used with ExpectedQuery and ExpectedExec expectations.

func AnyArg 

func AnyArg() Argument

AnyArg will return an Argument which can match any kind of arguments.

Useful for time.Time or similar kinds of arguments.

type ExpectedBegin 

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

ExpectedBegin is used to manage *sql.DB.Begin expectation returned by *Sqlmock.ExpectBegin.

func (*ExpectedBegin) String 

func (e *ExpectedBegin) String() string

String returns string representation

func (*ExpectedBegin) WillDelayFor 

func (e *ExpectedBegin) WillDelayFor(duration time.Duration) *ExpectedBegin

WillDelayFor allows to specify duration for which it will delay result. May be used together with Context

func (*ExpectedBegin) WillReturnError 

func (e *ExpectedBegin) WillReturnError(err error) *ExpectedBegin

WillReturnError allows to set an error for *sql.DB.Begin action

type ExpectedClose 

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

ExpectedClose is used to manage *sql.DB.Close expectation returned by *Sqlmock.ExpectClose.

func (*ExpectedClose) String 

func (e *ExpectedClose) String() string

String returns string representation

func (*ExpectedClose) WillReturnError 

func (e *ExpectedClose) WillReturnError(err error) *ExpectedClose

WillReturnError allows to set an error for *sql.DB.Close action

type ExpectedCommit 

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

ExpectedCommit is used to manage *sql.Tx.Commit expectation returned by *Sqlmock.ExpectCommit.

func (*ExpectedCommit) String 

func (e *ExpectedCommit) String() string

String returns string representation

func (*ExpectedCommit) WillReturnError 

func (e *ExpectedCommit) WillReturnError(err error) *ExpectedCommit

WillReturnError allows to set an error for *sql.Tx.Close action

type ExpectedExec 

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

ExpectedExec is used to manage *sql.DB.Exec, *sql.Tx.Exec or *sql.Stmt.Exec expectations. Returned by *Sqlmock.ExpectExec.

Example 
db, mock, _ := New()
result := NewErrorResult(fmt.Errorf("some error"))
mock.ExpectExec("^INSERT (.+)").WillReturnResult(result)
res, _ := db.Exec("INSERT something")
_, err := res.LastInsertId()
fmt.Println(err)

Output:

some error

func (*ExpectedExec) String 

func (e *ExpectedExec) String() string

String returns string representation

func (*ExpectedExec) WillDelayFor 

func (e *ExpectedExec) WillDelayFor(duration time.Duration) *ExpectedExec

WillDelayFor allows to specify duration for which it will delay result. May be used together with Context

func (*ExpectedExec) WillReturnError 

func (e *ExpectedExec) WillReturnError(err error) *ExpectedExec

WillReturnError allows to set an error for expected database exec action

func (*ExpectedExec) WillReturnResult 

func (e *ExpectedExec) WillReturnResult(result driver.Result) *ExpectedExec

WillReturnResult arranges for an expected Exec() to return a particular result, there is sqlmock.NewResult(lastInsertID int64, affectedRows int64) method to build a corresponding result. Or if actions needs to be tested against errors sqlmock.NewErrorResult(err error) to return a given error.

func (*ExpectedExec) WithArgs 

func (e *ExpectedExec) WithArgs(args ...driver.Value) *ExpectedExec

WithArgs will match given expected args to actual database exec operation arguments. if at least one argument does not match, it will return an error. For specific arguments an sqlmock.Argument interface can be used to match an argument.

type ExpectedPrepare 

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

ExpectedPrepare is used to manage *sql.DB.Prepare or *sql.Tx.Prepare expectations. Returned by *Sqlmock.ExpectPrepare.

func (*ExpectedPrepare) ExpectExec 

func (e *ExpectedPrepare) ExpectExec() *ExpectedExec

ExpectExec allows to expect Exec() on this prepared statement. this method is convenient in order to prevent duplicating sql query string matching.

func (*ExpectedPrepare) ExpectQuery 

func (e *ExpectedPrepare) ExpectQuery() *ExpectedQuery

ExpectQuery allows to expect Query() or QueryRow() on this prepared statement. this method is convenient in order to prevent duplicating sql query string matching.

func (*ExpectedPrepare) String 

func (e *ExpectedPrepare) String() string

String returns string representation

func (*ExpectedPrepare) WillBeClosed 

func (e *ExpectedPrepare) WillBeClosed() *ExpectedPrepare

WillBeClosed expects this prepared statement to be closed.

func (*ExpectedPrepare) WillDelayFor 

func (e *ExpectedPrepare) WillDelayFor(duration time.Duration) *ExpectedPrepare

WillDelayFor allows to specify duration for which it will delay result. May be used together with Context

func (*ExpectedPrepare) WillReturnCloseError 

func (e *ExpectedPrepare) WillReturnCloseError(err error) *ExpectedPrepare

WillReturnCloseError allows to set an error for this prepared statement Close action

func (*ExpectedPrepare) WillReturnError 

func (e *ExpectedPrepare) WillReturnError(err error) *ExpectedPrepare

WillReturnError allows to set an error for the expected *sql.DB.Prepare or *sql.Tx.Prepare action.

type ExpectedQuery 

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

ExpectedQuery is used to manage *sql.DB.Query, *dql.DB.QueryRow, *sql.Tx.Query, *sql.Tx.QueryRow, *sql.Stmt.Query or *sql.Stmt.QueryRow expectations. Returned by *Sqlmock.ExpectQuery.

func (*ExpectedQuery) String 

func (e *ExpectedQuery) String() string

String returns string representation

func (*ExpectedQuery) WillDelayFor 

func (e *ExpectedQuery) WillDelayFor(duration time.Duration) *ExpectedQuery

WillDelayFor allows to specify duration for which it will delay result. May be used together with Context

func (*ExpectedQuery) WillReturnError 

func (e *ExpectedQuery) WillReturnError(err error) *ExpectedQuery

WillReturnError allows to set an error for expected database query

func (*ExpectedQuery) WillReturnRows 

func (e *ExpectedQuery) WillReturnRows(rows ...*Rows) *ExpectedQuery

WillReturnRows specifies the set of resulting rows that will be returned by the triggered query

func (*ExpectedQuery) WithArgs 

func (e *ExpectedQuery) WithArgs(args ...driver.Value) *ExpectedQuery

WithArgs will match given expected args to actual database query arguments. if at least one argument does not match, it will return an error. For specific arguments an sqlmock.Argument interface can be used to match an argument.

type ExpectedRollback 

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

ExpectedRollback is used to manage *sql.Tx.Rollback expectation returned by *Sqlmock.ExpectRollback.

func (*ExpectedRollback) String 

func (e *ExpectedRollback) String() string

String returns string representation

func (*ExpectedRollback) WillReturnError 

func (e *ExpectedRollback) WillReturnError(err error) *ExpectedRollback

WillReturnError allows to set an error for *sql.Tx.Rollback action

type Rows 

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

Rows is a mocked collection of rows to return for Query result

Example 
db, mock, err := New()
if err != nil {
	fmt.Println("failed to open sqlmock database:", err)
}
defer db.Close()

rows := NewRows([]string{"id", "title"}).
	AddRow(1, "one").
	AddRow(2, "two")

mock.ExpectQuery("SELECT").WillReturnRows(rows)

rs, _ := db.Query("SELECT")
defer rs.Close()

for rs.Next() {
	var id int
	var title string
	rs.Scan(&id, &title)
	fmt.Println("scanned id:", id, "and title:", title)
}

if rs.Err() != nil {
	fmt.Println("got rows error:", rs.Err())
}

Output:

scanned id: 1 and title: one
scanned id: 2 and title: two
Example (CloseError) 
db, mock, err := New()
if err != nil {
	fmt.Println("failed to open sqlmock database:", err)
}
defer db.Close()

rows := NewRows([]string{"id", "title"}).CloseError(fmt.Errorf("close error"))
mock.ExpectQuery("SELECT").WillReturnRows(rows)

rs, _ := db.Query("SELECT")

// Note: that close will return error only before rows EOF
// that is a default sql package behavior. If you run rs.Next()
// it will handle the error internally and return nil bellow
if err := rs.Close(); err != nil {
	fmt.Println("got error:", err)
}

Output:

got error: close error
Example (RowError) 
db, mock, err := New()
if err != nil {
	fmt.Println("failed to open sqlmock database:", err)
}
defer db.Close()

rows := NewRows([]string{"id", "title"}).
	AddRow(0, "one").
	AddRow(1, "two").
	RowError(1, fmt.Errorf("row error"))
mock.ExpectQuery("SELECT").WillReturnRows(rows)

rs, _ := db.Query("SELECT")
defer rs.Close()

for rs.Next() {
	var id int
	var title string
	rs.Scan(&id, &title)
	fmt.Println("scanned id:", id, "and title:", title)
}

if rs.Err() != nil {
	fmt.Println("got rows error:", rs.Err())
}

Output:

scanned id: 0 and title: one
got rows error: row error

func NewRows 

func NewRows(columns []string) *Rows

NewRows allows Rows to be created from a sql driver.Value slice or from the CSV string and to be used as sql driver.Rows

func (*Rows) AddRow 

func (r *Rows) AddRow(values ...driver.Value) *Rows

AddRow composed from database driver.Value slice return the same instance to perform subsequent actions. Note that the number of values must match the number of columns

func (*Rows) CloseError 

func (r *Rows) CloseError(err error) *Rows

CloseError allows to set an error which will be returned by rows.Close function.

The close error will be triggered only in cases when rows.Next() EOF was not yet reached, that is a default sql library behavior

func (*Rows) FromCSVString 

func (r *Rows) FromCSVString(s string) *Rows

FromCSVString build rows from csv string. return the same instance to perform subsequent actions. Note that the number of values must match the number of columns

func (*Rows) RowError 

func (r *Rows) RowError(row int, err error) *Rows

RowError allows to set an error which will be returned when a given row number is read

type Sqlmock 

type Sqlmock interface {

	// ExpectClose queues an expectation for this database
	// action to be triggered. the *ExpectedClose allows
	// to mock database response
	ExpectClose() *ExpectedClose

	// ExpectationsWereMet checks whether all queued expectations
	// were met in order. If any of them was not met - an error is returned.
	ExpectationsWereMet() error

	// ExpectPrepare expects Prepare() to be called with sql query
	// which match sqlRegexStr given regexp.
	// the *ExpectedPrepare allows to mock database response.
	// Note that you may expect Query() or Exec() on the *ExpectedPrepare
	// statement to prevent repeating sqlRegexStr
	ExpectPrepare(sqlRegexStr string) *ExpectedPrepare

	// ExpectQuery expects Query() or QueryRow() to be called with sql query
	// which match sqlRegexStr given regexp.
	// the *ExpectedQuery allows to mock database response.
	ExpectQuery(sqlRegexStr string) *ExpectedQuery

	// ExpectExec expects Exec() to be called with sql query
	// which match sqlRegexStr given regexp.
	// the *ExpectedExec allows to mock database response
	ExpectExec(sqlRegexStr string) *ExpectedExec

	// ExpectBegin expects *sql.DB.Begin to be called.
	// the *ExpectedBegin allows to mock database response
	ExpectBegin() *ExpectedBegin

	// ExpectCommit expects *sql.Tx.Commit to be called.
	// the *ExpectedCommit allows to mock database response
	ExpectCommit() *ExpectedCommit

	// ExpectRollback expects *sql.Tx.Rollback to be called.
	// the *ExpectedRollback allows to mock database response
	ExpectRollback() *ExpectedRollback

	// MatchExpectationsInOrder gives an option whether to match all
	// expectations in the order they were set or not.
	//
	// By default it is set to - true. But if you use goroutines
	// to parallelize your query executation, that option may
	// be handy.
	//
	// This option may be turned on anytime during tests. As soon
	// as it is switched to false, expectations will be matched
	// in any order. Or otherwise if switched to true, any unmatched
	// expectations will be expected in order
	MatchExpectationsInOrder(bool)
}

Sqlmock interface serves to create expectations for any kind of database action in order to mock and test real database behavior.

Example (Goroutines) 
db, mock, err := New()
if err != nil {
	fmt.Println("failed to open sqlmock database:", err)
}
defer db.Close()

// note this line is important for unordered expectation matching
mock.MatchExpectationsInOrder(false)

result := NewResult(1, 1)

mock.ExpectExec("^UPDATE one").WithArgs("one").WillReturnResult(result)
mock.ExpectExec("^UPDATE two").WithArgs("one", "two").WillReturnResult(result)
mock.ExpectExec("^UPDATE three").WithArgs("one", "two", "three").WillReturnResult(result)

var wg sync.WaitGroup
queries := map[string][]interface{}{
	"one":   []interface{}{"one"},
	"two":   []interface{}{"one", "two"},
	"three": []interface{}{"one", "two", "three"},
}

wg.Add(len(queries))
for table, args := range queries {
	go func(tbl string, a []interface{}) {
		if _, err := db.Exec("UPDATE "+tbl, a...); err != nil {
			fmt.Println("error was not expected:", err)
		}
		wg.Done()
	}(table, args)
}

wg.Wait()

if err := mock.ExpectationsWereMet(); err != nil {
	fmt.Println("there were unfulfilled expections:", err)
}

Output:

func New 

func New() (*sql.DB, Sqlmock, error)

New creates sqlmock database connection and a mock to manage expectations. Pings db so that all expectations could be asserted.

Example 
db, mock, err := New()
if err != nil {
	fmt.Println("expected no error, but got:", err)
	return
}
defer db.Close()
// now we can expect operations performed on db
mock.ExpectBegin().WillReturnError(fmt.Errorf("an error will occur on db.Begin() call"))

Output:

func NewWithDSN 

func NewWithDSN(dsn string) (*sql.DB, Sqlmock, error)

NewWithDSN creates sqlmock database connection with a specific DSN and a mock to manage expectations. Pings db so that all expectations could be asserted.

This method is introduced because of sql abstraction libraries, which do not provide a way to initialize with sql.DB instance. For example GORM library.

Note, it will error if attempted to create with an already used dsn

It is not recommended to use this method, unless you really need it and there is no other way around.

Source Files

View all Source files

Directories

Path Synopsis
basic
blog
orders

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.