README

Build Status GoDoc Go Report Card 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.

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 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, assuming you use the go-mysql-driver
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
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:

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

Expand ▾ Collapse ▴

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
    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")

        ErrCancelled defines an error value, which can be expected in case of such cancellation error.

        Functions

        func MonitorPingsOption

        func MonitorPingsOption(monitorPings bool) func(*sqlmock) error

          MonitorPingsOption determines whether calls to Ping on the driver should be observed and mocked.

          If true is passed, we will check these calls were expected. Expectations can be registered using the ExpectPing() method on the mock.

          If false is passed or this option is omitted, calls to Ping will not be considered when determining expectations and calls to ExpectPing will have no effect.

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

              func QueryMatcherOption

              func QueryMatcherOption(queryMatcher QueryMatcher) func(*sqlmock) error

                QueryMatcherOption allows to customize SQL query matcher and match SQL query strings in more sophisticated ways. The default QueryMatcher is QueryMatcherRegexp.

                func ValueConverterOption

                func ValueConverterOption(converter driver.ValueConverter) func(*sqlmock) error

                  ValueConverterOption allows to create a sqlmock connection with a custom ValueConverter to support drivers with special data types.

                  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 Column

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

                        Column is a mocked column Metadata for rows.ColumnTypes()

                        func NewColumn

                        func NewColumn(name string) *Column

                          NewColumn returns a Column with specified name

                          func (*Column) DbType

                          func (c *Column) DbType() string

                          func (*Column) IsNullable

                          func (c *Column) IsNullable() (bool, bool)

                          func (*Column) Length

                          func (c *Column) Length() (int64, bool)

                          func (*Column) Name

                          func (c *Column) Name() string

                          func (*Column) Nullable

                          func (c *Column) Nullable(nullable bool) *Column

                            Nullable returns the column with nullable metadata set

                            func (*Column) OfType

                            func (c *Column) OfType(dbType string, sampleValue interface{}) *Column

                              OfType returns the column with type metadata set

                              func (*Column) PrecisionScale

                              func (c *Column) PrecisionScale() (int64, int64, bool)

                              func (*Column) ScanType

                              func (c *Column) ScanType() reflect.Type

                              func (*Column) WithLength

                              func (c *Column) WithLength(length int64) *Column

                                WithLength returns the column with length metadata set.

                                func (*Column) WithPrecisionAndScale

                                func (c *Column) WithPrecisionAndScale(precision, scale int64) *Column

                                  WithPrecisionAndScale returns the column with precision and scale metadata set.

                                  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
                                                        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 ExpectedPing

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

                                                                    ExpectedPing is used to manage *sql.DB.Ping expectations. Returned by *Sqlmock.ExpectPing.

                                                                    func (*ExpectedPing) String

                                                                    func (e *ExpectedPing) String() string

                                                                      String returns string representation

                                                                      func (*ExpectedPing) WillDelayFor

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

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

                                                                        func (*ExpectedPing) WillReturnError

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

                                                                          WillReturnError allows to set an error for expected database ping

                                                                          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) RowsWillBeClosed

                                                                                            func (e *ExpectedQuery) RowsWillBeClosed() *ExpectedQuery

                                                                                              RowsWillBeClosed expects this query rows to be closed.

                                                                                              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 QueryMatcher

                                                                                                              type QueryMatcher interface {
                                                                                                              
                                                                                                              	// Match expected SQL query string without whitespace to
                                                                                                              	// actual SQL.
                                                                                                              	Match(expectedSQL, actualSQL string) error
                                                                                                              }

                                                                                                                QueryMatcher is an SQL query string matcher interface, which can be used to customize validation of SQL query strings. As an example, external library could be used to build and validate SQL ast, columns selected.

                                                                                                                sqlmock can be customized to implement a different QueryMatcher configured through an option when sqlmock.New or sqlmock.NewWithDSN is called, default QueryMatcher is QueryMatcherRegexp.

                                                                                                                Example
                                                                                                                Output:
                                                                                                                
                                                                                                                scanned id: 1 and title: one
                                                                                                                scanned id: 2 and title: two
                                                                                                                
                                                                                                                var QueryMatcherEqual QueryMatcher = QueryMatcherFunc(func(expectedSQL, actualSQL string) error {
                                                                                                                	expect := stripQuery(expectedSQL)
                                                                                                                	actual := stripQuery(actualSQL)
                                                                                                                	if actual != expect {
                                                                                                                		return fmt.Errorf(`actual sql: "%s" does not equal to expected "%s"`, actual, expect)
                                                                                                                	}
                                                                                                                	return nil
                                                                                                                })

                                                                                                                  QueryMatcherEqual is the SQL query matcher which simply tries a case sensitive match of expected and actual SQL strings without whitespace.

                                                                                                                  var QueryMatcherRegexp QueryMatcher = QueryMatcherFunc(func(expectedSQL, actualSQL string) error {
                                                                                                                  	expect := stripQuery(expectedSQL)
                                                                                                                  	actual := stripQuery(actualSQL)
                                                                                                                  	re, err := regexp.Compile(expect)
                                                                                                                  	if err != nil {
                                                                                                                  		return err
                                                                                                                  	}
                                                                                                                  	if !re.MatchString(actual) {
                                                                                                                  		return fmt.Errorf(`could not match actual sql: "%s" with expected regexp "%s"`, actual, re.String())
                                                                                                                  	}
                                                                                                                  	return nil
                                                                                                                  })

                                                                                                                    QueryMatcherRegexp is the default SQL query matcher used by sqlmock. It parses expectedSQL to a regular expression and attempts to match actualSQL.

                                                                                                                    type QueryMatcherFunc

                                                                                                                    type QueryMatcherFunc func(expectedSQL, actualSQL string) error

                                                                                                                      QueryMatcherFunc type is an adapter to allow the use of ordinary functions as QueryMatcher. If f is a function with the appropriate signature, QueryMatcherFunc(f) is a QueryMatcher that calls f.

                                                                                                                      func (QueryMatcherFunc) Match

                                                                                                                      func (f QueryMatcherFunc) Match(expectedSQL, actualSQL string) error

                                                                                                                        Match implements the QueryMatcher

                                                                                                                        type Rows

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

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

                                                                                                                          Example
                                                                                                                          Output:
                                                                                                                          
                                                                                                                          scanned id: 1 and title: one
                                                                                                                          scanned id: 2 and title: two
                                                                                                                          
                                                                                                                          Example (CloseError)
                                                                                                                          Output:
                                                                                                                          
                                                                                                                          got error: close error
                                                                                                                          
                                                                                                                          Example (CustomDriverValue)
                                                                                                                          Output:
                                                                                                                          
                                                                                                                          scanned id: 1 and null int64: {7 true}
                                                                                                                          scanned id: 5 and null int64: {5 true}
                                                                                                                          scanned id: 2 and null int64: {0 false}
                                                                                                                          
                                                                                                                          Example (ExpectToBeClosed)
                                                                                                                          Output:
                                                                                                                          
                                                                                                                          got error: expected query rows to be closed, but it was not: ExpectedQuery => expecting Query, QueryContext or QueryRow which:
                                                                                                                            - matches sql: 'SELECT'
                                                                                                                            - is without arguments
                                                                                                                            - should return rows:
                                                                                                                              row 0 - [1 john]
                                                                                                                          
                                                                                                                          Example (RawBytes)
                                                                                                                          Output:
                                                                                                                          
                                                                                                                          initial read...
                                                                                                                          scanned id: 1 and raw: one binary value with some text!
                                                                                                                          scanned id: 2 and raw: two binary value with even more text than the first one
                                                                                                                          after reading all...
                                                                                                                          scanned id: 1 and raw: ☠☠☠ MEMORY OVERWRITTEN ☠
                                                                                                                          scanned id: 2 and raw: ☠☠☠ MEMORY OVERWRITTEN ☠☠☠ ☠☠☠ MEMORY
                                                                                                                          
                                                                                                                          Example (RowError)
                                                                                                                          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. Use Sqlmock.NewRows instead if using a custom converter

                                                                                                                            func NewRowsWithColumnDefinition

                                                                                                                            func NewRowsWithColumnDefinition(columns ...*Column) *Rows

                                                                                                                              NewRowsWithColumnDefinition return rows with columns metadata

                                                                                                                              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 {
                                                                                                                                      	// Embed common methods
                                                                                                                                      	SqlmockCommon
                                                                                                                                      
                                                                                                                                      	// NewRowsWithColumnDefinition allows Rows to be created from a
                                                                                                                                      	// sql driver.Value slice with a definition of sql metadata
                                                                                                                                      	NewRowsWithColumnDefinition(columns ...*Column) *Rows
                                                                                                                                      
                                                                                                                                      	// New Column allows to create a Column
                                                                                                                                      	NewColumn(name string) *Column
                                                                                                                                      }

                                                                                                                                        Sqlmock interface for Go 1.8+

                                                                                                                                        Example (Goroutines)
                                                                                                                                        Output:
                                                                                                                                        
                                                                                                                                        

                                                                                                                                        func New

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

                                                                                                                                          New creates sqlmock database connection and a mock to manage expectations. Accepts options, like ValueConverterOption, to use a ValueConverter from a specific driver. Pings db so that all expectations could be asserted.

                                                                                                                                          Example
                                                                                                                                          Output:
                                                                                                                                          
                                                                                                                                          

                                                                                                                                          func NewWithDSN

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

                                                                                                                                            NewWithDSN creates sqlmock database connection with a specific DSN and a mock to manage expectations. Accepts options, like ValueConverterOption, to use a ValueConverter from a specific driver. 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.

                                                                                                                                            type SqlmockCommon

                                                                                                                                            type SqlmockCommon 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 expectedSQL query.
                                                                                                                                            	// the *ExpectedPrepare allows to mock database response.
                                                                                                                                            	// Note that you may expect Query() or Exec() on the *ExpectedPrepare
                                                                                                                                            	// statement to prevent repeating expectedSQL
                                                                                                                                            	ExpectPrepare(expectedSQL string) *ExpectedPrepare
                                                                                                                                            
                                                                                                                                            	// ExpectQuery expects Query() or QueryRow() to be called with expectedSQL query.
                                                                                                                                            	// the *ExpectedQuery allows to mock database response.
                                                                                                                                            	ExpectQuery(expectedSQL string) *ExpectedQuery
                                                                                                                                            
                                                                                                                                            	// ExpectExec expects Exec() to be called with expectedSQL query.
                                                                                                                                            	// the *ExpectedExec allows to mock database response
                                                                                                                                            	ExpectExec(expectedSQL 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
                                                                                                                                            
                                                                                                                                            	// ExpectPing expected *sql.DB.Ping to be called.
                                                                                                                                            	// the *ExpectedPing allows to mock database response
                                                                                                                                            	//
                                                                                                                                            	// Ping support only exists in the SQL library in Go 1.8 and above.
                                                                                                                                            	// ExpectPing in Go <=1.7 will return an ExpectedPing but not register
                                                                                                                                            	// any expectations.
                                                                                                                                            	//
                                                                                                                                            	// You must enable pings using MonitorPingsOption for this to register
                                                                                                                                            	// any expectations.
                                                                                                                                            	ExpectPing() *ExpectedPing
                                                                                                                                            
                                                                                                                                            	// 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)
                                                                                                                                            
                                                                                                                                            	// 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.
                                                                                                                                            	NewRows(columns []string) *Rows
                                                                                                                                            }

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

                                                                                                                                              Directories

                                                                                                                                              Path Synopsis