pgxmock

package module
v4.3.0 Latest Latest
Warning

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

 Go to latest Published: Sep 9, 2024 License: BSD-3-Clause Imports: 14 Imported by: 5

README

Go Reference Go Report Card Coverage Status

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.21 version;
  • 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/v4

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

// 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(), pgxmock.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

The three clause BSD license

Star History

Star History Chart

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

Examples

Constants

This section is empty.

Variables

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

Functions

func NewResult 

func NewResult(op string, rowsAffected int64) pgconn.CommandTag

NewResult creates a new pgconn.CommandTag 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.

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 CallModifier 

type CallModifier interface {
	// Maybe allows the expected method call to be optional.
	// Not calling an optional method will not cause an error while asserting expectations
	Maybe() CallModifier
	// Times indicates that that the expected method should only fire the indicated number of times.
	// Zero value is ignored and means the same as one.
	Times(n uint) CallModifier
	// WillDelayFor allows to specify duration for which it will delay
	// result. May be used together with Context
	WillDelayFor(duration time.Duration) CallModifier
	// WillReturnError allows to set an error for the expected method
	WillReturnError(err error)
	// WillPanic allows to force the expected method to panic
	WillPanic(v any)
}

CallModifier interface represents common interface for all expectations supported

type ExpectedBatch 

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

ExpectedBatch is used to manage pgx.Batch expectations. Returned by pgxmock.ExpectBatch.

func (*ExpectedBatch) ExpectExec 

func (e *ExpectedBatch) ExpectExec(query string) *ExpectedExec

ExpectExec allows to expect Queue().Exec() on this batch.

func (*ExpectedBatch) ExpectQuery 

func (e *ExpectedBatch) ExpectQuery(query string) *ExpectedQuery

ExpectQuery allows to expect Queue().Query() or Queue().QueryRow() on this batch.

func (*ExpectedBatch) Maybe 

func (e *ExpectedBatch) Maybe() CallModifier

func (*ExpectedBatch) String 

func (e *ExpectedBatch) String() string

String returns string representation

func (*ExpectedBatch) Times 

func (e *ExpectedBatch) Times(n uint) CallModifier

func (*ExpectedBatch) WillDelayFor 

func (e *ExpectedBatch) WillDelayFor(duration time.Duration) CallModifier

func (*ExpectedBatch) WillPanic 

func (e *ExpectedBatch) WillPanic(v any)

func (*ExpectedBatch) WillReturnError 

func (e *ExpectedBatch) WillReturnError(err error)

type ExpectedBegin 

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

ExpectedBegin is used to manage *pgx.Begin expectation returned by pgxmock.ExpectBegin.

func (*ExpectedBegin) Maybe 

func (e *ExpectedBegin) Maybe() CallModifier

func (*ExpectedBegin) String 

func (e *ExpectedBegin) String() string

String returns string representation

func (*ExpectedBegin) Times 

func (e *ExpectedBegin) Times(n uint) CallModifier

func (*ExpectedBegin) WillDelayFor 

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

func (*ExpectedBegin) WillPanic 

func (e *ExpectedBegin) WillPanic(v any)

func (*ExpectedBegin) WillReturnError 

func (e *ExpectedBegin) WillReturnError(err error)

type ExpectedClose 

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

ExpectedClose is used to manage pgx.Close expectation returned by pgxmock.ExpectClose

func (*ExpectedClose) Maybe 

func (e *ExpectedClose) Maybe() CallModifier

func (*ExpectedClose) String 

func (e *ExpectedClose) String() string

String returns string representation

func (*ExpectedClose) Times 

func (e *ExpectedClose) Times(n uint) CallModifier

func (*ExpectedClose) WillDelayFor 

func (e *ExpectedClose) WillDelayFor(duration time.Duration) CallModifier

func (*ExpectedClose) WillPanic 

func (e *ExpectedClose) WillPanic(v any)

func (*ExpectedClose) WillReturnError 

func (e *ExpectedClose) WillReturnError(err error)

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

func (e *ExpectedCommit) Maybe() CallModifier

func (*ExpectedCommit) String 

func (e *ExpectedCommit) String() string

String returns string representation

