Documentation
¶
Overview ¶
Package cloudstep holds what the cloud service packs share: waiting for something the services under test do asynchronously, matching rows, items, documents and messages against a step's table with the values of the other packs' JSON property steps, which mean what they say (ADR 0014), and reading seed files.
Index ¶
- Constants
- func Compact(body []byte) []byte
- func ExpectMatch(sc *core.Scenario, d time.Duration, in *Inbox, ...) error
- func ExpectMessage(sc *core.Scenario, d time.Duration, in *Inbox, rs Rows, field, where string) error
- func ExpectRecords(sc *core.Scenario, d time.Duration, fetch func() ([]string, error), rs Rows, ...) error
- func JSON(v any) string
- func Plain(v any) (any, error)
- func Poll(sc *core.Scenario, d time.Duration, check func() (bool, string, error)) error
- func RunID(s *core.Suite) string
- func Shown(what string, items []string, max int) string
- func TextPairs(t *core.Table) ([]core.Pair, error)
- func Wait(a core.Args, i int) time.Duration
- type Deferred
- type Inbox
- type Listeners
- type Message
- type Messages
- type ObjectStore
- type Objects
- type Rows
- type Sample
- type Seed
- type SeedOptions
Constants ¶
const DefaultWait = 10 * time.Second
DefaultWait is how long a check waits when its step does not say `within {duration}`: the services under test act asynchronously.
Variables ¶
This section is empty.
Functions ¶
func ExpectMatch ¶ added in v0.1.5
func ExpectMatch(sc *core.Scenario, d time.Duration, in *Inbox, match func(Message) (bool, error), field, what, where string) error
ExpectMatch waits until the inbox has a message, received since the scenario started, that match accepts. what is the word for one ("message", "event"); where names what was listened to; field is the word for the named values messages carry. When what the inbox listens to has ended, it fails at once, saying why.
func ExpectMessage ¶
func ExpectMessage(sc *core.Scenario, d time.Duration, in *Inbox, rs Rows, field, where string) error
ExpectMessage waits until the inbox has a message, received since the scenario started, that meets the conditions. where names what was listened to ("the invoice-events pubsub topic"); field is the word for the named values messages carry ("attribute", "property").
func ExpectRecords ¶
func ExpectRecords(sc *core.Scenario, d time.Duration, fetch func() ([]string, error), rs Rows, count int, what, where string) error
ExpectRecords waits until the records (rows, items, documents, as JSON) fetch returns include one that meets the conditions, or, with count >= 0, exactly count of them. what names them ("item", "row") and where names what holds them ("the claims dynamodb table").
func Plain ¶
Plain converts a compat JSON value to plain Go values: maps, slices, strings, bools, nil, and json.Number for numbers.
func Poll ¶
Poll calls check until it reports done or d has passed; check's last message explains the failure. Errors from check end the wait.
func RunID ¶
RunID names what a run creates in the cloud (subscriptions, queues), so runs do not collide and leftovers are recognizable: "axx-" and 8 hex digits.
func Shown ¶
Shown lists up to max candidates (rows, items, messages) for a failure report, the most recent last, saying how many were left out.
func TextPairs ¶ added in v0.3.0
TextPairs are the rows of a key and value table whose values are text (ADR 0014), each value the text it gives (core.ParseText): `"42"` gives 42, `""` the empty text, and a value that reads as anything else (`42`, `true`, `null`) or an empty cell is an error naming its row.
Types ¶
type Deferred ¶
type Deferred struct {
// contains filtered or unexported fields
}
Deferred holds what a pack plans before the apps start (Prepare) and does once they run (Init): the listeners of a run's checks need the topics and queues the environment creates.
func DeferredFor ¶
DeferredFor returns the pack's deferred work for the run.
type Inbox ¶
type Inbox struct {
// contains filtered or unexported fields
}
Inbox collects the messages a listener receives during a run, for the "has a message where:" checks of every scenario.
func (*Inbox) End ¶ added in v0.1.5
End records that what the inbox listens to has ended (the server closed the connection, the stream finished) and why. What arrived before still counts; a check that finds nothing among it fails at once instead of waiting for more.
type Listeners ¶
type Listeners struct {
// contains filtered or unexported fields
}
Listeners are the listeners one pack runs during a run, one per key (connection and topic, say), started once and stopped when the run ends.
func RunListeners ¶
RunListeners returns the pack's listeners for the run.
func (*Listeners) Start ¶
func (l *Listeners) Start(key string, start func(ctx context.Context, in *Inbox) (stop func(context.Context) error, err error)) (*Inbox, error)
Start runs start once for key and returns the inbox it fills. start receives the context of the whole run; stop undoes what it set up (a subscription it created, say).
type Message ¶
type Message struct {
Body []byte
Fields map[string]string
// Meta are values of the message itself, by the names checks give
// them: its "routing key", its "topic".
Meta map[string]string
// Received is when axx received it.
Received time.Time
}
Message is a message as the checks see it: its body and the named values sent with it (attributes, application properties).
type Messages ¶
type Messages struct {
// Pack is the pack name, the prefix of the step IDs.
Pack string
// Kind tells the steps of one kind of target from a pack's others, in
// their IDs: "queue" gives amqp.queue.send. Empty for a pack with one.
Kind string
// Target is how steps name what messages go to: "sqs queue",
// "pubsub topic", "service bus queue/topic".
Target string
// Verb is "sent" or "published".
Verb string
// Field names the values sent with a message: "attribute" or
// "property"; Fields is its plural.
Field, Fields string
// Key is a value of the message that the doc string form can give
// too, where a table cannot go: "routing key" gives "a message is
// published to the {word} amqp exchange[[ with the routing key
// {string}]]:". Send gets it as a field of that name. The Target must
// have no alternatives.
Key string
// Meta are the values of a message itself, not sent with it as
// fields, that checks read by name: "routing key", "topic".
Meta []string
// SendRows are the rows the "with the following <fields>:" table
// knows, when it takes more than fields.
SendRows []core.TableRow
// Typed are the rows of that table that set how a message is sent,
// whose values are numbers or booleans (ADR 0014): MQTT's "qos" and
// "retain". Send gets each as JSON (`1`, `true`, or `"1"` for the
// string). Every other value is text, and Send gets the text.
Typed []string
// Example is what the step examples send and check.
Example Sample
// Send sends a message.
Send func(sc *core.Scenario, target string, body []byte, fields map[string]string) error
// Inbox returns the listener for a target's checks; noun is the
// target's kind as the step wrote it ("service bus topic").
Inbox func(sc *core.Scenario, target, noun string) (*Inbox, error)
// Found, when set, is given the message a check found before the
// check passes: an error fails the check, as for a message that breaks
// its registration's contract.
Found func(sc *core.Scenario, target, noun string, msg Message) error
// Received explains in the pack's docs how the checks receive
// messages.
Received string
// Since is the axx version that introduced the pack, when it came
// after the message steps (0.1.0).
Since string
}
Messages describes the message steps of one messaging pack.
func (Messages) ID ¶ added in v0.1.5
ID is the ID of one of the pack's message steps: "send", "send.file" or "received".
func (Messages) Noun ¶
Noun is the target's kind as a step's text wrote it ("service bus topic" for "service bus queue/topic").
func (Messages) ReceivedStep ¶ added in v0.1.5
ReceivedStep is the check of the pack's message steps alone, for a kind of target that messages are not sent to (a NATS stream, whose subjects they are published to).
type ObjectStore ¶
type ObjectStore interface {
// Put stores an object.
Put(ctx context.Context, container, name string, body []byte, contentType string) error
// Get returns an object's content; ok is false when there is none.
Get(ctx context.Context, container, name string) (body []byte, ok bool, err error)
// List returns up to max object names of a container, for failure
// reports.
List(ctx context.Context, container string, max int) ([]string, error)
}
ObjectStore is an object storage service (S3, Cloud Storage, Blob Storage), or a folder, as the object steps use it.
type Objects ¶
type Objects struct {
// Pack is the pack name, the prefix of the step IDs.
Pack string
// Container is how steps name a container, e.g. "s3 bucket".
Container string
// Object is how steps name what it holds: "object", "blob".
Object string
// Example is a container name for the step examples.
Example string
// Store returns the scenario's store.
Store func(sc *core.Scenario) (ObjectStore, error)
// Since is the axx version that introduced the pack, when it came
// after the object steps (0.1.0): its steps are as old as it is.
Since string
// AbsentSince is the axx version that introduced the pack's check that
// an object is gone: empty while no release has it.
AbsentSince string
}
Objects describes the object steps of one storage pack.
func (Objects) Await ¶ added in v0.2.1
func (o Objects) Await(sc *core.Scenario, d time.Duration, container, name string, check func([]byte) (bool, string, error)) error
Await waits until the object exists and check accepts its content: for a pack's own check of its objects. A name with a * names the one object it matches.
type Rows ¶
Rows are the conditions of a "where:" table: each is a path into the JSON of a row, item, document or message (a column or field name, a dotted path, or a JSONPath) and the value it must have, typed as in the JSON property steps (core.ParseValue): `42` an integer, `"42"` the string, `null` null and `undefined` absent. A condition on a value sent with a message (an attribute) or of the message itself (its routing key) is on text (core.ParseText).
func Conditions ¶
Conditions reads a "where:" table of values alone. A value the rule cannot read (an empty cell, 01067) fails here, before the step waits for anything.
func MessageConditions ¶ added in v0.3.0
MessageConditions reads a "where:" table of a check on messages: a condition on "<field> <name>" or on one of meta is on text, and any other on a value (Readable), each failing here with what validate reports for it.
func (Rows) MatchMessage ¶
MatchMessage reports whether a message meets every condition. A condition on "<field> <name>" ("attribute eventType") is on a named value sent with the message; any other is a path into the body, which must then be JSON.
func (Rows) MatchMessageIn ¶ added in v0.1.5
MatchMessageIn is MatchMessage for messages with values of their own that conditions name (meta, "routing key"): a condition on one of them is on m.Meta.
func (Rows) Readable ¶ added in v0.3.0
Readable checks that the rule reads every condition's value (ADR 0014), before any message comes: a value in the body as a value (core.ParseValue), one sent with the message ("<field> <name>") or of the message itself (meta) as text (core.ParseText). A check fails at once on a value it cannot read, instead of waiting for a message.
type Sample ¶ added in v0.1.1
type Sample struct {
// To is a target the services read, which the examples send the JSON
// Body to, and the File with the Fields.
To, Body, File string
Fields [][2]string
// Key is the Key's value in the doc string form's example.
Key string
// From is a target the services write to, which the check example
// checks with the Where rows.
From string
Where [][2]string
}
Sample is what a messaging pack's step examples send and check, in the pack's own terms.
type Seed ¶
Seed is a seed file: names (tables, collections) in file order, each with its rows, items or documents.
func ReadSeed ¶
ReadSeed reads a YAML or JSON seed file whose top level maps names to their content.
func ReadSeedWith ¶ added in v0.1.1
ReadSeedWith is ReadSeed with options.
type SeedOptions ¶ added in v0.1.1
type SeedOptions struct {
// Timestamps keeps YAML's timestamps, for a service that stores them:
// an unquoted date or date and time (2026-09-01, 2026-09-01T10:00:00Z,
// 2026-09-01 10:00:00.5 +02:00) and a value tagged !!timestamp are
// time.Time values instead of their text. Quoted and block scalars, keys
// and JSON's strings stay strings.
Timestamps bool
}
SeedOptions change how ReadSeedWith reads a seed.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cloudtest runs the steps of packs in tests, as a run does: the cloud service packs against local cloud emulators, the web pack against a site the test serves.
|
Package cloudtest runs the steps of packs in tests, as a run does: the cloud service packs against local cloud emulators, the web pack against a site the test serves. |