uiconformance

package

v2.10.1 Latest Latest Go to latest Published: Oct 9, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation ¶

Overview ¶

Package uiconformance is the one suite every interface to Cartograph must pass: the web interface, the terminal interface, and whatever an organisation builds. It is public so an interface in its own repository can import it and run it in its own CI.

The suite drives an interface through the Driver protocol, a small vocabulary of what a person does (open a flow, go to a step, set a field, act), and reads the vault back through a client.Client. It asserts on two things only: what the vault holds afterwards, and which problems the interface showed at which fields. It never looks at a widget, a pixel or a key binding, so two interfaces that pass it behave the same and a person can move between them.

The scenarios are data (scenarios/*.json), so a runner in another language can execute the same ones against an interface written in that language; this package is the Go runner and the reference.

Index ¶

func Execute(ctx context.Context, sc Scenario, d Driver, c client.Client) error
func Run(t *testing.T, factory func(t *testing.T) (Driver, client.Client))
type Action
type Driver
type Expect
type Field
type Location
type Problem
type Scenario
- func All() ([]Scenario, error)
type Step

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func Execute ¶

func Execute(ctx context.Context, sc Scenario, d Driver, c client.Client) error

Execute runs one scenario and returns the first failed step as an error naming the step number and what was expected.

func Run ¶

func Run(t *testing.T, factory func(t *testing.T) (Driver, client.Client))

Run executes every scenario against a fresh driver and client. The factory is called once per scenario so scenarios share no state.

Types ¶

type Action ¶

type Action string

Action is something a person does that is not filling a field.

const (
	ActSave        Action = "save"        // keep the working copy (never refused for incompleteness)
	ActSaveVersion Action = "saveVersion" // save a version; refused with problems when invalid
	ActDiscard     Action = "discard"     // drop the working copy
	ActNext        Action = "next"
	ActBack        Action = "back"
	ActApply       Action = "apply" // include an unapplied manifest in the live state
)

The actions every flow offers.

type Driver ¶

type Driver interface {
	Open(ctx context.Context, kind, id string) (string, error)
	Step(ctx context.Context, key string) error
	Set(ctx context.Context, field Field, value any) error
	Act(ctx context.Context, action Action, reason string) error
	Problems(ctx context.Context) ([]Problem, error)
	Where(ctx context.Context) (Location, error)
	Close(ctx context.Context) error
}

Driver is what an interface implements to be driven. A method returns an error only when the interface could not do what was asked (the control is missing, the step does not exist); a refusal shown to the person is not an error, it is a Problem.

type Expect ¶

type Expect struct {
	NoProblems bool `json:"noProblems,omitempty"`
	// Problem: a problem at Field whose message contains Contains.
	Problem *struct {
		Field    Field  `json:"field"`
		Contains string `json:"contains"`
	} `json:"problem,omitempty"`
	// Where: the interface is at this step.
	Where string `json:"where,omitempty"`
	// Current: the committed version's document has Field equal to
	// Value (Field "" with Version checks only the number).
	Current *struct {
		Field   Field `json:"field"`
		Value   any   `json:"value"`
		Version int   `json:"version"`
		Absent  bool  `json:"absent"`
	} `json:"current,omitempty"`
	// Working: the working copy has Field equal to Value.
	Working *struct {
		Field Field `json:"field"`
		Value any   `json:"value"`
	} `json:"working,omitempty"`
	// IDIsIdentifier: the id the interface is editing has no spaces.
	IDIsIdentifier bool `json:"idIsIdentifier,omitempty"`
}

Expect is an expectation checked against the interface or the vault.

type Field ¶

type Field string

Field is a JSON pointer into the manifest being edited, for example "/spec/objective" or "/spec/keyResults/{kr-1}/target" (a keyed list element by its key).

type Location ¶

type Location struct {
	Kind string
	ID   string
	Step string
}

Location is where the interface is: which flow (a kind), on which manifest, at which step.

type Problem ¶

type Problem struct {
	Field   Field
	Message string
}

Problem is one thing the interface shows as wrong: at a field, with a message. The same shape the engine answers, because that is where it comes from.

type Scenario ¶

type Scenario struct {
	Key   string `json:"key"`
	Name  string `json:"name"`
	Rule  string `json:"rule"` // the DESIGN_RULES line it holds
	Steps []Step `json:"steps"`
}

Scenario is one behaviour every interface must have, as steps.

func All ¶

func All() ([]Scenario, error)

All loads every scenario from the embedded files, sorted by key.

type Step ¶

type Step struct {
	Open *struct{ Kind, ID string } `json:"open,omitempty"`
	Step string                     `json:"step,omitempty"`
	Set  *struct {
		Field Field
		Value any
	} `json:"set,omitempty"`
	Act *struct {
		Action Action
		Reason string
	} `json:"act,omitempty"`
	Expect *Expect `json:"expect,omitempty"`
}

Step is one instruction to the driver, or one expectation. Exactly one of the fields below is set.

Source Files ¶

View all Source files

suite.go

Directories ¶

Path	Synopsis
clientdriver Package clientdriver is the reference Driver: it does what a person does, through a client.Client alone, walking the contract's flow.	Package clientdriver is the reference Driver: it does what a person does, through a client.Client alone, walking the contract's flow.

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