From: Dave Chinner <dchinner@xxxxxxxxxx>
Because how it actually gets used by the fstests infrastructure
has been undocumented and that has impact on how it should be set
up.
Signed-off-by: Dave Chinner <dchinner@xxxxxxxxxx>
---
README | 41 ++++++++++++++++++++++++++++++++---------
1 file changed, 32 insertions(+), 9 deletions(-)
diff --git a/README b/README
index 7da66cb6..eacf1acd 100644
--- a/README
+++ b/README
@@ -368,19 +368,42 @@ Test script environment:
6. Test group membership: Each test can be associated with any number
of groups for convenient selection of subsets of tests. Group names
- can be any sequence of non-whitespace characters. Test authors
- associate a test with groups by passing the names of those groups as
- arguments to the _begin_fstest function. For example, the code:
+ can be any sequence of non-whitespace characters, though human-readable
+ names that match the set [A-Za-z0-9\-] are highly prefered.
- _begin_fstest auto quick subvol snapshot
+ Test authors associate a test with groups by passing the names of those
+ groups as arguments to the _begin_fstest function. While _begin_fstests
+ is a shell function that must be called at the start of a test to
+ initialise the test environment correctly, the the build infrastructure
+ also scans the test files for _begin_fstests invocations. It does this
+ to compile the group lists that are used to determine which tests to run
+ when `check` is executed. In other words, test files files must call
+ _begin_fstest with their intended groups or they will not be run.
+
+ However, because the build infrastructure also uses _begin_fstests as
+ a defined keyword, addition restrictions are placed on how it must be
+ formatted:
+
+ (a) It must be a single line with no multi-line continuations.
+
+ (b) group names should be separated by spaces and not other whitespace
+
+ (c) A '#' placed anywhere in the list, even in the middle of a group
+ name, will cause everything from the # to the end of the line to be
+ ignored.
+
+ For example, the code:
+
+ _begin_fstest auto quick subvol snapshot # metadata
associates the current test with the "auto", "quick", "subvol", and
- "snapshot" groups. It is not necessary to specify the "all" group
- in the list because that group is computed at run time.
+ "snapshot" groups. Because "metadata" is after the "#" comment
+ delimiter, it is ignored by the build infrastructure and so it will not
+ be associated with that group.
+
+ It is not necessary to specify the "all" group in the list because that
+ group is always computed at run time from the group lists.
- The build process scans test files for _begin_fstest invocations and
- compiles the group list from that information. In other words, test
- files must call _begin_fstest or they will not be run.
Verified output:
--
2.35.1
