sqlmock

package module
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2023 License: BSD-3-Clause Imports: 20 Imported by: 0

README

SQL driver mock for Golang (with jmoiron/sqlx support)

Forked from DATA-DOG/go-sqlmock

Added functionality
  • Newx() and NewxWithDNS() which returns *sqlx.DB object instead of *sql.DB

Install

go get -u github.com/zhashkevych/go-sqlxmock@master

Usage Example

Repository Implementation:

type UserRepository interface {
	Insert(user domain.User) (int, error)
	GetById(id int) (domain.User, error)
	Get(username, password string) (domain.User, error)
}


type UserRepository struct {
	db *sqlx.DB
}

func NewUserRepository(db *sqlx.DB) *UserRepository {
	return &UserRepository{db: db}
}

func (r *UserRepository) Insert(user domain.User) (int, error) {
	var id int
	row := r.db.QueryRow("INSERT INTO users (first_name, last_name, username, password) VALUES ($1, $2, $3, $4) RETURNING id",
		user.FirstName, user.LastName, user.Username, user.Password)
	if err := row.Scan(&id); err != nil {
		return 0, err
	}

	return id, nil
}

Unit Tests:

import (
	sqlxmock "github.com/zhashkevych/go-sqlxmock"
	"testing"
)

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

	s := NewUserRepository(db)

	tests := []struct {
		name    string
		s       repository.UserRepository
		user    domain.User
		mock    func()
		want    int
		wantErr bool
	}{
		{
			//When everything works as expected
			name: "OK",
			s:    s,
			user: domain.User{
				FirstName: "first_name",
				LastName:  "last_name",
				Username:  "username",
				Password:  "password",
			},
			mock: func() {
				rows := sqlxmock.NewRows([]string{"id"}).AddRow(1)
				mock.ExpectQuery("INSERT INTO users").WithArgs("first_name", "last_name", "username", "password").WillReturnRows(rows)
			},
			want: 1,
		},
		{
			name:  "Empty Fields",
			s:     s,
			user: domain.User{
				FirstName: "",
				LastName:  "",
				Username:  "username",
				Password:  "password",
			},
			mock: func() {
				rows := sqlxmock.NewRows([]string{"id"}) 
				mock.ExpectQuery("INSERT INTO users").WithArgs("first_name", "last_name", "username", "password").WillReturnRows(rows)
			},
			wantErr: true,
		},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			tt.mock()
			got, err := tt.s.Insert(tt.user)
			if (err != nil) != tt.wantErr {
				t.Errorf("Get() error new = %v, wantErr %v", err, tt.wantErr)
				return
			}
			if err == nil && got != tt.want {
				t.Errorf("Get() = %v, want %v", got, tt.want)
			}
		})
	}
}

Develop

You can develop locally using the following commands:

$ go work init

$ go work edit -replace=github.com/zhashkevych/go-sqlxmock=/home/panhong/go/src/github.com/panhongrainbow/go-sqlxmock

Config

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

View Source 
const (
	Condition_The_Same       uint8 = iota // Condition_The_Same indicates that the state is the same; all initialized variables have not been modified.
	Condition_Diff_In_Length              // Condition_Diff_In_Length indicates that two slices have different lengths, and comparison cannot proceed due to length mismatch, resulting in direct interruption.
	Condition_Diff_In_Value               // Condition_Diff_In_Value indicates that two slices have different values.
)
View Source 
const (
	Case_Upper     uint8 = iota + 1 // Represents converting text to uppercase.
	Case_Lower                      // Represents converting text to lowercase.
	Case_Snake                      // Represents converting text to snake_case.
	Case_No_Change                  // Represents no change in text case. (Keep Camel)
)

Defines text case conversion constants.

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 ConvertStringFormats 

func ConvertStringFormats(input string, convertCase uint8) (formatted string)

ConvertStringFormats converts the input string to different case formats. It takes the input string and a conversion case flag. Supported conversion cases: Case_Upper, Case_Lower, Case_Snake.

func FetchResultsFromRows 

func FetchResultsFromRows(rows *sql.Rows) (results [][]string, err error)

FetchResultsFromRows fetches results from a SQL rows object and converts them into a 2D string slice.

func FetchResultsFromRowsComparator 

func FetchResultsFromRowsComparator(rows *sql.Rows) (results [][]string, err error)

FetchResultsFromRowsComparator fetches results from a SQL rows object and converts them into a 2D string slice.

func GetGenuineLocation 

func GetGenuineLocation() (path string)

GetGenuineLocation returns genuineConfigLocation.

func GetMockLocation 

func GetMockLocation() (path string)

GetMockLocation returns mockConfigLocation.

func LoadMockConfig 

func LoadMockConfig(sqlMock Sqlmock, subPath, jsonFile string) (error error)

LoadMockConfig is used to load the configuration values for Mock. It contains JSON data and requires UseNumber to preserve numbers as strings. If there are specific performance requirements, you may need to write your own parser. For now, we'll use the simplest method using json.NewDecoder to handle it.

func MakeCreateTableSQLStr 

func MakeCreateTableSQLStr(tableName string, model interface{}, convertCase uint8) (sqlStr string, err error)

MakeCreateTableSQLStr generates a SQL string for creating a table with the given table name and model. Database column names prioritize tags first, followed by other settings. (栏位优先考虑标签)

func MakeInsertTableSQLStr 

func MakeInsertTableSQLStr(tableName string, model interface{}, convertCase uint8) (sqlStr string)

MakeInsertTableSQLStr generates SQL INSERT statements for a given table name and model.

func MakeSelectTableSQLStr 

func MakeSelectTableSQLStr(tableName string, model interface{}, convertCase uint8) (sqlStr string)

MakeSelectTableSQLStr generates SQL INSERT statements for a given table name and model.

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

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 SetGenuineLocationByManual 

func SetGenuineLocationByManual(path string)

SetGenuineLocationByManual sets genuineConfigLocation by manual.

func SetMockLocationByManual 

func SetMockLocationByManual(path string)

SetMockLocationByManual sets mockConfigLocation by manual.

func SetMockOrGenuineLocationByTriggerMain 

func SetMockOrGenuineLocationByTriggerMain(isGenuine bool)

SetMockOrGenuineLocationByTriggerMain sets mockConfigLocation and gets the directory path of the caller's location. When passed as false, the file path design is based on the mock simulated database (mockConfigLocation). When passed as true, the file path design is based on the genuine real database (genuineConfigLocation).

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 BasicOptions 

type BasicOptions struct {
	UseDB bool // UseDB indicates whether to use a database.
}

BasicOptions holds basic configuration options.

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 ConfigRows 

type ConfigRows struct {
	Columns []string         `json:"columns"`
	Rows    [][]driver.Value `json:"rows"`
}

ConfigRows can be used to set the corresponding database schema.

type ConfigSet 

type ConfigSet struct {
	QueryString string         `json:"qureyString"`
	QueryArgs   []driver.Value `json:"queryArgs"`
	ReturnRows  []ConfigRows   `json:"returnRows"`
}

ConfigSet can be used to set the basic response

type DBOptions 

type DBOptions struct {
	ConfigSubFolder string // Setting up sub-paths (设定子路径) ❗️
	ConfigFile      []string
	DS              DataSource `json:"ds"` // DataSource configuration for the database.
	OP              Operate    `json:"op"` // Operate options for database operations.
}

DBOptions holds database configuration options.

func LoadGenuineConfig 

func LoadGenuineConfig(subPath, jsonFile string) (dbOpts DBOptions, err error)

type DataSource 

type DataSource struct {
	Driver   string `json:"driver"`   // Driver specifies the database driver to be used (e.g., mysql, postgres).
	User     string `json:"user"`     // User represents the database username.
	Password string `json:"password"` // Password represents the password associated with the database user.
	Protocal string `json:"protocal"` // Protocal specifies the communication protocol (e.g., tcp).
	IP       string `json:"ip"`       // IP is the IP address of the database server.
	Port     string `json:"port"`     // Port is the port number for the database connection.
	DbName   string `json:"db_name"`  // DbName is the name of the target database.
}

DataSource holds information for establishing a database connection.

type DiffPlace 

type DiffPlace struct {
	RowIndex    int    // Index of the differing row
	ColumnIndex int    // Index of the differing column
	BeforeValue string // Value before modification
	AfterValue  string // Value after modification
}

DiffPlace represents the differences between two slices.

func CompareResults 

func CompareResults(results1, results2 [][]string) (same bool, condition uint8, differences []DiffPlace)

CompareResults compares two sets of string slices and identifies any differences.

type EraseTableAction 

type EraseTableAction string

定义一个 Erace Action 避免混用 

const (
	EraseDropTableAction     EraseTableAction = "DROP TABLE IF EXISTS "
	EraseTruncateTableAction EraseTableAction = "TRUNCATE TABLE "
)

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

type MockOptions struct {
	ConfigSubFolder string // Setting up sub-paths (设定子路径) ❗️
	ConfigFile      []string
}

MockOptions holds options related to mocking.

type Mocker 

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

Mocker represents a struct for managing database or mocking.

func NewMocker 

func NewMocker(mOpts MockerOptions) (mocker *Mocker, err error)

NewMocker creates a new Mocker instance with the provided options.

func (*Mocker) Close 

func (m *Mocker) Close()

Close closes the database connection.