func (*ExpectedCommit) Times 

func (e *ExpectedCommit) Times(n uint) CallModifier

func (*ExpectedCommit) WillDelayFor 

func (e *ExpectedCommit) WillDelayFor(duration time.Duration) CallModifier

func (*ExpectedCommit) WillPanic 

func (e *ExpectedCommit) WillPanic(v any)

func (*ExpectedCommit) WillReturnError 

func (e *ExpectedCommit) WillReturnError(err error)

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

func (e *ExpectedCopyFrom) Maybe() CallModifier

func (*ExpectedCopyFrom) String 

func (e *ExpectedCopyFrom) String() string

String returns string representation

func (*ExpectedCopyFrom) Times 

func (e *ExpectedCopyFrom) Times(n uint) CallModifier

func (*ExpectedCopyFrom) WillDelayFor 

func (e *ExpectedCopyFrom) WillDelayFor(duration time.Duration) CallModifier

func (*ExpectedCopyFrom) WillPanic 

func (e *ExpectedCopyFrom) WillPanic(v any)

func (*ExpectedCopyFrom) WillReturnError 

func (e *ExpectedCopyFrom) WillReturnError(err error)

func (*ExpectedCopyFrom) WillReturnResult 

func (e *ExpectedCopyFrom) WillReturnResult(result int64) *ExpectedCopyFrom

WillReturnResult arranges for an expected CopyFrom() to return a number of rows affected

type ExpectedDeallocate 

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

ExpectedDeallocate is used to manage pgx.Deallocate and pgx.DeallocateAll expectations. Returned by pgxmock.ExpectDeallocate(string) and pgxmock.ExpectDeallocateAll().

func (*ExpectedDeallocate) Maybe 

func (e *ExpectedDeallocate) Maybe() CallModifier

func (*ExpectedDeallocate) String 

func (e *ExpectedDeallocate) String() string

String returns string representation

func (*ExpectedDeallocate) Times 

func (e *ExpectedDeallocate) Times(n uint) CallModifier

func (*ExpectedDeallocate) WillDelayFor 

func (e *ExpectedDeallocate) WillDelayFor(duration time.Duration) CallModifier

func (*ExpectedDeallocate) WillPanic 

func (e *ExpectedDeallocate) WillPanic(v any)

func (*ExpectedDeallocate) WillReturnError 

