From 73eac6099d6d30ab28149136fcef414205659ae2 Mon Sep 17 00:00:00 2001 From: Fabio Bonelli Date: Thu, 12 Nov 2026 11:53:13 +0000 Subject: [PATCH] doc: update the test data guide --- testdata/README.md | 46 ++++++++++++++++++++++++++++------------------ 1 file changed, 28 insertions(+), 18 deletions(-) diff --git a/testdata/README.md b/testdata/README.md index a7302fd..58de3f8 100644 --- a/testdata/README.md +++ b/testdata/README.md @@ -1,32 +1,42 @@ # Add new testcase files to this directory -**tl;dr**: +## Path -* `v0.1/valid/name.yml`: A valid v0.2 publiccode.yml testing the `name` key. -* `v0.1/invalid/name_missing.yml`: An invalid v0.1 publiccode.yml where the mandatory - `name` key is missing. -* `v0.2/invalid/latin1_encoded.yml`: An invalid v0.2 publiccode.yml with the wrong - encoding. +Fixtures are grouped by the major version of the core standard: `v0/` and +`v1/`, not by minor version (such as `v0.2/`). Paths below are relative to +this directory. -Rules are not enforced but help keeping things tidy. +The tests in [`v0_test.go`](../v0_test.go) read these directories: -## Path +* `v0/valid/`: Valid publiccode.yml files without warnings. +* `v0/valid_with_warnings/`: Valid files with expected warnings. +* `v0/invalid/`: Files with expected validation errors. -Put files in `VERSION/valid/` for valid YAML files for that version and -`VERSION/invalid/` for invalid YAML files. +Each directory also has a `no-network/` subdirectory. Put cases that test +parsing with `ParserConfig.DisableNetwork` enabled there. -Where `VERSION` is the version of the core standard prefixed by `v`. +The tests in [`v1_test.go`](../v1_test.go) read `v1/invalid/`, +`v1/invalid_valid_in_v0/` and `v1/invalid_valid_with_warnings_in_v0/`. +They currently expect the same unsupported version error for every file. +They do not validate v1 fields. `v1/valid/` is not read by these tests. -**Examples** +The globs only read YAML files directly inside each listed directory. +The v0 `no-network/` directories have separate tests. The v1 tests do not +read their `no-network/` subdirectories. -* `v0.2/valid/` -* `v0.2/invalid/` -* `v0.1/invalid/` +## File contents and expected results -## File contents +Start from [`v0/valid/valid.minimal.yml`](v0/valid/valid.minimal.yml) and +edit it to contain the subject of your test. Keep `publiccodeYmlVersion` +consistent with the version you want to test. -Start from `valid.minimal.yml` and edit it to contain the subject of -your test. +For every new file in `v0/invalid/` or `v0/valid_with_warnings/`, add an +entry keyed by its filename to the `expected` map in the corresponding +test in `v0_test.go`. The same applies to their `no-network/` subdirectories: +use the corresponding `_NoNetwork` test. Record the expected diagnostics, +including their line and column numbers. Without an entry, the test fails +with "No expected data for file". Valid files without warnings are discovered +automatically and need no map entry. Add comments only to the section / key being tested to draw attention to it and, if the testcase needs more context, add it as a comment at