testenv

package
v0.1.0 Latest Latest
Warning

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

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

Documentation

Overview

Package testenv is what the two live suites share: the Dockhand and the Docker hosts .scripts/testenv.sh started for them, and which of the two ways a Dockhand is run they stand for - open, as it comes, with no login, or with its login switched on and asked with an API token. The machinery for reading the environment is go-kt's (test/env).

The SDK suite (../../acceptance/dockhand) drives the client in sdk/dockhand and the tool suite (../../acceptance/tools) drives the tools over MCP. Each runs twice on the same server, in order: open, and then with the login on - which this package switches on, through the client, as part of opening the second: the first user, the login, and a token for that user.

Opening a world also registers the two hosts as environments, through the client, each the way Dockhand reaches it: alpha by its socket and beta by the Hawser agent in front of it.

It is also where something is started on a host from outside Dockhand (Run, Compose): what Dockhand did not make is half of what it manages, and no API of Dockhand's makes it.

Index

Constants

View Source
const (
	// Alpha and Beta are the two Docker hosts .scripts/testenv.sh starts, by the names the suites register them under: alpha is reached by its
	// socket, and beta by the Hawser agent in front of it.
	Alpha = "alpha"
	Beta  = "beta"

	// NotConfigured is why a live test skips when the environment names no server.
	NotConfigured = `DOCKHAND_SERVER is not set: run "make testacc", or eval "$(.scripts/testenv.sh up)" first`
)
View Source
const (
	ConnectionSocket = "socket"
	ConnectionDirect = "direct"
	ConnectionAgent  = "hawser-standard"
	ConnectionCaller = "hawser-edge"
)

The ways Dockhand reaches a host, as it names them.

View Source
const Calls = "ws://dockhand:3000/api/hawser/connect" //nolint:revive // unsecure-url-scheme: the throwaway Dockhand is served without TLS, on a network of its own

Calls is what a Hawser agent that calls the Dockhand is told to call: the Dockhand by the name it has on the network the hosts share, where nothing outside that network hears what is said.

Variables

This section is empty.

Functions

func Configured

func Configured() bool

Configured reports whether the environment names a server and the hosts it is to manage. It names no token: a fresh Dockhand has none to give, and the suites make their own.

func HostPort

func HostPort(address string) (host string, port int, err error)

HostPort splits an address as the script gives one, host:port.

Types

type Stage

type Stage string

Stage is one of the ways the Dockhand under test is run.

const (
	// StageOpen is a Dockhand as it comes: no login, and nothing sent to say who is asking.
	StageOpen Stage = "open"
	// StageLogin is a Dockhand with its login switched on, asked with an API token.
	StageLogin Stage = "login"
)

type World

type World struct {
	Stage Stage
	// Server is the address the Dockhand answers on
	Server string
	// Token is the API token this run minted, "" in the open stage
	Token string
	// Dock is a client for the server as this stage asks it: with nothing, or with the token
	Dock *dockhand.Client

	// User and Password are the administrator the login stage makes
	User     string
	Password string

	// Socket is where Dockhand finds alpha's Docker socket, Direct the address alpha's Docker also listens on, and Agent the address of the Hawser
	// agent in front of beta, with the token it was started with
	Socket     string
	Direct     string
	Agent      string
	AgentToken string
	// Image is what the suites run on the hosts
	Image string
	// Scanned is an image old enough that a scanner finds plenty in it, and Scanner the image the scanner is run from: both where a host can pull
	// them without asking Docker Hub
	Scanned string
	Scanner string
	// Registry is where the hosts and the Dockhand find the registry the suites push to, which speaks plain HTTP and asks for the administrator's
	// name and password
	Registry string
	// Vault is where the Dockhand finds the secret store the suites save as a secret provider, which speaks Vault's API, and VaultToken the token it
	// takes: made up, and good for nothing but that store
	Vault      string
	VaultToken string
	// VaultByName is the same secret store by another address, its container's own name: for showing what Dockhand does when a provider's address
	// changes
	VaultByName string
	// Git is where the Dockhand finds the suites' git server, which speaks plain HTTP: a repository is at /open/<name>.git for anyone and at
	// /private/<name>.git for GitUser and GitPassword, a login made up for that server alone
	Git         string
	GitUser     string
	GitPassword string

	// Environments are the numbers Dockhand gave alpha and beta
	Environments map[string]dockhand.EnvironmentID
	// contains filtered or unexported fields
}

