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 ¶
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 ¶
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) Run ¶
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 ¶
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.