README
¶
pgx driver mock for Golang
pgxmock is a mock library implementing pgx - PostgreSQL Driver and Toolkit.
It's based on the well-known sqlmock library for sql/driver
.
pgxmock has one and only purpose - to simulate pgx behavior in tests, without needing a real database connection. It helps to maintain correct TDD workflow.
- written based on go1.15 version, however, should be compatible with go1.11 and above;
- does not require any modifications to your source code;
- has strict by default expectation order matching;
- has no third party dependencies except pgx packages.
Install
go get github.com/pashagolub/pgxmock/v2
Documentation and Examples
Visit godoc for general examples and public api reference.
See implementation examples:
Something you may want to test
package main
import (
"context"
pgx "github.com/jackc/pgx/v5"
)
type PgxIface interface {
Begin(context.Context) (pgx.Tx, error)
Close(context.Context) error
}
func recordStats(db PgxIface, userID, productID int) (err error) {
if tx, err := db.Begin(context.Background()); err != nil {
return
}
defer func() {
switch err {
case nil:
err = tx.Commit(context.Background())
default:
_ = tx.Rollback(context.Background())
}
}()
sql := "UPDATE products SET views = views + 1"
if _, err = tx.Exec(context.Background(), sql); err != nil {
return
}
sql = "INSERT INTO product_viewers (user_id, product_id) VALUES ($1, $2)"
if _, err = tx.Exec(context.Background(), sql, userID, productID); err != nil {
return
}
return
}
func main() {
// @NOTE: the real connection is not required for tests
db, err := pgx.Connect(context.Background(), "postgres://rolname@hostname/dbname")
if err != nil {
panic(err)
}
defer db.Close(context.Background())
if err = recordStats(db, 1 /*some user id*/, 5 /*some product id*/); err != nil {
panic(err)
}
}
Tests with pgxmock
package main
import (
"context"
"fmt"
"testing"
"github.com/pashagolub/pgxmock/v2"
)
// a successful case
func TestShouldUpdateStats(t *testing.T) {
mock, err := pgxmock.NewPool()
if err != nil {
t.Fatal(err)
}
defer mock.Close()
mock.ExpectBegin()
mock.ExpectExec("UPDATE products").
WillReturnResult(pgxmock.NewResult("UPDATE", 1))
mock.ExpectExec("INSERT INTO product_viewers").
WithArgs(2, 3).
WillReturnResult(pgxmock.NewResult("INSERT", 1))
mock.ExpectCommit()
// now we execute our method
if err = recordStats(mock, 2, 3); err != nil {
t.Errorf("error was not expected while updating: %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) {
mock, err := pgxmock.NewPool()
if err != nil {
t.Fatal(err)
}
defer mock.Close()
mock.ExpectBegin()
mock.ExpectExec("UPDATE products").
WillReturnResult(pgxmock.NewResult("UPDATE", 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(mock, 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
pgxmock.New
or pgxmock.NewWithDSN
.
This now allows to include some library, which would allow for example to parse and validate SQL AST. And create a custom QueryMatcher in order to validate SQL in sophisticated ways.
By default, pgxmock is preserving backward compatibility and default query matcher is pgxmock.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:
mock, err := pgxmock.New(context.Background(), sqlmock.QueryMatcherOption(pgxmock.QueryMatcherEqual))
The query matcher can be fully customized based on user needs. pgxmock will not provide a standard sql parsing matchers.
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
pgxmock 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 interface{}) 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
Contributions
Feel free to open a pull request. Note, if you wish to contribute an extension to public (exported methods or types) - please open an issue before, to discuss whether these changes can be accepted. All backward incompatible changes are and will be treated cautiously
License
Documentation
¶
Overview ¶
package pgxmock is a mock library implementing pgx connector. Which has one and only purpose - to simulate pgx driver behavior in tests, without needing a real database connection. It helps to maintain correct **TDD** workflow.
It does not require (almost) 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 pgx driver method behavior.
Index ¶
- Variables
- func MonitorPingsOption(monitorPings bool) func(*pgxmock) error
- func NewErrorResult(err error) pgconn.CommandTag
- func NewResult(op string, rowsAffected int64) pgconn.CommandTag
- func QueryMatcherOption(queryMatcher QueryMatcher) func(*pgxmock) error
- type Argument
- type ExpectedBegin
- type ExpectedClose
- type ExpectedCommit
- type ExpectedCopyFrom
- type ExpectedExec
- func (e *ExpectedExec) String() string
- func (e *ExpectedExec) WillDelayFor(duration time.Duration) *ExpectedExec
- func (e *ExpectedExec) WillReturnError(err error) *ExpectedExec
- func (e *ExpectedExec) WillReturnResult(result pgconn.CommandTag) *ExpectedExec
- func (e *ExpectedExec) WithArgs(args ...interface{}) *ExpectedExec
- type ExpectedPing
- type ExpectedPrepare
- func (e *ExpectedPrepare) ExpectExec() *ExpectedExec
- func (e *ExpectedPrepare) ExpectQuery() *ExpectedQuery
- func (e *ExpectedPrepare) String() string
- func (e *ExpectedPrepare) WillBeClosed() *ExpectedPrepare
- func (e *ExpectedPrepare) WillDelayFor(duration time.Duration) *ExpectedPrepare
- func (e *ExpectedPrepare) WillReturnCloseError(err error) *ExpectedPrepare
- func (e *ExpectedPrepare) WillReturnError(err error) *ExpectedPrepare
- type ExpectedQuery
- func (e *ExpectedQuery) RowsWillBeClosed() *ExpectedQuery
- func (e *ExpectedQuery) String() string
- func (e *ExpectedQuery) WillDelayFor(duration time.Duration) *ExpectedQuery
- func (e *ExpectedQuery) WillReturnError(err error) *ExpectedQuery
- func (e *ExpectedQuery) WillReturnRows(rows ...*Rows) *ExpectedQuery
- func (e *ExpectedQuery) WithArgs(args ...interface{}) *ExpectedQuery
- type ExpectedRollback
- type PgxConnIface
- type PgxPoolIface
- type QueryMatcher
- type QueryMatcherFunc
- type Rows
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var CSVColumnParser = func(s string) interface{} { switch { case strings.ToLower(s) == "null": return nil } return s }
CSVColumnParser is a function which converts trimmed csv column string to a []byte representation. Currently transforms NULL to nil
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 ¶
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) pgconn.CommandTag
NewErrorResult creates a new sql driver Result which returns an error given for both interface methods
func NewResult ¶
func NewResult(op string, rowsAffected int64) pgconn.CommandTag
NewResult creates a new sql driver Result for Exec based query mocks.
func QueryMatcherOption ¶
func QueryMatcherOption(queryMatcher QueryMatcher) func(*pgxmock) error
QueryMatcherOption allows to customize SQL query matcher and match SQL query strings in more sophisticated ways. The default QueryMatcher is QueryMatcherRegexp.
Types ¶
type Argument ¶
type Argument interface {
Match(interface{}) bool
}
Argument interface allows to match any argument in specific way when used with ExpectedQuery and ExpectedExec expectations.
type ExpectedBegin ¶
type ExpectedBegin struct {
// contains filtered or unexported fields
}
ExpectedBegin is used to manage *pgx.Begin expectation returned by pgxmock.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 pgx.Begin action
type ExpectedClose ¶
type ExpectedClose struct {
// contains filtered or unexported fields
}
ExpectedClose is used to manage pgx.Close expectation returned by pgxmock.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 pgx.Close action
type ExpectedCommit ¶
type ExpectedCommit struct {
// contains filtered or unexported fields
}
ExpectedCommit is used to manage pgx.Tx.Commit expectation returned by pgxmock.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 pgx.Tx.Close action
type ExpectedCopyFrom ¶
type ExpectedCopyFrom struct {
// contains filtered or unexported fields
}
ExpectedCopyFrom is used to manage *pgx.Conn.CopyFrom expectations. Returned by *Pgxmock.ExpectCopyFrom.
func (*ExpectedCopyFrom) String ¶
func (e *ExpectedCopyFrom) String() string
String returns string representation
func (*ExpectedCopyFrom) WillDelayFor ¶
func (e *ExpectedCopyFrom) WillDelayFor(duration time.Duration) *ExpectedCopyFrom
WillDelayFor allows to specify duration for which it will delay result. May be used together with Context
func (*ExpectedCopyFrom) WillReturnError ¶
func (e *ExpectedCopyFrom) WillReturnError(err error) *ExpectedCopyFrom
WillReturnError allows to set an error for expected database exec action
func (*ExpectedCopyFrom) WillReturnResult ¶
func (e *ExpectedCopyFrom) WillReturnResult(result int64) *ExpectedCopyFrom
WillReturnResult arranges for an expected Exec() to return a particular result, there is pgxmock.NewResult(lastInsertID int64, affectedRows int64) method to build a corresponding result. Or if actions needs to be tested against errors pgxmock.NewErrorResult(err error) to return a given error.
type ExpectedExec ¶
type ExpectedExec struct {
// contains filtered or unexported fields
}
ExpectedExec is used to manage pgx.Exec, pgx.Tx.Exec or pgx.Stmt.Exec expectations. Returned by pgxmock.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 pgconn.CommandTag) *ExpectedExec
WillReturnResult arranges for an expected Exec() to return a particular result, there is pgxmock.NewResult(lastInsertID int64, affectedRows int64) method to build a corresponding result. Or if actions needs to be tested against errors pgxmock.NewErrorResult(err error) to return a given error.
func (*ExpectedExec) WithArgs ¶
func (e *ExpectedExec) WithArgs(args ...interface{}) *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 pgxmock.Argument interface can be used to match an argument.
type ExpectedPing ¶
type ExpectedPing struct {
// contains filtered or unexported fields
}
ExpectedPing is used to manage pgx.Ping expectations. Returned by pgxmock.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 pgx.Prepare or pgx.Tx.Prepare expectations. Returned by pgxmock.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 pgx.Prepare or pgx.Tx.Prepare action.
type ExpectedQuery ¶
type ExpectedQuery struct {
// contains filtered or unexported fields
}
ExpectedQuery is used to manage *pgx.Conn.Query, *pgx.Conn.QueryRow, *pgx.Tx.Query, *pgx.Tx.QueryRow, *pgx.Stmt.Query or *pgx.Stmt.QueryRow expectations. Returned by pgxmock.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 ...interface{}) *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 pgxmock.Argument interface can be used to match an argument.
type ExpectedRollback ¶
type ExpectedRollback struct {
// contains filtered or unexported fields
}
ExpectedRollback is used to manage pgx.Tx.Rollback expectation returned by pgxmock.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 pgx.Tx.Rollback action
type PgxConnIface ¶
type PgxConnIface interface { pgx.Tx Close(ctx context.Context) error // contains filtered or unexported methods }
func NewConn ¶
func NewConn(options ...func(*pgxmock) error) (PgxConnIface, error)
NewConn creates PgxConnIface 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.
type PgxPoolIface ¶
type PgxPoolIface interface { pgx.Tx Acquire(ctx context.Context) (*pgxpool.Conn, error) AcquireAllIdle(ctx context.Context) []*pgxpool.Conn AcquireFunc(ctx context.Context, f func(*pgxpool.Conn) error) error Close() Stat() *pgxpool.Stat AsConn() PgxConnIface // contains filtered or unexported methods }
func NewPool ¶
func NewPool(options ...func(*pgxmock) error) (PgxPoolIface, error)
NewPool creates PgxPoolIface pool of database connections 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.
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.
pgxmock can be customized to implement a different QueryMatcher configured through an option when pgxmock.New or pgxmock.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 pgxmock. It parses expectedSQL to a regular expression and attempts to match actualSQL.
type QueryMatcherFunc ¶
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: command tag: SELECT 2 scanned id: 1 and title: one scanned id: 2 and title: two
Example (CustomDriverValue) ¶
Output: 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: result set: 0 row 0 - [1 john] result set: 1 row 0 - [1 john] row 1 - [2 anna]
Example (RawValues) ¶
Output: one binary value with some text! two binary value with even more text than the first one
Example (RowError) ¶
Output: scanned id: 0 and title: one scanned id: 1 and title: two got rows error: row error
Example (Values) ¶
Output: one string value with some text! <nil> two string value with even more text than the first one <nil> [] <nil>
func NewRows ¶
NewRows allows Rows to be created from a sql interface{} slice or from the CSV string and to be used as sql driver.Rows. Use pgxmock.NewRows instead if using a custom converter
func NewRowsWithColumnDefinition ¶
func NewRowsWithColumnDefinition(columns ...pgconn.FieldDescription) *Rows
NewRowsWithColumnDefinition return rows with columns metadata
func (*Rows) AddCommandTag ¶
func (r *Rows) AddCommandTag(tag pgconn.CommandTag) *Rows
AddCommandTag will add a command tag to the result set
func (*Rows) AddRow ¶
AddRow composed from database interface{} slice return the same instance to perform subsequent actions. Note that the number of values must match the number of columns
func (*Rows) AddRows ¶ added in v2.1.0
AddRows adds multiple rows composed from any slice and returns the same instance to perform subsequent actions.
Example ¶
Output: scanned id: 1 and title: one scanned id: 2 and title: two
func (*Rows) CloseError ¶
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 ¶
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