Skip to content

Resolve local paths against the suite file and widen --check - #97

Merged
bgrewell merged 1 commit into
mainfrom
feature/docs-driven-fixes
Aug 8, 2026
Merged

Resolve local paths against the suite file and widen --check#97
bgrewell merged 1 commit into
mainfrom
feature/docs-driven-fixes

Conversation

@bgrewell

@bgrewell bgrewell commented Aug 8, 2026

Copy link
Copy Markdown
Owner

Five things the documentation had to apologize for. Rather than document the wart, fixed the behaviour.

One convention for local paths

Absolute paths are used as-is, ~ expands to the invoking user's home, and everything else resolves against the directory holding the suite file — not the process working directory.

That now covers file-step source/dest, docker volumes, LXD disk source, SSH key and known_hosts, LXD client/server certificates, and compose_file, joining docker.images[].dockerfile and !!load_from which already worked this way.

A suite is portable as a result. Verified by running the same suite from /:

[ local ] push a fixture named relative to the suite file ... done
00001: [ local ] the fixture arrived ... passed

Before this, that same run failed with open fixtures/app.conf: no such file or directory.

--check now validates what it was assumed to

  • Required fieldshost on ssh, image on docker, compose_file on docker-compose. An ssh node missing host used to pass the check and then fail the run dialling :22.
  • Unknown option names, reported with the accepted set:
    Error: node "web": unknown option "privilaged" for a docker node (accepted:
    capabilities, command, container_name, entrypoint, env, exec_opts, image,
    networks, ports, privileged, volumes)
    
    Options decode through a JSON round-trip that discards unrecognised keys, so privilaged left privileged at its default while the suite read as though it were set — a silent false green.
  • Cross-node constraints — duplicate node names and more than one local node. Both lived inline in the node factory, so --check (which substitutes mock nodes) never reached them. Extracted to ValidateNodeSet, called from both.

Two missing options

  • command / entrypoint on docker nodes override the image's CMD/ENTRYPOINT. A bare distribution image can now host a node — command: ["sleep", "infinity"] — instead of exiting the moment it starts.
  • container_name (docker) and instance_name (lxd) decouple the platform identifier from node identity. Both default to the node name, so nothing changes unless set. The node name remains what node: references, what reports show, and what the container's hostname is set to.

Note on strictness

Unknown option names are now a hard error, not a warning. That is the stricter reading — it is consistent with how the project has treated other silent-no-op classes, and a stray key in an existing suite will now fail rather than be ignored. Easy to soften to a warning if you would rather not break suites carrying dead keys.

Verification

New tests cover path resolution (including ~, ../, absolute, and the in-memory fallback), suite-dir stamping through load, name defaulting and override for both platforms, command/entrypoint decoding, unknown-option rejection across node types, and ValidateNodeSet. go build, go vet, gofmt, and the full suite are green, and the docs site builds.

Docs updated throughout — the notes describing the old behaviour are gone rather than reworded.

Five behaviours the documentation had to apologize for, fixed instead.

Local paths now follow one convention. Absolute paths are used as-is, `~`
expands to the invoking user's home, and everything else resolves against
the directory holding the suite file rather than the process working
directory. That covers file-step sources and destinations, docker volumes,
LXD disk sources, SSH keys and known_hosts, LXD certificates, and
compose_file, joining dockerfile and !!load_from which already worked this
way. A suite now behaves the same run from the repository root, from its
own directory, or from a CI checkout elsewhere.

--check gained the validation it was assumed to have:

- Required fields: host on ssh, image on docker, compose_file on
  docker-compose. Previously an ssh node missing host passed the check and
  failed the run dialling :22.
- Unknown option names, reported with the accepted set. Options decode
  through a JSON round-trip that discards unrecognised keys, so `privilaged`
  for `privileged` left the option at its default while the suite read as
  though it were set.
- Cross-node constraints — duplicate names and more than one local node —
  which lived in the node factory and so never ran under --check.

Two options that were missing:

- docker `command` and `entrypoint` override the image's CMD and ENTRYPOINT,
  so a bare distribution image can host a node instead of exiting at once.
- docker `container_name` and lxd `instance_name` decouple the platform
  identifier from node identity, defaulting to the node name. The node name
  stays what `node:` references and what reports show.
@bgrewell
bgrewell merged commit 5892607 into main Aug 8, 2026
2 checks passed
@bgrewell
bgrewell deleted the feature/docs-driven-fixes branch August 8, 2026 15:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant