tdd

func AssertConnectError ¶

func AssertConnectError(t *testing.T, err error, want connect.Code)

AssertConnectError asserts that err is non-nil and that the client would read the given code for it. It is the canonical assertion helper used inside TableRPC and is exported for direct use in hand-written tests.

"Would read" is svcerr.Code: the code svcerr.Interceptor sends for err. A handler test calls the *Service method directly, with no interceptor in between, so the error it sees is whatever the handler returned — and a handler may return a bare svcerr kind (`return nil, svcerr.NotFound("x")`) because the interceptor wraps it. connect.CodeOf read that as Unknown, which made the documented handler shape untestable without a client. For a *connect.Error the two agree.

func AssertScaffoldStub ¶

func AssertScaffoldStub(t *testing.T, err error)

AssertScaffoldStub asserts err is the error forge's generated handler stub returns — svcerr.ErrScaffoldStub. It backs Case.WantScaffoldStub and is exported for hand-written tests that drive a stub directly.

It accepts either identification, because which one is available depends on how far the error travelled. In process — a row calling the handler method directly — the chain is intact and errors.Is matches. Through a real Connect client the chain does not survive: the error is marshalled to the wire and rebuilt on the far side, so errors.Is is false and the reason METADATA is what arrives. Integration rows go over a client and unit rows do not, so both paths must work or the assertion would silently mean different things at the two tiers.

The failure message names what it found, because the interesting case is not "no error" but "a DIFFERENT error" — that is what an implemented handler produces, and the whole point of this row.

func E2EClient ¶

func E2EClient[Client any](t *testing.T, srv *httptest.Server, newClient func(url string) Client) Client

E2EClient takes an httptest.Server and a typed-client factory and returns a client wired to the server's URL. Cleanup of the server is registered via t.Cleanup, so the caller does not need to close it.

Typical usage with a generated Connect client:

client := tdd.E2EClient(t, srv, func(url string) myv1connect.MyServiceClient {
    return myv1connect.NewMyServiceClient(http.DefaultClient, url)
})

The factory receives the live server URL (including scheme and port).

func NewMock ¶

func NewMock[T any](opts ...MockOption[T]) *T

NewMock constructs a zero-valued T and applies each option.

T is typically a Forge-generated MockService. The returned pointer is safe to assign into a Deps struct that expects the contract interface — Forge mocks have a *MockService method-set that satisfies their matching Service interface.

func RunRPCCases ¶

func RunRPCCases[Req, Resp any](
	t *testing.T,
	cases []RPCCase[Req, Resp],
	handler HandlerFunc[Req, Resp],
)

RunRPCCases is a function alias for TableRPC — see RPCCase. The codegen-emitted test shim uses RunRPCCases so the generated call site mirrors the migration skill's documentation. Hand-written tests may call either; they have identical behaviour.

func SetupMockDB ¶

func SetupMockDB(t *testing.T) *sql.DB

SetupMockDB returns a fresh, isolated real-postgres *sql.DB suitable for hermetic unit tests. The DB and its underlying database are cleaned up via t.Cleanup, so the caller does not need to close it manually.

forge is postgres-pinned: the DB is a per-test database on the process-shared ephemeral postgres (pkg/pgtest — embedded-postgres by default, or the FORGE_TEST_POSTGRES_URL server). No driver blank-import is required; pgtest owns the driver. The first call in a process boots the shared server (downloading the pg binary on a fresh machine).

func TableContract ¶

func TableContract[T any](t *testing.T, impl T, cases []ContractCase)

TableContract runs a slice of ContractCase rows. Each row becomes a t.Run subtest. The helper invokes Setup, runs Call, and:

• if WantErr is set, asserts errors.Is(err, WantErr),
• else if Check is set, runs it on the returned value,
• else compares the returned value to Want via reflect.DeepEqual.

The impl parameter is unused at runtime — it exists so the call site reads naturally (TableContract(t, svc, cases)) and so the Go type system carries the implementation type into the closure capture, which is the most ergonomic shape we found for an "any method on T" table.

func TableRPC ¶

func TableRPC[Req, Resp any](
	t *testing.T,
	cases []Case[Req, Resp],
	handler HandlerFunc[Req, Resp],
)

TableRPC runs a slice of Case rows against a Connect handler. Each row becomes a t.Run subtest. The helper:

• calls Setup if present,
• invokes the handler with the row's request,
• asserts on WantErr (if set) or runs Check (if the call succeeded).

Subtests run with t.Parallel disabled by default so per-row Setup that touches shared state stays correct. Wrap the call site in a parallel outer test if you want concurrency; per-row parallelism is the caller's choice and not the library's default.

func WithTimeout ¶

func WithTimeout(d time.Duration) (context.Context, context.CancelFunc)

WithTimeout returns a context.Context with the given deadline and a cleanup function that cancels it. Suitable for use inside a Case.Setup hook or directly as Case.Ctx.

tdd.Case[Req, Resp]{
    Name: "slow", Req: ...,
    Ctx:  func() context.Context { ctx, _ := tdd.WithTimeout(2*time.Second); return ctx }(),
},

Cancel is exposed so tests that want eager cleanup can defer it; the returned context will already be canceled by Go's runtime once the timeout elapses.