test

package
v0.34.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 7 Imported by: 0

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

	// ThreadSharesMessageID is what the provider reports through
	// 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL