Documentation
¶
Overview ¶
Package test provides a conformance harness for comms providers.
The compiler checks a provider's method set. It cannot check the rules a caller actually relies on: that asking for a read-only provider yields one with nothing to post through, that Close is safe on a provider that never connected, that Messages returns a channel a caller can range over, or that the capabilities a provider claims are the ones it has. A provider can satisfy every interface in the contract and still be wrong in each of those ways.
Run it from the provider's own test suite:
func TestConformance(t *testing.T) {
commstest.RunProviderConformance(t, commstest.ConformanceConfig{
NewClient: func(c comms.ClientConfig) (comms.Client, error) {
return mydiscord.NewClient(c)
},
Capabilities: commstest.Capabilities{Moderator: true, Interactive: true},
Space: "123",
SecondSpace: "456",
AllowedChannel: "789",
})
}
Every check runs without a network. Behaviour that needs a live platform — that a thread is really created, that the allowlist really filters an inbound feed — belongs in the provider's own integration tests, gated behind an environment variable. The harness covers the contract a consumer depends on before a single message arrives.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RunProviderConformance ¶
func RunProviderConformance(t *testing.T, cfg ConformanceConfig)
RunProviderConformance runs every check and reports what it finds.
Types ¶
type Capabilities ¶
type Capabilities struct {
Moderator bool
MemberInspector bool
Interactive bool
Commands bool
// Author is replacing and retracting messages the consumer posted. Declared
// separately from Moderator because whose message it is decides which
// applies, and a provider may well offer one and not the other.
Author bool
// VoiceReceiver and VoiceSender are declared separately because they are
// separate interfaces: a provider may offer one without the other, and a
// build without the platform's voice support offers neither.
//
// A provider whose voice support is conditional on a build tag should
// declare these from the same build-tagged file that decides it, or the
// declaration and the reality drift apart in exactly the configuration
// nobody runs the harness in.
VoiceReceiver bool
VoiceSender bool
// VoiceParticipants is who is in a voice channel. Declared separately
// because it is answerable without capturing anything, and because it is
// the one capability discovered on the Reader — a provider may offer it
// with no voice capture at all.
VoiceParticipants bool
// Indicator is the consumer's words on the bot's name in the space.
Indicator bool
// ReactionObserver is hearing reactions change on messages. The second
// capability discovered on the Reader, for the same reason as
// VoiceParticipants: a reaction arriving is observed.
ReactionObserver bool
// SpaceInspector is reading the space's current name, the third
// capability discovered on the Reader: reading a name observes.
SpaceInspector bool
// AllowlistEditor is changing which channels a live scope reads, on the
// Reader because the allowlist governs reading.
AllowlistEditor bool
// ChannelManager and RoleManager are setting up a space (spec 0032).
// Declared separately because a role is a privilege no allowlist bounds,
// so a deployment may create channels without being able to grant roles.
ChannelManager bool
RoleManager bool
// ChannelInspector is reading one allowed channel's current details, on
// the Reader because reading a name observes (spec 0033).
ChannelInspector bool
// ChannelDirectory is listing the space's channels the bot can take part
// in, on the Reader because listing observes (spec 0040).
ChannelDirectory bool
// Poster is posting into a channel unprompted (spec 0034).
Poster bool
// Floor is inviting members to speak on a stage (spec 0035).
Floor bool
// ThreadReader is reading a thread's history, on the Reader because reading
// observes (spec 0042).
ThreadReader bool
// comms.ThreadSharesMessageID: whether a thread started from a message has
// that message's ID (spec 0042). Checked on a read-only scope.
ThreadSharesMessageID bool
}
Capabilities declares what the provider under test supports, so the harness can tell "correctly does not offer this" apart from "should and does not".
Declare honestly. Claiming a capability the provider lacks makes the harness look for something impossible; omitting one it has means nobody discovers it.
type ConformanceConfig ¶
type ConformanceConfig struct {
// NewClient builds a client from the given config. Called once per check,
// so each gets an independent transport.
NewClient func(comms.ClientConfig) (comms.Client, error)
// Needs are declared to the client under test. Leave empty and the harness
// declares every need the contract defines, less Refuses, so that every
// capability check can reach what it checks; set it to narrow a run to what
// the transport under test can serve. Naming a need here that is also in
// Refuses is a configuration error the run stops on.
Needs []comms.Need
// Refuses are the needs the transport under test can never serve, so a
// client asked for one must not be built: NewClient with that need alone
// returns a nil Client and an error matching ErrUnsupported that names it.
// A transport that carries audio only refuses NeedMessages this way.
//
// A declaration, as Capabilities is. Left empty, nothing is checked, and
// the run's needs are not narrowed.
Refuses []comms.Need
// Capabilities the provider claims.
Capabilities Capabilities
// Space is the guild, workspace or network the provider serves.
Space comms.ID
// AllowedChannel is a channel the provider should accept in its allowlist.
AllowedChannel comms.ID
// SecondSpace is a second space, used to check that scopes on different
// spaces are independent. Required.
//
// It is never dialled — like Space, it needs only to be an identifier your
// constructor accepts, so a fabricated one is fine and no second real
// space has to exist. Without it the sibling checks cannot run, and the
// run fails rather than skipping them: a harness that quietly drops a
// check when it is under-configured tells you your provider is sound when
// nothing looked at it.
SecondSpace comms.ID
}
ConformanceConfig configures a run.