cloudstep

package
v0.7.5 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

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

View Source
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 Compact

func Compact(body []byte) []byte

Compact is JSON on one line, or the text as it is.

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 JSON

func JSON(v any) string

JSON renders a value as compact JSON.

func Plain

func Plain(v any) (any, error)

Plain converts a compat JSON value to plain Go values: maps, slices, strings, bools, nil, and json.Number for numbers.

func Poll

func Poll(sc *core.Scenario, d time.Duration, check func() (bool, string, error)) error

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

func RunID(s *core.Suite) string

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

func Shown(what string, items []string, max int) string

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

func TextPairs(t *core.Table) ([]core.Pair, error)

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.

func Wait

func Wait(a core.Args, i int) time.Duration

Wait is the optional `within {duration}` argument i, or DefaultWait.

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

func DeferredFor(s *core.Suite, pack string) *Deferred

DeferredFor returns the pack's deferred work for the run.

func (*Deferred) Add

func (d *Deferred) Add(key string, fn func(context.Context) error)

Add plans fn under key (planning a key twice keeps the first).

func (*Deferred) Run

func (d *Deferred) Run(ctx context.Context) error

Run does the planned work, in the order planned, and forgets it.

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) Add

func (b *Inbox) Add(m Message)

Add records a received message.

func (*Inbox) End added in v0.1.5

func (b *Inbox) End(why string)

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.

func (*Inbox) Ended added in v0.1.5

func (b *Inbox) Ended() (string, bool)

Ended reports why what the inbox listens to ended, if it has.

func (*Inbox) Fail

func (b *Inbox) Fail(err error)

Fail records why the listener stopped.

func (*Inbox) Since

func (b *Inbox) Since(t time.Time) ([]Message, error)

Since returns the messages received at or after t, or why the listener stopped.

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

func RunListeners(s *core.Suite, pack string) *Listeners

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

func (*Listeners) Started

func (l *Listeners) Started(key string) bool

Started reports whether key's listener was started.

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

func (Message) Describe

func (m Message) Describe(field string) string

Describe renders a message for a failure report: its own values, its named values and its body.

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

func (m Messages) ID(step string) string

ID is the ID of one of the pack's message steps: "send", "send.file" or "received".

func (Messages) Noun

func (m Messages) Noun(text string) string

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

func (m Messages) ReceivedStep() core.StepDef

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

func (Messages) Steps

func (m Messages) Steps() []core.StepDef

Steps are the pack's message steps: send a message given in the step or in a file (with its attributes), and wait for a message that meets conditions.

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.

func (Objects) Checks added in v0.1.1

func (o Objects) Checks() []core.StepDef

Checks are the pack's object checks: they wait for an object, its exact content, its JSON properties, its text or a row of its table, or for it to be gone.

func (Objects) Steps

func (o Objects) Steps() []core.StepDef

Steps are the pack's object steps: upload a file, and the checks.

type Rows

type Rows []core.Pair

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

func Conditions(t *core.Table) (Rows, error)

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

func MessageConditions(t *core.Table, field string, meta []string) (Rows, error)

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) Match

func (rs Rows) Match(doc string) (bool, error)

Match reports whether the JSON document meets every condition.

func (Rows) MatchMessage

func (rs Rows) MatchMessage(m Message, field string) (bool, error)

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

func (rs Rows) MatchMessageIn(m Message, field string, meta []string) (bool, error)

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

func (rs Rows) Readable(field string, meta []string) error

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

type Seed struct {
	Names []string
	Items map[string]any
}

Seed is a seed file: names (tables, collections) in file order, each with its rows, items or documents.

func ReadSeed

func ReadSeed(sc *core.Scenario, file string) (*Seed, error)

ReadSeed reads a YAML or JSON seed file whose top level maps names to their content.

func ReadSeedWith added in v0.1.1

func ReadSeedWith(sc *core.Scenario, file string, o SeedOptions) (*Seed, error)

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.

Jump to

Keyboard shortcuts

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