From 83c24e48a41cdda4e272a939c430feaeb5adf5ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kat=20March=C3=A1n?= Date: Tue, 31 Aug 2021 22:31:16 -0700 Subject: [PATCH] add a note about what to do if a test fails (or wrongly succeeds) --- tests/README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/tests/README.md b/tests/README.md index 0484ac4..354d644 100644 --- a/tests/README.md +++ b/tests/README.md @@ -6,6 +6,8 @@ output after being run through the parser and printed out again. If there's no file in `expected_kdl` with a name corresponding to one in `input` it indicates that parsing for that case should fail. +## Translation Rules + By necessity, the files in `expected_kdl` are not identical to their corresponding inputs. They are instead pretty-printed according to the following rules: @@ -34,3 +36,17 @@ following rules: Data may be manipulated as you wish in order to output the expected KDL. This test suite verifies the ability to **parse**, not specific quirks about internal representations. + +## What to do if a test fails for you + +This test suite was originally designed for a pre-1.0 version of the KDL +specification. If you encounter a failure, it's likely that the test suite +will need to be updated, rather than your parser itself. This test suite is +NOT AUTHORITATIVE. If this test suite disagrees with the KDL spec in any way, +the most desirable resolution is to send a PR to this repository to fix the +test itself. Likewise, if you think a test succeeded but should not have, +please send a PR. + +If you think the disagreement is due to a genuine error or oversight in the +KDL specification, please open an issue explaining the matter and the change +will be considered for the next version of the KDL spec.