sweep

package
v0.6.1 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: GPL-3.0 Imports: 18 Imported by: 0

Documentation

Overview

Package sweep is the read sweep a repository runs against a real server: every GET operation in a service's definitions, called on the generated SDK with arguments resolved from the suite's fixtures, and its answer decoded (or its file read). Bespoke tests prove the shapes a tool relies on field by field; the sweep proves the rest of the read surface answers in its documented status with something in it, that what the server sends lands in the model, and that it keeps doing so as the definitions change: a GET the importer adds is swept on the next run with nothing to write, and one that fails must be classified.

What the sweep holds an answer to: it decodes; it carries something (a file of at least one byte, JSON with at least one value that is not empty, zero or false, an event stream with at least one event), because an empty list decodes into any model and so proves nothing about its shape; and no object in it is lost whole, which is how a model whose fields do not match the server shows up (the JSON decoder drops a key it has no field for without a word). It does not check every field unless Strict asks: a server sends many its document does not declare, and a model that holds one of an object's keys holds that object.

An event stream (text/event-stream) never ends, so the sweep does not read one whole: it reads as far as the first event and hangs up. One that sends no event in the time the sweep waits (EventWait) is an answer with nothing in it, like an empty list.

Every operation either answers with something, or has a Case that says why not: the feature needs something the test server lacks, the endpoint is gone from the server, the server answers a shape its document does not describe, or what the operation reads is not there on a fresh server. A Status, Decode or Empty case whose operation starts answering fails the sweep, so a stale one is noticed and removed, the way a stale importer workaround is. A Skip case is never called, so it is only ever reviewed by hand. Nothing is allowed to answer one way on some runs and another on others, with two ways out for what no test can set up: MayBeEmpty, for an answer that follows the server image, and Sometimes, for a call that depends on something outside the server.

Index

Constants

View Source
const (
	// DefaultTimeout is how long one operation gets when the sweep sets none.
	DefaultTimeout = 60 * time.Second
	// DefaultEventWait is how long an event stream gets to send its first
	// event when the sweep sets none.
	DefaultEventWait = 10 * time.Second
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Case

type Case struct {
	// Skip leaves the operation uncalled, for the reason given.
	Skip string
	// Status is the error status the server answers with, and Decode is set
	// when it answers a body the documented model cannot decode; Why says
	// why that is the server's behaviour rather than a bug to fix.
	Status int
	Decode bool
	Why    string
	// Sometimes accepts an answer as well as the Status or the Decode, for a
	// call that depends on something outside the server (a catalogue it
	// fetches from the internet).
	Sometimes bool
	// Empty says why the operation answers with nothing on the fixtures (an
	// empty list, an object of zero values, a file of no bytes, an event
	// stream that sends no event while the sweep waits), which the sweep
	// otherwise fails.
	Empty string
	// MayBeEmpty says why the answer has something on one server image and
	// nothing on the next, so that neither is a failure.
	MayBeEmpty string
	// Path and Options supply arguments by parameter name and options field,
	// beyond what the fixtures resolve.
	Path    map[string]string
	Options map[string]any
}

Case is how the sweep treats one operation.

type Fixtures

type Fixtures struct {
	Path    map[string]string
	Options map[string]string
	Always  map[string]string
}

Fixtures resolves arguments from the suite's fixtures. A path parameter is looked up in Path as "<segments>/<param>", the literal path segments before the placeholder and the placeholder's name (Items/Id, Users/Id), then as the name alone; all case-insensitively. The segments are as many as stand between the placeholder and the one before it, and the most of them wins: /api/v3/config/indexer/{id} is api/v3/config/indexer/id, then v3/config/indexer/id, config/indexer/id and indexer/id, so the settings under config can be given another id than the list of the same name. A required option is looked up by name in Options; Always holds options set whenever an operation has them (the user an API key has to name for anything user-scoped).

type Outcome

type Outcome struct {
	// Skipped is why the operation was not called; empty when it was.
	Skipped string
	// Failures are what is wrong with the operation, its answer or its case;
	// none is a pass.
	Failures []string
	// Notes are what went as its case said it would.
	Notes []string
}

Outcome is what the sweep made of one operation.

type Sweep

type Sweep struct {
	// Definitions are the service's, as definitions.Load reads them.
	Definitions *definitions.Service
	// Client is the generated package's client, on which each operation's
	// method is called by name.
	Client any
	// StatusCode is the base client's: the status of an error for a status
	// the operation does not document, and 0 for any other error.
	StatusCode func(error) int
	// Fixtures resolve the arguments, and Cases, by operation name, say how
	// each operation that cannot simply answer is treated.
	Fixtures Fixtures
	Cases    map[string]Case
	// Strict also fails an answer that carries a key its model has no field
	// for, by model and key. Without it only an object lost whole is a
	// failure, since servers send many fields their documents leave out.
	Strict bool
	// Timeout is how long one operation gets; zero is DefaultTimeout.
	Timeout time.Duration
	// EventWait is how long an event stream gets, once it has answered, to
	// send its first event before the sweep hangs up and counts it as an
	// answer with nothing in it; zero is DefaultEventWait.
	EventWait time.Duration
}

Sweep is one service's read sweep.

func (Sweep) Operation

func (s Sweep) Operation(ctx context.Context, op *definitions.Operation) Outcome

Operation calls one operation and holds its answer to its case.

func (Sweep) Run

func (s Sweep) Run(t *testing.T)

Run sweeps every GET operation of the service, each as a subtest named for its method, and fails for a case that names no GET operation.

func (Sweep) StaleCases

func (s Sweep) StaleCases() []string

StaleCases names the cases that are for no GET operation of the service, which is what a case becomes when its operation is renamed or removed.

Jump to

Keyboard shortcuts

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