pgvcr

README

go-pgvcr

This a testing library meant to record postgresql interactions once so the test can be replayed after without a real postgres server, just by replaying the records.

Once the records are done, this method is faster than a real Postgres and requires less resources, which is great for CI systems.

It also requires less manual work than mocks, and thus is less error-prone : SQL queries are tested at least once against a real server.

The idea is to emulate a real Postgres server at the TCP level so you can use any driver you want.

In recording mode, we just forward all messages between the client and the server and record them.

In replaying mode, we verify that the messages we receive from the client match what we recorded, and we reply with the recorded server messages.

Documentation

Index

• func ForceRecording(_ context.Context, _ Config) (bool, error)
• func ForceReplaying(_ context.Context, _ Config) (bool, error)
• func NewPgxTestingServer(t *testing.T, options ...func(config *Config)) *pgxpool.Pool
• func PostgresBuilderFallback(builders ...func(context.Context, Config) (ConnectionString, error)) func(context.Context, Config) (ConnectionString, error)
• func PostgresBuilderViaEnvVar(envKey string) func(_ context.Context, _ Config) (ConnectionString, error)
• func ReplayIfRecordExists(_ context.Context, cfg Config) (bool, error)
• type Config
• type ConnectionString
  • func PostgresBuilderViaTestContainers(ctx context.Context, cfg Config) (ConnectionString, error)
• type NoopHandler
  • func (n NoopHandler) Enabled(_ context.Context, _ slog.Level) bool
  • func (n NoopHandler) Handle(_ context.Context, _ slog.Record) error
  • func (n NoopHandler) WithAttrs(_ []slog.Attr) slog.Handler
  • func (n NoopHandler) WithGroup(_ string) slog.Handler
• type QueryOrderValidationStrategy
• type Server
  • func NewServer(cfg Config) Server
• type StartedServer

Functions

func ForceRecording

func ForceRecording(_ context.Context, _ Config) (bool, error)

func ForceReplaying

func ForceReplaying(_ context.Context, _ Config) (bool, error)

func NewPgxTestingServer

func NewPgxTestingServer(t *testing.T, options ...func(config *Config)) *pgxpool.Pool

func PostgresBuilderFallback

func PostgresBuilderFallback(builders ...func(context.Context, Config) (ConnectionString, error)) func(
	context.Context,
	Config,
) (ConnectionString, error)

func PostgresBuilderViaEnvVar

func PostgresBuilderViaEnvVar(envKey string) func(_ context.Context, _ Config) (ConnectionString, error)

func ReplayIfRecordExists

func ReplayIfRecordExists(_ context.Context, cfg Config) (bool, error)

Types

type Config

type Config struct {
	// EchoFilePath should be a path to a file we can read and write to store the mocking data.
	// Default value is "testdata/pgvcr.gob"
	EchoFilePath string
	// RealPostgresBuilder is a function returning the network address (host:port) of a real postgres database.
	// It will only be used when recording.
	// Default value uses "github.com/testcontainers/testcontainers-go/modules/postgres" to start a postgres in Docker.
	// Unused in replaying mode.
	RealPostgresBuilder func(ctx context.Context, cfg Config) (ConnectionString, error)
	// IsRecording is a function telling the server if it must write to the record or read it.
	// Default value decides to record if the file does not exist yet, and to replay if it does.
	IsRecording func(ctx context.Context, cfg Config) (bool, error)
	// Logger will be used by the server for all its logging.
	// Default value is a no-op logger.
	Logger *slog.Logger
	// QueryOrderValidationStrategy determines how to handle out-of-order queries in replay mode.
	// Default is QueryOrderValidationStrategyStalling
	QueryOrderValidationStrategy QueryOrderValidationStrategy
	// Listener
	// Default value listens on tcp://127.0.0.1: (random port)
	Listener net.Listener
}

type ConnectionString

type ConnectionString = string

ConnectionString (aka dsn)

func PostgresBuilderViaTestContainers

func PostgresBuilderViaTestContainers(ctx context.Context, cfg Config) (ConnectionString, error)

type NoopHandler

type NoopHandler struct{}

func (NoopHandler) Enabled

func (n NoopHandler) Enabled(_ context.Context, _ slog.Level) bool

func (NoopHandler) Handle

func (n NoopHandler) Handle(_ context.Context, _ slog.Record) error

func (NoopHandler) WithAttrs

func (n NoopHandler) WithAttrs(_ []slog.Attr) slog.Handler

func (NoopHandler) WithGroup

func (n NoopHandler) WithGroup(_ string) slog.Handler

type QueryOrderValidationStrategy

type QueryOrderValidationStrategy string

const (
	// QueryOrderValidationStrategyStrict forbids out-of-order queries.
	// Probably won't work if you have concurrent queries, but provides more security if you don't.
	QueryOrderValidationStrategyStrict QueryOrderValidationStrategy = "strict"
	// QueryOrderValidationStrategyStalling handles out-of-order queries by stalling them until it is their turn.
	// This allows concurrent queries as long as your queries don't end up waiting on each other (when you have maxed out your connection pool for example).
	// A 3 seconds timeout is configured so that it doesn't hang forever.
	QueryOrderValidationStrategyStalling QueryOrderValidationStrategy = "stalling"
)

type Server

type Server interface {
	Start(ctx context.Context) (StartedServer, error)
}

func NewServer

func NewServer(cfg Config) Server

type StartedServer

type StartedServer interface {
	Wait() error
	Stop() error
	ConnectionString() ConnectionString
}