ktest

func AssertContracts ¶

func AssertContracts(t *testing.T, actions []action.AnyAction)

AssertContracts checks structural invariants across every action and is intentionally soft: each action is validated in its own subtest using t.Errorf so that one bad action does not hide the rest.

func BenchAction ¶

func BenchAction[Req, Res any](b *testing.B, act *action.BuiltAction[Req, Res], req Req)

BenchAction benchmarks a built action's pure execution speed without transport overhead. Use it to lock in the zero-allocation hot path on Do/DoAny: a regression shows up in allocs/op immediately.

func Ctx ¶

func Ctx(tb testing.TB) (context.Context, *xctx.RequestScope)

Ctx returns a fresh request scope bound to context.Background() and registered with tb.Cleanup so it is released back to the pool when the test ends.

func CtxWithAuth ¶

func CtxWithAuth(tb testing.TB, userID, tenantID string, roles ...string) context.Context

CtxWithAuth is the common composite: user + tenant + roles in a single call.

func CtxWithPerm ¶

func CtxWithPerm(tb testing.TB, perm string) context.Context

CtxWithPerm returns a context carrying a scope with the given permission.

func CtxWithRole ¶

func CtxWithRole(tb testing.TB, role string) context.Context

CtxWithRole returns a context carrying a scope with the given role.

func CtxWithTenant ¶

func CtxWithTenant(tb testing.TB, tenantID string) context.Context

CtxWithTenant returns a context carrying a scope with the tenant ID.

func CtxWithUser ¶

func CtxWithUser(tb testing.TB, userID string) context.Context

CtxWithUser returns a context carrying a scope with the user ID.

func Echo ¶

func Echo[T any](name string) *action.Builder[T, T]

Echo returns a typed action that returns its request unchanged.

func Fails ¶

func Fails[Req, Res any](name string, err error) *action.Builder[Req, Res]

Fails returns a typed action that always returns err and the zero response.

func Fake ¶

func Fake(name string, res any) action.AnyAction

Fake returns an untyped action that always succeeds with res. Prefer Returns when the request and response types are known.

func FakeErr ¶

func FakeErr(name string, err error) action.AnyAction

FakeErr returns an untyped action that always fails with err. Prefer Fails when the request and response types are known.

func FakeSeq ¶

func FakeSeq(name string, values ...any) action.AnyAction

FakeSeq returns an untyped action that yields each value in order, then repeats the last one. Prefer Sequence when the response type is known.

func Flaky ¶

func Flaky[Req, Res any](name string, failures int, err error, value Res) *action.Builder[Req, Res]

Flaky returns err for the first failures executions and then returns value. It is deterministic and safe for concurrent action execution.

func MustError ¶

func MustError[Req, Res any](tb testing.TB, fn action.Fn[Req, Res], req Req, want error)

func MustExecute ¶

func MustExecute[Req, Res any](tb testing.TB, fn action.Fn[Req, Res], req Req) Res

func NewErrAction ¶

func NewErrAction(name string, err error) *action.Builder[struct{}, string]

NewErrAction returns a new action builder that accepts struct{} and returns ("", err).

func NewOkAction ¶

func NewOkAction(name string) *action.Builder[struct{}, string]

NewOkAction returns a new action builder that accepts struct{} and returns ("ok", nil).

func RequestContext ¶

func RequestContext(tb testing.TB, requestID string) context.Context

RequestContext returns the test context carrying requestID. The request ID is the idempotency key used by action middleware; cancellation and timeout remain explicit with context.WithCancel/WithTimeout at the call site.

func RequireCondition ¶

func RequireCondition(tb testing.TB, condition bool, format string, args ...any)

RequireCondition fails the test when condition is false.

func RequireEqual ¶

func RequireEqual[T any](tb testing.TB, got, want T)

RequireEqual fails the test when got and want differ.

func RequireErrorContains ¶

func RequireErrorContains(tb testing.TB, err error, substr string)

RequireErrorContains fails the test when err is nil or lacks substr.

func RequireErrorIs ¶

func RequireErrorIs(tb testing.TB, err, target error)

RequireErrorIs fails the test when err does not wrap target.

func RequireErrorKind ¶

func RequireErrorKind(tb testing.TB, err error, want xerr.Kind)

RequireErrorKind fails the test unless err is an *xerr.AppError with the given kind. It prints the full error on failure so the caller does not need a second assertion to see what actually happened.

func RequireNoError ¶

func RequireNoError(tb testing.TB, err error)

RequireNoError fails the test when err is non-nil.

func RequirePermanent ¶

func RequirePermanent(tb testing.TB, err error)

RequirePermanent fails the test unless err is permanent by xerr rules (must not be retried).

func RequireStringContains ¶

func RequireStringContains(tb testing.TB, value, substr string)

RequireStringContains fails the test when value lacks substr.

func RequireTransient ¶

func RequireTransient(tb testing.TB, err error)

RequireTransient fails the test unless err is transient by xerr rules (safe to retry).

func Returns ¶

func Returns[Req, Res any](name string, value Res) *action.Builder[Req, Res]

Returns returns a typed action that always returns value.

func Script ¶

func Script[Req, Res any](results ...Result[Res]) action.Fn[Req, Res]

func Sequence ¶

func Sequence[Req, Res any](name string, values ...Res) *action.Builder[Req, Res]

Sequence returns values in order and repeats the final value thereafter. The sequence is safe for concurrent action execution.

func Simulate ¶

func Simulate[Req, Res any](
	tb testing.TB,
	act *action.BuiltAction[Req, Res],
	req Req,
	concurrency int,
	assertFn func(tb testing.TB, res Res, err error),
)