pgxmock

pgxmock allows you to simulate pgx behavior without a real database connection. It follows a strict expectation order by default.

To use it:

1. Create a mock using pgxmock.NewPool().
2. Define expectations using methods like ExpectBegin(), ExpectExec(), ExpectCommit(), or ExpectRollback().
3. Use WithArgs(...) to match specific arguments in queries.
4. Use WillReturnResult(...) or WillReturnError(...) to define the mock's response.
5. Execute your application logic using the mock object.
6. Verify all expectations were met using mock.ExpectationsWereMet().

Note: Your application code should accept an interface (e.g., PgxIface) that matches the pgx methods you use, allowing you to pass the mock in place of a real connection during tests.

package main

import (
	"context"
	"fmt"
	"testing"

	"github.com/pashagolub/pgxmock/v5"
)

// 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)
	}
}

The Expecter interface is the core mechanism for defining what database operations your code is expected to perform during a test. You use it to queue expectations for queries, executions, transactions, and more. After your code under test has run, you should call ExpectationsWereMet() to verify that all queued expectations were satisfied.

Key capabilities include:

• Query/Exec Mocking: Use ExpectQuery(expectedSQL) and ExpectExec(expectedSQL) to match SQL statements.
• Transaction Mocking: Use ExpectBegin(), ExpectCommit(), and ExpectRollback() to simulate transaction lifecycles.
• Order Control: By default, expectations must be met in the order they are defined. You can change this behavior using MatchExpectationsInOrder(bool) if your code executes queries in parallel (e.g., using goroutines).
• Result Simulation: Each expectation returns a specific object (like *ExpectedQuery or *ExpectedExec) that allows you to define the return values, errors, or rows that the mock should provide.

// Example of setting expectations
// mock is an implementation of Expecter

// Mock a query
queryExp := mock.ExpectQuery("SELECT * FROM users WHERE id = $1")
queryExp.WillReturnRows(mock.NewRows([]string{"id", "name"}))

// Mock an execution
execExp := mock.ExpectExec("UPDATE users SET name = $1 WHERE id = $2")
execExp.WillReturnResult(pgconn.NewCommandTag("UPDATE 1"))

// Verify all expectations were met
err := mock.ExpectationsWereMet()
if err != nil {
    t.Errorf("unmet expectations: %v", err)
}

The batchResults type (returned when using batching features in pgxmock) implements the pgx.Batch interface. It allows you to simulate the execution of a batch of queries by mapping each queued query in a pgx.Batch to a corresponding expectation defined in your mock.

When you call Exec(), Query(), or QueryRow() on the batch results, the mock retrieves the next queued query and its arguments from the batch and executes them against the mock's configured expectations.

Key behaviors:

• Sequential Execution: Each call to Exec, Query, or QueryRow advances to the next query in the pgx.Batch.
• Error Handling: If an error occurs during the retrieval of the next query, subsequent calls will return that error.
• Closing the Batch: Calling Close() ensures that any remaining queries in the batch that have associated functions (Fn) are executed. If no function is provided for a queued query, it defaults to an Exec call.

When matching arguments that are difficult to compare by value (like time.Time or custom structs), you can implement the Argument interface. The Match(v interface{}) bool method allows you to define custom logic to determine if a provided argument satisfies your requirement.

Example of matching any time.Time argument:

type AnyTime struct{}

// Match satisfies sqlmock.Argument interface
func (a AnyTime) Match(v interface{}) bool {
	_, ok := v.(time.Time)
	return ok
}

// In your test:
mock.ExpectExec("INSERT INTO users").
	WithArgs("john", AnyTime{}).
	WillReturnResult(pgxmock.NewResult(1, 1))

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 {
		err := err
		_ = err
		t.Errorf("there were unfulfilled expectations: %s", err)
	}
}

The CallModifier interface allows you to define how an expected method call should behave. You can use these modifiers on various expectation types (like ExpectedExec or ExpectedQuery) to control their lifecycle and return values.

Available modifiers:

• Maybe(): Makes the expected method call optional. Not calling it will not cause an error during assertion.
• Times(n uint): Specifies that the expected method must be called exactly n times. A value of 0 is treated as 1.
• WillDelayFor(duration time.Duration): Specifies a delay before the result is returned. This is useful for testing timeouts or context cancellations.
• WillReturnError(err error): Forces the expected method to return the provided error.
• WillPanic(v any): Forces the expected method to panic with the provided value v.

// Example usage of CallModifier
// Assuming 'mock' is a pgxmock instance

mock.ExpectExec("SELECT 1").
    Maybe().
    Times(2).
    WillDelayFor(100 * time.Millisecond).
    WillReturnError(errors.New("database error"))