Documentation
¶
Overview ¶
Package conformance is a reusable test suite that a config codec adapter runs against its own codec to prove it behaves like a first-class backend.
The point is the D3 trap. The file machinery a codec plugs into — reading, fingerprinting for conflict detection, staging, atomic rename, rollback, watching — lives in the core and is shared, so an adapter cannot reimplement it wrongly. This suite is what confirms, per adapter, that a real source in the adapter's format takes part in merge, precedence, provenance and conflict detection exactly as the built-in YAML one does, rather than trusting it to.
An adapter writes one test:
func TestConformance(t *testing.T) {
conformance.Run(t, conformance.Suite{
Codec: jsonfile.Codec{},
Sample: []byte(`{"server":{"port":"9090"}}`),
Defines: map[string]string{"server.port": "9090"},
WriteKey: "server.host", WriteValue: "localhost",
})
}
It uses the standard library testing package and nothing else — deliberately no testify — so an adapter that runs it takes on no assertion-library dependency it would otherwise avoid.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run executes the whole suite against s, one named subtest per contract, so a failing adapter sees exactly which one it breaks.
Every codec is checked for the capability split, per-key merge with another format, tolerance of an absent source, and provenance naming the source. A read-only codec additionally has its layer confirmed skipped by write routing. An config.EditingCodec instead has its write round-trip, its no-edit no-op, and — the trap the seam exists to make unmissable — its refusal of a change that landed between load and write with config.ErrConflict checked, using WriteKey and WriteValue.
Types ¶
type Suite ¶
type Suite struct {
// Codec is the codec under test. When it also satisfies
// [config.EditingCodec], the editing assertions run.
Codec config.Codec
// Sample is a valid single-document source in the codec's format.
Sample []byte
// Defines is the keys Sample exposes and the value each reads back as
// through a View, so the suite can assert decoding, merge and provenance
// without knowing the format. At least one entry is required.
Defines map[string]string
// WriteKey and WriteValue are a key the codec can set and the value it is
// set to — required only for an [config.EditingCodec]. The value must read
// back after the write.
WriteKey string
WriteValue string
}
Suite describes a codec and the minimal sample of its format the assertions need. Read-only codecs supply the first four fields; an EditingCodec supplies WriteKey and WriteValue as well.
Source Files