Documentation
¶
Overview ¶
Package testutil contains shared helpers for repository-local tests and benchmarks.
The package intentionally lives under internal/ so helpers can be reused across arcoris.dev/pool test packages without becoming part of the public module API.
Index ¶
- Constants
- func AppendOversizedPayload(dst []byte) []byte
- func AppendSamplePayload(dst []byte) []byte
- func AssertEventSequence(tb testing.TB, scenario string, got []string, want []string)
- func AssertPanicMessage(tb testing.TB, scenario string, fn func(), want string)
- func MustPanic(tb testing.TB, scenario string, fn func()) string
- func ParallelWarmCount() int
- func PrefillPool[T any](count int, newFn func() T, put func(T))
- func PrimePoolValue[T any](get func() T, put func(T))
- func ReportLifecycleMetrics(b *testing.B, news uint64, drops uint64, reuseDenials uint64)
- func ReportPerOpMetric(b *testing.B, total uint64, unit string)
- func WithControlledSteadyStatePoolRoundTrip(tb testing.TB, fn func())
- func WithGCDisabled(tb testing.TB, fn func())
- func WithSingleP(tb testing.TB, fn func())
- type RecordingSink
Constants ¶
const ( // MetricNewsPerOp is the canonical custom metric name for constructor events // observed per benchmark iteration. MetricNewsPerOp = "news/op" // MetricDropsPerOp is the canonical custom metric name for explicit // reuse-denial drop events observed per benchmark iteration. MetricDropsPerOp = "drops/op" // MetricReuseDenialsPerOp is the canonical custom metric name for reuse // policy denials observed per benchmark iteration. MetricReuseDenialsPerOp = "reuse_denials/op" )
Variables ¶
This section is empty.
Functions ¶
func AppendOversizedPayload ¶
AppendOversizedPayload appends the canonical oversized benchmark payload to dst.
The helper intentionally uses a shared zero-value array rather than allocating a temporary source slice on every call. This keeps oversized-path benchmarks focused on target growth and reuse policy instead of measuring incidental source-slice allocations.
func AppendSamplePayload ¶
AppendSamplePayload appends the repository's canonical small benchmark payload to dst.
Several benchmark families mutate a pooled byte slice with a short, allocation-free payload. Centralizing that payload keeps the suite consistent and removes repeated literal byte sequences from multiple files.
func AssertEventSequence ¶
AssertEventSequence verifies that an observed event log matches the expected sequence exactly.
Lifecycle-oriented tests use this helper to keep ordering assertions concise and to produce a stable diagnostic message when a semantic step moves or is omitted.
func AssertPanicMessage ¶
AssertPanicMessage verifies that fn panics and that the recovered panic value stringifies to the exact expected message.
The helper is used when panic text is part of the contract under test. It delegates panic capture to MustPanic so callers can keep panic assertions short while still producing a scenario-specific diagnostic on failure.
func MustPanic ¶
MustPanic runs fn and returns the recovered panic value formatted with fmt.Sprint.
If fn does not panic, the helper fails the test immediately. This keeps panic-based contract checks concise while preserving the scenario name in the failure output.
func ParallelWarmCount ¶
func ParallelWarmCount() int
ParallelWarmCount returns the default repository warm-up size for parallel pool benchmarks.
The value scales with the current GOMAXPROCS setting so the prefill step is proportional to the number of active Ps that may participate in sync.Pool local-cache distribution.
func PrefillPool ¶
PrefillPool stores count freshly constructed values into a pool-like sink.
Parallel benchmarks use this helper to avoid measuring an entirely cold pool when the question is concurrent steady-state behaviour.
func PrimePoolValue ¶
func PrimePoolValue[T any](get func() T, put func(T))
PrimePoolValue executes one Get/Put-style round trip before a benchmark loop starts.
Serial steady-state benchmarks use this helper to ensure the timed loop measures the reuse path rather than the first constructor miss.
func ReportLifecycleMetrics ¶
ReportLifecycleMetrics publishes the repository's three canonical pool counters for one benchmark run.
Use this helper when a benchmark intentionally observes constructor events, explicit drops, and reuse denials together. It keeps both metric names and reporting order stable across the suite and across generated reports.
func ReportPerOpMetric ¶
ReportPerOpMetric publishes a total counter as a per-iteration benchmark metric.
The helper keeps custom metric formatting consistent across the benchmark suite. It intentionally does nothing for empty benchmark runs.
func WithControlledSteadyStatePoolRoundTrip ¶
WithControlledSteadyStatePoolRoundTrip scopes a callback to a quieter runtime state for pool-focused tests and benchmarks.
Pinning execution to one P avoids per-P handoff noise, and disabling GC reduces the chance that cached values disappear between tightly coupled pool operations. The helper restores both runtime settings before it returns to the caller.
Despite the historical name, this helper does not turn exact same-instance reuse into a valid contract. Tests must still avoid asserting that a raw sync.Pool-backed path returns the exact value that was just stored. Use the helper only to reduce scheduler and GC noise around controlled scenarios, not to claim deterministic retention semantics.
func WithGCDisabled ¶
WithGCDisabled runs fn with automatic GC disabled and restores the previous GC target before returning.
This helper is useful when a test or benchmark needs to prevent transient GC cycles from discarding sync.Pool state between tightly-coupled Put/Get steps. As with WithSingleP, restoration happens immediately after fn returns so the helper composes safely inside larger tests.
func WithSingleP ¶
WithSingleP runs fn with GOMAXPROCS forced to 1 and restores the previous setting before returning.
The helper is intended for tests and benchmarks that need deterministic single-P behaviour, especially around sync.Pool local-cache semantics. The restoration is scoped to the callback itself rather than deferred to test cleanup so later assertions in the same test see the original runtime state.
Types ¶
type RecordingSink ¶
RecordingSink is a generic Put recorder for tests that need to observe the final storage step of a value.
When Events is non-nil, Put appends a literal "put" marker to that event log before storing the value in Puts.
func (*RecordingSink[T]) Put ¶
func (s *RecordingSink[T]) Put(value T)
Put records the final storage step of a value.
The method intentionally mirrors the minimal sink contract used by lifecycle tests: append an optional "put" event marker first, then retain the value in Puts for later inspection.
Source Files