func (*Mocker) DSN 

func (m *Mocker) DSN() string

DSN returns the Data Source Name (DSN) used for the database connection.

func (*Mocker) EraseTable 

func (m *Mocker) EraseTable(action EraseTableAction, db string, tables ...string) (err error)

EraseTable drops specified tables in the given database. (Data in the database will be deleted or cleared here, please be cautious ☢️.)

func (*Mocker) Exec 

func (m *Mocker) Exec(query string, args ...any) (sql.Result, error)

Exec executes SQL statements.

func (*Mocker) Query 

func (m *Mocker) Query(query string, args ...any) (*sql.Rows, error)

Query executes a SQL query and returns the resulting rows.

type MockerOptions 

type MockerOptions struct {
	Basic BasicOptions // Struct field to hold Basic configuration options.
	Mock  MockOptions  // Struct field to hold Mocking configuration options.
	DB    DBOptions    // Struct field to hold Database (DB) configuration options.
}

MockerOptions is the collection of configuration.

func NewMockerOptions 

func NewMockerOptions(funcs ...SetMockOptsFunc) MockerOptions

NewMockerOptions is a function that creates a new instance of MockerOptions with the provided options.

type Operate 

type Operate struct {
	DropTable     bool `json:"drop_table"`     // DropTable indicates whether to drop the whole table.
	TruncateTable bool `json:"truncate_table"` // TruncateTable indicates whether to truncate database tables.
}

Operate holds options for performing specific database operations.

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 
// configure to use case sensitive SQL query matcher
// instead of default regular expression matcher
db, mock, err := New(QueryMatcherOption(QueryMatcherEqual))
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 * FROM users").WillReturnRows(rows)

rs, err := db.Query("SELECT * FROM users")
if err != nil {
	fmt.Println("failed to match expected query")
	return
}
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

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 
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 (CustomDriverValue) 
db, mock, err := New()
if err != nil {
	fmt.Println("failed to open sqlmock database:", err)
}
defer db.Close()

rows := NewRows([]string{"id", "null_int"}).
	AddRow(1, 7).
	AddRow(5, sql.NullInt64{Int64: 5, Valid: true}).
	AddRow(2, sql.NullInt64{})

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

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

for rs.Next() {
	var id int
	var num sql.NullInt64
	rs.Scan(&id, &num)
	fmt.Println("scanned id:", id, "and null int64:", num)
}

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

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) 
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, "john")
mock.ExpectQuery("SELECT").WillReturnRows(rows).RowsWillBeClosed()

db.Query("SELECT")

if err := mock.ExpectationsWereMet(); err != nil {
	fmt.Println("got error:", err)
}

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) 
db, mock, err := New()
if err != nil {
	fmt.Println("failed to open sqlmock database:", err)
}
defer db.Close()

rows := NewRows([]string{"id", "binary"}).
	AddRow(1, []byte(`one binary value with some text!`)).
	AddRow(2, []byte(`two binary value with even more text than the first one`))

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

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

type scanned struct {
	id  int
	raw sql.RawBytes
}
fmt.Println("initial read...")
var ss []scanned
for rs.Next() {
	var s scanned
	rs.Scan(&s.id, &s.raw)
	ss = append(ss, s)
	fmt.Println("scanned id:", s.id, "and raw:", string(s.raw))
}

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

fmt.Println("after reading all...")
for _, s := range ss {
	fmt.Println("scanned id:", s.id, "and raw:", string(s.raw))
}

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) 
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. 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 SetMockOptsFunc 

type SetMockOptsFunc func(*MockerOptions)

SetMockOptsFunc is a type of function that sets options for MockOptions.

func WithBasicOptions 

func WithBasicOptions(basicOpts BasicOptions) SetMockOptsFunc

WithBasicOptions is a function that creates a SetOptsFunc to set BasicOptions.

func WithDBOptions 

func WithDBOptions(dbOpts DBOptions) SetMockOptsFunc

WithDBOptions is a function that creates a SetOptsFunc to set BasicOptions.

func WithMockOptions 

func WithMockOptions(mockOpts MockOptions) SetMockOptsFunc

WithMockOptions is a function that creates a SetOptsFunc to set BasicOptions.

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) 
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":   {"one"},
	"two":   {"one", "two"},
	"three": {"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 expectations:", err)
}

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

func Newx 

func Newx(options ...func(*sqlmock) error) (*sqlx.DB, Sqlmock, error)

Newx creates sqlmock database connection of *sqlx.DB type 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.

func NewxWithDSN 

func NewxWithDSN(dsn string, options ...func(*sqlmock) error) (*sqlx.DB, Sqlmock, error)

NewxWithDSN creates sqlmock database connection of *sqlx.DB type 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.

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.