World is the Dockhand a live suite runs against, how it is run, and the hosts it manages.

func Open

func Open(ctx context.Context) (*World, error)

Open finds the Dockhand under test, runs it the way the stage asks - which for the login stage is switching its login on and minting a token - and registers the two hosts as environments.

func OpenBare

func OpenBare(ctx context.Context) (*World, error)

OpenBare is Open without the hosts: the Dockhand is run the way the stage asks and is left managing whatever it already manages, which on a fresh server is nothing. It is for a suite that adds the hosts itself, through what it tests, and then says which it added (Manages).

func (*World) Branch

func (w *World) Branch(ctx context.Context, repository, branch string) error

Branch gives a repository of the suites' git server another branch, at the commit its main branch is at.

func (*World) CallIn

func (w *World) CallIn(ctx context.Context, host, token string) error

CallIn starts a Hawser agent before one of the hosts that calls the Dockhand with a token, as an agent on a host Dockhand cannot reach does. One a run that was cut short left is taken away first.

func (*World) Commit

func (w *World) Commit(ctx context.Context, repository string, files map[string]string, gone ...string) (string, error)

Commit writes files into a repository of the suites' git server and commits them to its main branch, making the repository when there is none of that name, and takes out the files named as gone. It answers the new commit, shortened as Dockhand shortens one, and there always is one: a repository outlives a stage of the suites, so the next finds the files it writes there already and commits all the same. It is how a repository comes to hold something for Dockhand to deploy, and how it changes under a stack already deployed, which nothing in Dockhand can do.

func (*World) Compose

func (w *World) Compose(ctx context.Context, host, project, file string) error

Compose starts a compose project on a host from outside Dockhand, as a person at the host would: its file is written on the host and brought up.

func (*World) Docker

func (w *World) Docker(ctx context.Context, host string, args ...string) (string, error)

Docker runs a docker command on one of the hosts, inside the container the host is, and returns what it printed: how something is started on a host that Dockhand had no part in.

func (*World) Env

func (w *World) Env(host string) dockhand.EnvironmentID

Env is the number Dockhand gave a host.

func (*World) Freeze

func (w *World) Freeze(ctx context.Context, host string) error

Freeze holds the agent CallIn started for a host still, so that it neither answers nor calls again. An agent whose token stops working calls again with it a second later, is turned away, and Dockhand then turns away every call from the agent's address for five minutes, the next agent's with the right token among them, since a container that is removed leaves its address to the next. So a test that ends an agent's token holds the agent still first, and takes it away after.

func (*World) HangUp

func (w *World) HangUp(ctx context.Context, host string) error

HangUp takes away the agent CallIn started for a host; one that is not there is no error.

func (*World) Laid

func (w *World) Laid(ctx context.Context, path string) (string, error)

Laid reads a file inside the Dockhand's own container.

func (*World) Lay

func (w *World) Lay(ctx context.Context, path, content string) error

Lay writes a file inside the Dockhand's own container, as a folder mounted into it would hold one: where Dockhand looks for a compose file it is shown rather than given.

func (*World) Manages

func (w *World) Manages(host string, id dockhand.EnvironmentID)

Manages records the number Dockhand gave a host, for a suite that added the hosts itself.

func (*World) Repository

func (w *World) Repository(name string, private bool) string

Repository is the address Dockhand fetches a repository of the suites' git server from: the one anyone may read, or with private the one that asks for the server's login.

func (*World) Secrets

func (w *World) Secrets(ctx context.Context, args ...string) (string, error)

Secrets runs a command of the secret store's own in its container, signed in with its token, and returns what it printed: how a suite puts a secret there for Dockhand to load, and takes it away again, which nothing in Dockhand can do. The first argument is the command, as kv.

func (*World) Serve

func (w *World) Serve(ctx context.Context, host, name, file, content string) (string, error)

Serve has one of the hosts serve one file over HTTP, from a small container started on it from outside Dockhand, and returns the address Dockhand fetches it at: how a test gives Dockhand something to fetch without either of them asking the internet. One a run that was cut short left under the same name is taken away first.

func (*World) Unlay

func (w *World) Unlay(ctx context.Context, dir string) error

Unlay removes a directory a test laid inside the Dockhand's own container.

func (*World) Unserve

func (w *World) Unserve(ctx context.Context, host, name string) error

Unserve takes away what Serve started on a host; one that is not there is no error.

Jump to

Keyboard shortcuts

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