shared

Documentation

Overview

Package shared implements utility functions for acceptance testing Hydra as well as shared test cases.

Index

• Variables
• func CreatePGPool(t *testing.T, ctx context.Context, username, password string, port int) (*pgxpool.Pool, error)
• func MustHaveValidArtifactDir(dir string)
• func RunAcceptanceTests(t *testing.T, ctx context.Context, cm DockerComposeManager, ...)
• func RunUpgradeTests(t *testing.T, ctx context.Context, cm DockerComposeManager)
• func TerminateDockerComposeProject(t *testing.T, ctx context.Context, project, logDir string, killAndCleanup bool)
• type Case
  • func AcceptanceCases() []Case
• type DockerComposeManager
• type PGVersion
  • func QueryPGVersion(t *testing.T, ctx context.Context, pool *pgxpool.Pool) PGVersion

Variables

var (
	BeforeUpgradeCases = []Case{
		{
			Name: "create columnar table",
			SQL: `
CREATE TABLE columnar_table
(
    id UUID,
    i1 INT,
    i2 INT8,
    n NUMERIC,
    t TEXT
) USING columnar;
		`,
		},
		{
			Name: "insert into columnar table",
			SQL: `
INSERT INTO columnar_table (id, i1, i2, n, t)
VALUES ('75372aac-d74a-4e5a-8bf3-43cdaf9011de', 2, 3, 100.1, 'hydra');
		`,
		},
	}
	AfterUpgradeCases = []Case{
		{
			Name: "force upgrade columnar ext",
			SQL: `
ALTER EXTENSION columnar UPDATE;
			`,
		},
		{
			Name: "create another columnar table",
			SQL: `
CREATE TABLE columnar_table2
(
    id UUID,
    i1 INT,
    i2 INT8,
    n NUMERIC,
    t TEXT
) USING columnar;
		`,
		},
		{
			Name: "validate columnar data",
			SQL:  "SELECT id, i1, i2, n, t FROM columnar_table LIMIT 1;",
			Validate: func(t *testing.T, row pgx.Row) {
				var result struct {
					ID uuid.UUID
					I1 int
					I2 int
					N  float32
					T  string
				}

				if err := row.Scan(&result.ID, &result.I1, &result.I2, &result.N, &result.T); err != nil {
					t.Fatal(err)
				}

				if result.ID != uuid.MustParse("75372aac-d74a-4e5a-8bf3-43cdaf9011de") {
					t.Errorf("id returned %s after upgrade, expected 75372aac-d74a-4e5a-8bf3-43cdaf9011de", result.ID)
				}

				if result.I1 != 2 {
					t.Errorf("i1 returned %d after upgrade, expected 2", result.I1)
				}

				if result.I2 != 3 {
					t.Errorf("i2 returned %d after upgrade, expected 3", result.I2)
				}

				if result.N != 100.1 {
					t.Errorf("n returned %f after upgrade, expected 100.1", result.N)
				}

				if result.T != "hydra" {
					t.Errorf("t returned %s after upgrade, expected hydra", result.T)
				}
			},
		},
	}
)

These describe the shared setup and validation cases that occur to validate the upgrade between two version of a Hydra-derived image.

var ErrPgPoolConnect = errors.New("pgxpool did not connect")

ErrPgPoolConnect is used when pgxpool cannot connect to a database.

Functions

func CreatePGPool

func CreatePGPool(t *testing.T, ctx context.Context, username, password string, port int) (*pgxpool.Pool, error)

CreatePGPool calls pgxpool.New and then sends a Ping to the database to ensure it is running. If the ping fails it returns a wrapped ErrPgPoolConnect.

func MustHaveValidArtifactDir

func MustHaveValidArtifactDir(dir string)

MustHaveValidArtifactDir ensures that if a artifact directory is present it is has an absolute path as go tests cannot determine the directory that they are running from.

func RunAcceptanceTests

func RunAcceptanceTests(t *testing.T, ctx context.Context, cm DockerComposeManager, additionalCases ...Case)

RunAcceptanceTests runs the shared acceptance tests for a given [ContainerManager] as well as any additional cases provided.

func RunUpgradeTests

func RunUpgradeTests(t *testing.T, ctx context.Context, cm DockerComposeManager)

RunUpgradeTests runs the shared upgrade tests for a given [ContainerManager].

func TerminateDockerComposeProject

func TerminateDockerComposeProject(t *testing.T, ctx context.Context, project, logDir string, killAndCleanup bool)

TerminateDockerComposeProject terminates a running docker compose project. If logDir is included then the container logs are saved to that directory before it is terminated. If killAndCleanup is false docker stop is used, otherwise docker compose kill is used and volumes are also deleted.

Types

type Case

type Case struct {
	Name             string                          // name of the test
	SQL              string                          // SQL to run during the test
	Validate         func(t *testing.T, row pgx.Row) // optional validation function
	Skip             bool                            // whether this case should be skipped
	TargetPGVersions []PGVersion                     // target PG version
}

A Case describes an acceptance test case. If a Validate function is provided then the test will call that function and expect it to handle test failues. Otherwise the case will fail if pool.Exec fails on the SQL.

func AcceptanceCases

func AcceptanceCases() []Case

AcceptanceCases describe the shared acceptance criteria for any Hydra-based images.

type DockerComposeManager

type DockerComposeManager interface {
	// StartCompose is responsible for starting the Docker Compose that includes a Hydra-based container and its test dependencies
	// then blocking until the Hydra container is able to accept Postgres connections.
	// startEverything indicates whether to start the test dependencies besides the Hydra container.
	StartCompose(t *testing.T, ctx context.Context, img string, startEverything bool)
	// TerminateCompose handles terminating the Docker compose, typically by using
	// [TerminateCompose].
	TerminateCompose(t *testing.T, ctx context.Context, kill bool)
	// Returns the image for the [ContainerManager]s.
	Image() string
	// Returns the UpgradeFromImage when the [ContainerManager] is used for
	// upgrade tests.
	UpgradeFromImage() string
	// Returns the already established pool for the container manager, typically
	// by calling [CreatePGPool]
	PGPool() *pgxpool.Pool
}

A DockerComposeManager provides a shared interface for managing the lifecycle of Hydra-based containers during testing.

type PGVersion

type PGVersion string

const (
	PGVersion13 PGVersion = "13"
	PGVersion14 PGVersion = "14"
	PGVersion15 PGVersion = "15"
	PGVersion16 PGVersion = "16"
)

func QueryPGVersion

func QueryPGVersion(t *testing.T, ctx context.Context, pool *pgxpool.Pool) PGVersion