README
¶
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.
- 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 vendor dependencies.
Install
go get gopkg.in/DATA-DOG/go-sqlmock.v1
If you need an old version, checkout go-sqlmock at gopkg.in:
go get gopkg.in/DATA-DOG/go-sqlmock.v0
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
Changes
- 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
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 ¶
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
Functions ¶
func NewErrorResult ¶
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 ¶
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 which: - matches sql: '^INSERT (.+)' - is without arguments - should return Result having: LastInsertId: 0 RowsAffected: 0
Types ¶
type Argument ¶
Argument interface allows to match any argument in specific way when used with ExpectedQuery and ExpectedExec expectations.
type ExpectedBegin ¶ added in v1.0.0
type ExpectedBegin struct {
// contains filtered or unexported fields
}
ExpectedBegin is used to manage *sql.DB.Begin expectation returned by *Sqlmock.ExpectBegin.
func (*ExpectedBegin) String ¶ added in v1.0.0
func (e *ExpectedBegin) String() string
String returns string representation
func (*ExpectedBegin) WillReturnError ¶ added in v1.0.0
func (e *ExpectedBegin) WillReturnError(err error) *ExpectedBegin
WillReturnError allows to set an error for *sql.DB.Begin action
type ExpectedClose ¶ added in v1.0.0
type ExpectedClose struct {
// contains filtered or unexported fields
}
ExpectedClose is used to manage *sql.DB.Close expectation returned by *Sqlmock.ExpectClose.
func (*ExpectedClose) String ¶ added in v1.0.0
func (e *ExpectedClose) String() string
String returns string representation
func (*ExpectedClose) WillReturnError ¶ added in v1.0.0
func (e *ExpectedClose) WillReturnError(err error) *ExpectedClose
WillReturnError allows to set an error for *sql.DB.Close action
type ExpectedCommit ¶ added in v1.0.0
type ExpectedCommit struct {
// contains filtered or unexported fields
}
ExpectedCommit is used to manage *sql.Tx.Commit expectation returned by *Sqlmock.ExpectCommit.
func (*ExpectedCommit) String ¶ added in v1.0.0
func (e *ExpectedCommit) String() string
String returns string representation
func (*ExpectedCommit) WillReturnError ¶ added in v1.0.0
func (e *ExpectedCommit) WillReturnError(err error) *ExpectedCommit
WillReturnError allows to set an error for *sql.Tx.Close action
type ExpectedExec ¶ added in v1.0.0
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 ¶ added in v1.0.0
func (e *ExpectedExec) String() string
String returns string representation
func (*ExpectedExec) WillReturnError ¶ added in v1.0.0
func (e *ExpectedExec) WillReturnError(err error) *ExpectedExec
WillReturnError allows to set an error for expected database exec action
func (*ExpectedExec) WillReturnResult ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
func (e *ExpectedPrepare) String() string
String returns string representation
func (*ExpectedPrepare) WillReturnCloseError ¶ added in v1.0.0
func (e *ExpectedPrepare) WillReturnCloseError(err error) *ExpectedPrepare
WillReturnCloseError allows to set an error for this prapared statement Close action
func (*ExpectedPrepare) WillReturnError ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
func (e *ExpectedQuery) String() string
String returns string representation
func (*ExpectedQuery) WillReturnError ¶ added in v1.0.0
func (e *ExpectedQuery) WillReturnError(err error) *ExpectedQuery
WillReturnError allows to set an error for expected database query
func (*ExpectedQuery) WillReturnRows ¶ added in v1.0.0
func (e *ExpectedQuery) WillReturnRows(rows driver.Rows) *ExpectedQuery
WillReturnRows specifies the set of resulting rows that will be returned by the triggered query
func (*ExpectedQuery) WithArgs ¶ added in v1.0.0
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 ¶ added in v1.0.0
type ExpectedRollback struct {
// contains filtered or unexported fields
}
ExpectedRollback is used to manage *sql.Tx.Rollback expectation returned by *Sqlmock.ExpectRollback.
func (*ExpectedRollback) String ¶ added in v1.0.0
func (e *ExpectedRollback) String() string
String returns string representation
func (*ExpectedRollback) WillReturnError ¶ added in v1.0.0
func (e *ExpectedRollback) WillReturnError(err error) *ExpectedRollback
WillReturnError allows to set an error for *sql.Tx.Rollback action
type Rows ¶
type Rows interface {
// composed interface, supports sql driver.Rows
driver.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
AddRow(columns ...driver.Value) 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
FromCSVString(s string) Rows
// RowError allows to set an error
// which will be returned when a given
// row number is read
RowError(row int, 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
CloseError(err error) Rows
}
Rows interface allows to construct rows which also satisfies database/sql/driver.Rows interface
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
type Sqlmock ¶ added in v1.0.0
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.
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 ¶
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 ¶ added in v1.1.0
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
Directories