feat: warn when a matcher property is an empty list

[vsolano9]

Refs #1095. Follow-up to #1096, implementing what you asked for there:

I do think empty lists should produce a warning, even if they don't produce an error. It does smell like the kind of thing that somebody would only do by accident, but I don't think it's worth changing the existing behaviour.

So: warning, behaviour untouched.

What changed

isSetWarnEmpty sits next to isSet and wraps it. It warns when the property holds a list written out as empty, then returns exactly what isSet returned, so no matcher changes outcome.

All six properties that route through isSet are covered — command.stdout, command.stderr, file.contains, file.contents, http.headers, http.body:

$ goss -g vacuous.yaml validate
WARNING: vacuous_stderr_test: command.stderr is an empty list, which asserts nothing and always passes. Use "" to assert empty content, or remove it.
.

Total Duration: 0.018s
Count: 1, Failed: 0, Skipped: 0

Count: 1, Failed: 0 is unchanged from master — the check is still skipped and still passes.

The message follows the <id>: <type>.<property> shape deprecateAtoI already uses, and goes to stderr like the existing deprecation warnings, so stdout stays clean. Verified: -f json still parses as JSON, -f tap is unchanged, and integration-tests/test.sh captures stdout only, so nothing there sees the warning.

stderr: "" — the form the warning points at — produces no warning and correctly reports Count: 2, Failed: 1.

The thing you should decide

A gossfile generated by goss add file produces one warning per file. Measured, not guessed:

$ goss -g gen.yaml add file /etc/hosts
$ goss -g gen.yaml add file /etc/passwd
$ goss -g gen.yaml validate 2>&1 >/dev/null
WARNING: /etc/hosts: file.contents is an empty list, ...
WARNING: /etc/passwd: file.contents is an empty list, ...

That is the generator writing contents: [] (resource/file.go:125) and the warning correctly reporting that it asserts nothing. It is accurate, but it means the warning fires on goss's own output.

This repository's own fixtures hit it too — 8 empty-list matcher properties across testdata/passing.goss.yaml, testdata/failing.goss.yaml, goss-shared.yaml, goss-serve.yaml and goss-dummy.yaml would each print one line on stderr during an integration run. No test breaks, because they all read stdout. I left those files alone rather than editing fixtures to silence a warning about the thing they exercise.

If that noise is not acceptable, the fix is to stop goss add file writing contents: []. That is a generator behaviour change and it would need integration-tests/goss/*/goss-expected-q.yaml regenerating, so I did not fold it into this PR. Say the word and I'll do it as a separate one.

One more thing worth flagging: goss serve re-validates on cache miss, so a long-running server repeats the warning each time. That is exactly how the existing file.contains deprecation warning already behaves, so I kept it consistent rather than inventing a dedupe mechanism. Happy to add once-per-process dedupe if you'd rather.

Testing

resource/resource_test.go is new. It pins both halves of the contract: the warning fires only for an empty list, and the set/unset answer is byte-identical to isSet's for every input — nil, empty list, non-empty list, "", a string, and an empty map.

Both warning assertions were checked by disabling the warning and confirming they go red; TestIsSet* is otherwise vacuous. TestIsSetWarnEmptyNamesTheProperty also asserts exactly one line is written, so a future change that warns per element rather than per property fails.

gofmt -l, go vet ./..., go build ./..., go test ./... -count=1 all clean. npx markdownlint-cli2 "docs/**/*.md" reports 0 issues in 14 files, matching the docs workflow.

Docs: the two admonitions added in #1096 now say the warning exists and that generated gossfiles will trigger it, so the documentation still matches the behaviour.

AI assistance

This contribution was prepared with AI assistance. Every console block above is real output from the built binary on this branch, GOSS_USE_ALPHA=1, Go 1.26.5.

---

📚 Documentation preview 📚: https://goss--1097.org.readthedocs.build/en/1097/

[vsolano9]

The red coverage check here is not this PR. It's a pre-existing flaky race, and I've split the fix out into #1098.

I assumed it was mine first and went looking. race detected during execution of test in the root package, and the stacks point at two serve tests sharing the log buffer, nothing near isSetWarnEmpty. So I ran the same command the coverage job runs against clean master fbc8318:

Branch	DATA RACE
master, 8 runs	4
master, 12 more runs	7
#1098, 12 runs	0

master fails it more often than this branch does. Details and the full trace are in #1098.

Everything else here is green: build, lint, Lint Documentation, and the Read the Docs build.

If you merge #1098 first I'll rebase this one and the check should go green.

[kgaughan]

Looks good. There's a small change I'm hoping to add as part of some modernisation.