func (e *ExpectedDeallocate) WillReturnError(err 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 
mock, _ := NewConn()
ex := mock.ExpectExec("^INSERT (.+)").WillReturnResult(NewResult("INSERT", 15))
ex.WillDelayFor(time.Second).Maybe().Times(2)

fmt.Print(ex)
res, _ := mock.Exec(ctx, "INSERT something")
fmt.Println(res)
ex.WithArgs(42)
fmt.Print(ex)
res, _ = mock.Exec(ctx, "INSERT something", 42)
fmt.Print(res)

Output:

ExpectedExec => expecting call to Exec():
	- matches sql: '^INSERT (.+)'
	- is without arguments
	- returns result: INSERT 15
	- delayed execution for: 1s
	- execution is optional
	- execution calls awaited: 2
INSERT 15
ExpectedExec => expecting call to Exec():
	- matches sql: '^INSERT (.+)'
	- is with arguments:
		0 - 42
	- returns result: INSERT 15
	- delayed execution for: 1s
	- execution is optional
	- execution calls awaited: 2
INSERT 15

func (*ExpectedExec) Maybe 

func (e *ExpectedExec) Maybe() CallModifier

func (*ExpectedExec) String 

func (e *ExpectedExec) String() string

String returns string representation

func (*ExpectedExec) Times 

func (e *ExpectedExec) Times(n uint) CallModifier

func (*ExpectedExec) WillDelayFor 

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

func (*ExpectedExec) WillPanic 

func (e *ExpectedExec) WillPanic(v any)

func (*ExpectedExec) WillReturnError 

func (e *ExpectedExec) WillReturnError(err error)

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(op string, rowsAffected int64) method to build a corresponding result.

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.

func (*ExpectedExec) WithRewrittenSQL 

func (e *ExpectedExec) WithRewrittenSQL(sql string) *ExpectedExec

WithRewrittenSQL will match given expected expression to a rewritten SQL statement by an pgx.QueryRewriter argument

type ExpectedPing 

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

ExpectedPing is used to manage Ping() expectations

func (*ExpectedPing) Maybe 

func (e *ExpectedPing) Maybe() CallModifier

func (*ExpectedPing) String 

func (e *ExpectedPing) String() string

String returns string representation

func (*ExpectedPing) Times 

func (e *ExpectedPing) Times(n uint) CallModifier

func (*ExpectedPing) WillDelayFor 

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

func (*ExpectedPing) WillPanic 

func (e *ExpectedPing) WillPanic(v any)

func (*ExpectedPing) WillReturnError 

func (e *ExpectedPing) WillReturnError(err error)

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

func (e *ExpectedPrepare) Maybe() CallModifier

func (*ExpectedPrepare) String 

func (e *ExpectedPrepare) String() string

String returns string representation

func (*ExpectedPrepare) Times 

func (e *ExpectedPrepare) Times(n uint) CallModifier

func (*ExpectedPrepare) WillDelayFor 

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

func (*ExpectedPrepare) WillPanic 

func (e *ExpectedPrepare) WillPanic(v any)

func (*ExpectedPrepare) WillReturnError 

func (e *ExpectedPrepare) WillReturnError(err error)

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

func (*ExpectedQuery) Maybe 

func (e *ExpectedQuery) Maybe() CallModifier

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

func (e *ExpectedQuery) Times(n uint) CallModifier

func (*ExpectedQuery) WillDelayFor 

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

func (*ExpectedQuery) WillPanic 

func (e *ExpectedQuery) WillPanic(v any)

func (*ExpectedQuery) WillReturnError 

func (e *ExpectedQuery) WillReturnError(err error)

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.

func (*ExpectedQuery) WithRewrittenSQL 

func (e *ExpectedQuery) WithRewrittenSQL(sql string) *ExpectedQuery

WithRewrittenSQL will match given expected expression to a rewritten SQL statement by an pgx.QueryRewriter argument

type ExpectedReset 

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

ExpectedReset is used to manage pgx.Reset expectation

func (*ExpectedReset) Maybe 

func (e *ExpectedReset) Maybe() CallModifier

func (*ExpectedReset) String 

func (e *ExpectedReset) String() string

func (*ExpectedReset) Times 

func (e *ExpectedReset) Times(n uint) CallModifier

func (*ExpectedReset) WillDelayFor 

func (e *ExpectedReset) WillDelayFor(duration time.Duration) CallModifier

func (*ExpectedReset) WillPanic 

func (e *ExpectedReset) WillPanic(v any)

func (*ExpectedReset) WillReturnError 

func (e *ExpectedReset) WillReturnError(err error)

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

func (e *ExpectedRollback) Maybe() CallModifier

func (*ExpectedRollback) String 

func (e *ExpectedRollback) String() string

String returns string representation

func (*ExpectedRollback) Times 

func (e *ExpectedRollback) Times(n uint) CallModifier

func (*ExpectedRollback) WillDelayFor 

func (e *ExpectedRollback) WillDelayFor(duration time.Duration) CallModifier

func (*ExpectedRollback) WillPanic 

func (e *ExpectedRollback) WillPanic(v any)

func (*ExpectedRollback) WillReturnError 

func (e *ExpectedRollback) WillReturnError(err error)

type Expecter 

type Expecter interface {
	// ExpectationsWereMet checks whether all queued expectations
	// were met in order (unless MatchExpectationsInOrder set to false).
	// If any of them was not met - an error is returned.
	ExpectationsWereMet() error

	// ExpectBatch expects pgx.Batch to be called. The *ExpectedBatch
	// allows to mock database response
	ExpectBatch() *ExpectedBatch

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

	// ExpectPrepare expects Prepare() to be called with expectedSQL query.
	ExpectPrepare(expectedStmtName, expectedSQL string) *ExpectedPrepare

	// ExpectDeallocate expects Deallocate() to be called with expectedStmtName.
	// The *ExpectedDeallocate allows to mock database response
	ExpectDeallocate(expectedStmtName string) *ExpectedDeallocate
	ExpectDeallocateAll() *ExpectedDeallocate

	// 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 pgx.Conn.Begin to be called.
	// the *ExpectedBegin allows to mock database response
	ExpectBegin() *ExpectedBegin

	// ExpectBeginTx expects expects BeginTx() to be called with expectedSQL
	// query. The *ExpectedBegin allows to mock database response.
	ExpectBeginTx(txOptions pgx.TxOptions) *ExpectedBegin

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

	// ExpectReset expects pgxpool.Reset() to be called.
	// The *ExpectedReset allows to mock database response
	ExpectReset() *ExpectedReset

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

	// ExpectPing expected Ping() to be called.
	// The *ExpectedPing allows to mock database response
	ExpectPing() *ExpectedPing

	// ExpectCopyFrom expects pgx.CopyFrom to be called.
	// The *ExpectCopyFrom allows to mock database response
	ExpectCopyFrom(expectedTableName pgx.Identifier, expectedColumns []string) *ExpectedCopyFrom

	// 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 []string slice.
	NewRows(columns []string) *Rows

	// NewRowsWithColumnDefinition allows Rows to be created from a
	// pgconn.FieldDescription slice with a definition of sql metadata
	NewRowsWithColumnDefinition(columns ...pgconn.FieldDescription) *Rows

	// New Column allows to create a Column
	NewColumn(name string) *pgconn.FieldDescription
}

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

type PgxCommonIface 

type PgxCommonIface interface {
	Expecter
	pgx.Tx
	BeginTx(ctx context.Context, txOptions pgx.TxOptions) (pgx.Tx, error)
	Ping(context.Context) error
}

PgxCommonIface represents common interface for all pgx connection interfaces: pgxpool.Pool, pgx.Conn and pgx.Tx

type PgxConnIface 

type PgxConnIface interface {
	PgxCommonIface
	Close(ctx context.Context) error
	Deallocate(ctx context.Context, name string) error
	DeallocateAll(ctx context.Context) error
	Config() *pgx.ConnConfig
	PgConn() *pgconn.PgConn
}

PgxConnIface represents pgx.Conn specific interface

func NewConn 

func NewConn(options ...func(*pgxmock) error) (PgxConnIface, error)

NewConn creates PgxConnIface database connection and a mock to manage expectations. Accepts options, like QueryMatcherOption, to match SQL query strings in more sophisticated ways.

type PgxPoolIface 

type PgxPoolIface interface {
	PgxCommonIface
	Acquire(ctx context.Context) (*pgxpool.Conn, error)
	AcquireAllIdle(ctx context.Context) []*pgxpool.Conn
	AcquireFunc(ctx context.Context, f func(*pgxpool.Conn) error) error
	AsConn() PgxConnIface
	Close()
	Stat() *pgxpool.Stat
	Reset()
	Config() *pgxpool.Config
}

PgxPoolIface represents pgxpool.Pool specific interface

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 QueryMatcherOption, to match SQL query strings in more sophisticated ways.

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 
// configure to use case sensitive SQL query matcher
// instead of default regular expression matcher
mock, err := NewConn(QueryMatcherOption(QueryMatcherEqual))
if err != nil {
	fmt.Println("failed to open pgxmock 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 := mock.Query(context.Background(), "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 pgxmock. 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 
mock, err := NewConn()
if err != nil {
	fmt.Println("failed to open pgxmock database:", err)
	return
}
defer mock.Close(context.Background())

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

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

rs, _ := mock.Query(context.Background(), "SELECT")
defer rs.Close()

fmt.Println("command tag:", rs.CommandTag())
if len(rs.FieldDescriptions()) != 2 {
	fmt.Println("got wrong number of fields")
}

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:

command tag: SELECT 2
scanned id: 1 and title: one
scanned id: 2 and title: two
Example (CustomDriverValue) 
mock, err := NewConn()
if err != nil {
	fmt.Println("failed to open pgxmock database:", err)
	return
}
defer mock.Close(context.Background())

rows := NewRows([]string{"id", "null_int"}).
	AddRow(5, pgtype.Int8{Int64: 5, Valid: true}).
	AddRow(2, pgtype.Int8{Valid: false})

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

rs, _ := mock.Query(context.Background(), "SELECT")
defer rs.Close()

for rs.Next() {
	var id int
	var num pgtype.Int8
	_ = 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: 5 and null int64: {5 true}
scanned id: 2 and null int64: {0 false}
Example (ExpectToBeClosed) 
mock, err := NewConn()
if err != nil {
	fmt.Println("failed to open pgxmock database:", err)
	return
}
defer mock.Close(context.Background())

row := NewRows([]string{"id", "title"}).AddRow(1, "john")
rows := NewRowsWithColumnDefinition(
	pgconn.FieldDescription{Name: "id"},
	pgconn.FieldDescription{Name: "title"}).
	AddRow(1, "john").AddRow(2, "anna")
mock.ExpectQuery("SELECT").WillReturnRows(row, rows).RowsWillBeClosed()

_, _ = mock.Query(context.Background(), "SELECT")
_, _ = mock.Query(context.Background(), "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 call to Query() or to QueryRow():
- matches sql: 'SELECT'
- is without arguments
- returns data:
	result set: 0
		row 0: [1 john]
	result set: 1
		row 0: [1 john]
		row 1: [2 anna]
*/

Output:

got error: expected query rows to be closed, but it was not: ExpectedQuery => expecting call to Query() or to QueryRow():
	- matches sql: 'SELECT'
	- is without arguments
	- returns data:
		result set: 0
			row 0: [1 john]
		result set: 1
			row 0: [1 john]
			row 1: [2 anna]
Example (RawValues) 
mock, err := NewConn()
if err != nil {
	fmt.Println("failed to open pgxmock database:", err)
	return
}
defer mock.Close(context.Background())

rows := NewRows([]string{"raw"}).
	AddRow([]byte(`one binary value with some text!`)).
	AddRow([]byte(`two binary value with even more text than the first one`)).
	AddRow([]byte{})
mock.ExpectQuery("SELECT").WillReturnRows(rows)

rs, err := mock.Query(context.Background(), "SELECT")
if err != nil {
	fmt.Print(err)
	return
}
defer rs.Close()

for rs.Next() {
	var rawValue []byte
	if err := json.Unmarshal(rs.RawValues()[0], &rawValue); err != nil {
		fmt.Print(err)
	}
	fmt.Println(string(rawValue))
}

Output:

one binary value with some text!
two binary value with even more text than the first one
Example (RowError) 
mock, err := NewConn()
if err != nil {
	fmt.Println("failed to open pgxmock database:", err)
	return
}
// defer mock.Close(context.Background())

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

rs, _ := mock.Query(context.Background(), "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
scanned id: 1 and title: two
got rows error: row error
Example (Values) 
mock, err := NewConn()
if err != nil {
	fmt.Println("failed to open pgxmock database:", err)
	return
}
defer mock.Close(context.Background())

rows := NewRows([]string{"raw"}).
	AddRow(`one string value with some text!`).
	AddRow(`two string value with even more text than the first one`).
	AddRow([]byte{})
mock.ExpectQuery("SELECT").WillReturnRows(rows)

rs, err := mock.Query(context.Background(), "SELECT")
if err != nil {
	fmt.Print(err)
	return
}
defer rs.Close()

for rs.Next() {
	v, e := rs.Values()
	fmt.Println(v[0], e)
}

Output:

one string value with some text! <nil>
two string value with even more text than the first one <nil>
[] <nil>

func NewRows 

func NewRows(columns []string) *Rows

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 

func (r *Rows) AddRow(values ...any) *Rows

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 

func (r *Rows) AddRows(values ...[]any) *Rows

AddRows adds multiple rows composed from any slice and returns the same instance to perform subsequent actions.

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

values := [][]any{
	{
		1, "one",
	},
	{
		2, "two",
	},
}

rows := NewRows([]string{"id", "title"}).AddRows(values...)

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

rs, _ := mock.Query(context.Background(), "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

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

func (r *Rows) Kind() pgx.Rows

Kind returns rows corresponding to the interface pgx.Rows useful for testing entities that implement an interface pgx.RowScanner

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

Source Files

View all Source files

Directories

Path Synopsis
basic
blog

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.