Documentation
¶
Overview ¶
Package invoketest is the executable specification for invoke providers.
Every invoke.Environment implementation, in-tree or third-party, is expected to pass this suite. A provider's test calls Verify with a factory that constructs a fresh environment:
func TestContracts(t *testing.T) {
invoketest.Verify(t, func(t invoketest.T) invoke.Environment {
env, err := myprovider.New("target")
if err != nil {
t.Fatalf("constructing environment: %v", err)
}
return env
})
}
Each contract receives its own environment from the factory, so contracts are independent: destructive contracts (closing the environment, killing processes) cannot affect later ones, and no ordering between contracts is significant.
Optional features are governed by the provider's declared invoke.Capabilities, symmetrically: a declared capability's behavior contracts must pass, and an undeclared capability's requests must fail wrapping invoke.ErrNotSupported. Declaring honestly is therefore the only way through the suite — there is no silent middle ground.
A provider that does not yet satisfy a contract may skip it, loudly and temporarily, with WithKnownGap.
Index ¶
Constants ¶
const ( // CategoryCore covers basic command execution: streams, exit codes, // environment, working directory. CategoryCore = "core" // CategoryLifecycle covers process lifecycle: Wait idempotency, // cancellation, Close, and signal delivery. CategoryLifecycle = "lifecycle" // CategoryErrors covers classification into the error taxonomy. CategoryErrors = "errors" // CategoryTransfer covers Upload and Download semantics. CategoryTransfer = "transfer" // CategoryTTY covers pseudo-terminal allocation. CategoryTTY = "tty" )
Contract categories, used as the first segment of a contract's ID.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Factory ¶ added in v0.2.0
type Factory func(t T) invoke.Environment
Factory constructs a fresh environment for one contract. It reports construction problems on t (typically via Fatalf, or Skipf when the target is unavailable, such as a daemon that is not running).
type Option ¶ added in v0.2.0
type Option func(*verifyConfig)
Option configures a Verify run.
func WithKnownGap ¶ added in v0.2.0
WithKnownGap marks a contract the provider does not yet satisfy. The contract is skipped — visibly, with the supplied reason, which should reference a tracking issue — instead of failing the run.
It is a temporary escape hatch for landing a stricter contract before every provider honors it. Naming a contract ID that does not exist fails the run, so an opt-out cannot silently outlive a renamed or removed contract.
type T ¶
type T interface {
Helper()
Errorf(format string, args ...any)
Fatalf(format string, args ...any)
FailNow()
Skipf(format string, args ...any)
Logf(format string, args ...any)
Context() context.Context
TempDir() string
Name() string
}
T is the testing surface contracts run against. *testing.T satisfies it; the indirection lets the suite test its own contracts by running them against a recording implementation.
type TestCase ¶
type TestCase struct {
// Category is one of the Category constants.
Category string
// Name identifies the contract within its category, in kebab-case.
Name string
// Description states the behavior the contract enforces.
Description string
// Gate, when non-nil, decides from the environment's declared
// capabilities whether this contract applies. When it returns
// false, the contract is skipped with the returned reason. Paired
// contracts cover both sides of each capability, so a gated skip is
// always matched by a contract that does run.
Gate func(caps invoke.Capabilities) (bool, string)
// Run executes the contract against env, reporting failures on t.
Run func(t T, env invoke.Environment)
}
TestCase is a single behavioral contract.
func AllContracts ¶
func AllContracts() []TestCase
AllContracts returns the full contract set, for harnesses that need to enumerate or filter it. The returned cases are safe to inspect; run them via Verify where possible.
Source Files