drivertest

type Fixture[TTx any] interface {
	// NewDriver returns a driver on a fresh database with hopper's schema
	// installed, torn down when the test ends.
	NewDriver(t *testing.T) driver.Driver[TTx]
	// Begin starts a transaction. The suite calls commit or rollback.
	Begin(ctx context.Context, t *testing.T, d driver.Driver[TTx]) (tx TTx, commit, rollback func() error)
	// ExpireLease makes a client's lease expired, as a partition or a long
	// pause would.
	ExpireLease(ctx context.Context, t *testing.T, d driver.Driver[TTx], clientID int64)
	// ExpireLeader makes the leader lease expired.
	ExpireLeader(ctx context.Context, t *testing.T, d driver.Driver[TTx])
	// MakeClaimable moves a job's scheduled time to now.
	MakeClaimable(ctx context.Context, t *testing.T, d driver.Driver[TTx], id driver.JobID)
	// AgeAttempt backdates a running job's attempted time by age.
	AgeAttempt(ctx context.Context, t *testing.T, d driver.Driver[TTx], id driver.JobID, age time.Duration)
	// ExpireJobLease makes the job lease of a job claimed by ID expired, as
	// a worker that stopped renewing it would. CountJobLeases counts the job
	// lease rows the engine keeps.
	ExpireJobLease(ctx context.Context, t *testing.T, d driver.Driver[TTx], id driver.JobID)
	CountJobLeases(ctx context.Context, t *testing.T, d driver.Driver[TTx]) int
	// AgeClientStart backdates a client's start by age; a negative age
	// moves it ahead.
	AgeClientStart(ctx context.Context, t *testing.T, d driver.Driver[TTx], clientID int64, age time.Duration)
	// CountLive and CountHistory count jobs in the live table and in history.
	CountLive(ctx context.Context, t *testing.T, d driver.Driver[TTx]) int
	CountHistory(ctx context.Context, t *testing.T, d driver.Driver[TTx]) int
	// ExpireJob moves a live job's TTL deadline a second into the past.
	ExpireJob(ctx context.Context, t *testing.T, d driver.Driver[TTx], id driver.JobID)
	// StaleWake marks a running job as woken by JobRetryOrderingKey a second
	// before its attempt began, as a wake during an earlier attempt would.
	StaleWake(ctx context.Context, t *testing.T, d driver.Driver[TTx], id driver.JobID)
	// MakePending puts a live job back in the pending state, as a client
	// that stopped before promoting it would leave it.
	MakePending(ctx context.Context, t *testing.T, d driver.Driver[TTx], id driver.JobID)
	// SnoozeReason reads a live job's stored snooze reason, or "" for none,
	// which the driver's reads show only for a scheduled job. The suite
	// calls it from any goroutine. SetSnoozeReason stores one, as a client
	// of an earlier release, which cleared it neither on claim nor on
	// finalize, can leave it on a job that is not snoozed.
	SnoozeReason(ctx context.Context, t *testing.T, d driver.Driver[TTx], id driver.JobID) string
	SetSnoozeReason(ctx context.Context, t *testing.T, d driver.Driver[TTx], id driver.JobID, reason string)
	// SetProgress stores a JSON value as a live job's progress as it is, as
	// a direct SQL write could.
	SetProgress(ctx context.Context, t *testing.T, d driver.Driver[TTx], id driver.JobID, value string)
	// CountEdges counts the dependency edges the engine keeps for workflow
	// jobs that have not finished.
	CountEdges(ctx context.Context, t *testing.T, d driver.Driver[TTx]) int
	// CountJobResults counts the dependency results the engine keeps for
	// workflow steps' claims. DeleteJobResult deletes a job's, as a job
	// finished before the engine recorded them has none. OrphanJobResult
	// copies a job's to a workflow that does not exist, as a client of an
	// earlier release, completing a workflow, leaves one.
	CountJobResults(ctx context.Context, t *testing.T, d driver.Driver[TTx]) int
	DeleteJobResult(ctx context.Context, t *testing.T, d driver.Driver[TTx], id driver.JobID)
	OrphanJobResult(ctx context.Context, t *testing.T, d driver.Driver[TTx], id driver.JobID)
	// WaitForLockWait waits until a statement on the driver's database
	// waits for a lock another transaction holds, so that a test knows its
	// competing statement is blocked rather than not yet started.
	WaitForLockWait(ctx context.Context, t *testing.T, d driver.Driver[TTx])
}

type Postgres[TTx any] struct {
	// SQL runs statements on a driver's database, as PostgresFixture's Exec
	// and QueryText describe.
	SQL interface {
		Exec(ctx context.Context, t *testing.T, d driver.Driver[TTx], query string, args ...any)
		QueryText(ctx context.Context, t *testing.T, d driver.Driver[TTx], query string, args ...any) string
	}
}

type PostgresFixture[TTx any] interface {
	Fixture[TTx]
	// Exec runs a SQL statement with hopper's tables on the search path, for
	// rows the suite writes directly, such as those a client of the previous
	// release leaves behind. QueryText returns the single text value a query
	// selects, for what the driver's reads do not show. Both report a
	// failure with t.Error rather than t.Fatal, so the suite may call them
	// from any goroutine.
	Exec(ctx context.Context, t *testing.T, d driver.Driver[TTx], query string, args ...any)
	QueryText(ctx context.Context, t *testing.T, d driver.Driver[TTx], query string, args ...any) string
}