Documentation
¶
Overview ¶
Package featuretest provides a conformance suite for feature.Driver implementations, modeled on testing/slogtest and testing/fstest.
Run executes one subtest per documented behavior of the contract: every value kind, integers read as floats, subject overrides, anonymous subjects, attributes, unknown keys, type mismatches, disabled flags, cancellation, updates, deletion and concurrency. A driver that passes is interchangeable with every other driver behind feature.Flags. Raw empty and unknown kinds must return feature.ErrTypeMismatch before flag lookup or disabled/default shortcuts, with cancellation taking precedence. These checks do not retry: kind validation cannot depend on propagation. Harnesses supply ready drivers, so adapters separately test invalid kinds before readiness and provider I/O.
Feature flags are read-only in the contract, so the suite cannot create them through the driver. The caller supplies a Harness that installs, replaces and removes Flag fixtures in the backend, by calling a setter (memory), an admin API, a test data source, or by writing a file. Each subtest gets its own harness from the factory passed to Run and its own unique flag keys, so a shared backend works.
Supply newHarness with signature func(*testing.T) featuretest.Harness. Its Set method adapts the raw Flag fixture to the backend's administration API; it is not an application feature.Flag declaration. For typed memory setup, switch on the fixture's canonical value type and construct a matching feature.Flag before calling Set or SetFor. The suite intentionally controls provider values independently so it can test mismatched evaluation kinds.
func TestDriver(t *testing.T) {
featuretest.Run(t, newHarness)
}
Backends that pick up changes asynchronously, such as ones that poll a file or an HTTP endpoint, pass WithPropagation; fixture-state reads are retried until it shows the expected state or the timeout passes. Backends where a change after the first evaluation cannot be observed pass WithoutUpdates.
The suite checks the reason only where the contract fixes it: a subject override must report feature.ReasonTargetingMatch and a disabled flag feature.ReasonDisabled. A plain value may report feature.ReasonStatic, feature.ReasonDefault or feature.ReasonUnknown. Variants are never checked. Fixture values are bool, string, int64 and float64 so that harnesses for remote backends can serialize them.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run executes the feature flag conformance suite against harnesses produced by newHarness. The factory is called once per subtest, so each subtest gets an isolated driver where the backend allows it; subtests also use unique flag keys so a shared backend works. Run calls t.Run for every group and marks the subtests parallel. Invalid-kind cases call the raw driver directly without propagation retries, including missing, disabled, default-only, and unmatched-override flags. Cancellation must take precedence. Harness drivers are ready by contract; adapters must separately test rejection before readiness or provider I/O.
featuretest.Run(t, func(*testing.T) featuretest.Harness {
return harness // A caller-owned implementation for an isolated backend.
}, featuretest.WithPropagation(time.Second))
Types ¶
type Flag ¶
type Flag struct {
// Key is the flag key, unique per subtest.
//
// Example: fixture := featuretest.Flag{Key: "checkout", Value: true}
Key string
// Value is the default value as bool, string, int64 or float64. Nil means
// the flag has no default value and only its Overrides.
//
// Example: fixture := featuretest.Flag{Key: "quota", Value: int64(25)}
Value any
// Overrides maps a subject key to the value that subject gets, with the
// same types as Value.
//
// Example: fixture := featuretest.Flag{Key: "checkout", Overrides: map[string]any{"user-42": true}}
Overrides map[string]any
// Disabled turns the flag off. The harness installs Value and Overrides
// first and then disables the flag, because a flag must exist to be
// disabled.
//
// Example: fixture := featuretest.Flag{Key: "checkout", Value: true, Disabled: true}
Disabled bool
}
Flag is a fixture the suite installs through a Harness.
A flag always carries a default Value, or at least one override: the suite never asks a harness to create a flag with neither, because some backends (memory among them) cannot represent one.
Example: fixture := featuretest.Flag{Key: "checkout", Value: true}
type Harness ¶
type Harness interface {
// Driver returns the driver under test. It must return the same driver on
// every call and be ready to evaluate (started, if it has a lifecycle).
//
// Example: driver := harness.Driver()
Driver() feature.Driver
// Set creates flag or replaces its definition entirely. It fails the test
// itself on error.
//
// Example: harness.Set(t, featuretest.Flag{Key: "checkout", Value: true})
Set(t *testing.T, flag Flag)
// Delete removes the flag key. Deleting a key that does not exist is not an
// error. It fails the test itself on error.
//
// Example: harness.Delete(t, "checkout")
Delete(t *testing.T, key string)
}
Harness gives the suite a driver and control over its backend's flags.
The suite calls Set before the first evaluation of a flag, and may call it again, or Delete, after the driver has served evaluations. Changes may become visible asynchronously when WithPropagation is given. A consumer implements this interface using its disposable backend setup; production flag-management operations do not belong to feature.Driver.
Example:
featuretest.Run(t, func(*testing.T) featuretest.Harness {
return harness // A caller-owned implementation for an isolated backend.
})
type Option ¶
type Option func(*config)
Option declares a capability or environment of the driver under test. Options never relax the contract's semantics.
Example: options := []featuretest.Option{featuretest.WithPropagation(time.Second)}
func WithPropagation ¶
WithPropagation declares that changes made through the Harness reach the driver asynchronously, within timeout. Every read that follows a Set or Delete, including the first read after the initial Set, is retried every 100 ms until it matches the expected state or the timeout passes. Without this option every read happens once. This controls the test's observation budget, not provider retry behavior.
Example: option := featuretest.WithPropagation(time.Second)
func WithoutUpdates ¶
func WithoutUpdates() Option
WithoutUpdates skips the subtests that change or delete a flag after the driver has served it, for backends where that cannot be observed in a test. It does not change the expected result of any evaluation that is exercised.
Example: option := featuretest.WithoutUpdates()