Expose information to tests about scope

Allow tests to find out if they are being running in the scope of all
files, or just a subset.

Add note to 'make xtest' helper script

Update search-categories to use this and skip a test that will
always fail if run on a subset of files.

Author: coke

lib/Test-Files.rakumod

@@ -2,18 +2,26 @@ unit class Test-Files;
 
 =begin overview
 
-Provide methods to generate a list of all C<files>, C<pod> documents,
-all C<documents> (POD and markdown), and C<tests> based on the output
-of C<git ls-files>.
+Utility methods for generating lists of files for testing.
 
-If the environment variable C<TEST_FILES> is set, it's treated a
-space-separated list of files to use instead. Files are trimmed from the list
-if they don't exist.
+=end overview
+
+#|(
+    Are we working with all the files in the repository?
+)
+method all-files() {
+    not (@*ARGS or %*ENV<TEST_FILES>);
+}
 
-If files were passed on the command line, use that list (as is) instead.
+#|(
+    Return list of files to test.
 
-=end overview
+    If files were passed on the command line, use those.
 
+    Otherwise, if the C<TEST_FILES> environmental variable is set to
+    a space-separated list of files, use that. Any files specified
+    this way that don't exist are silently removed.
+)
 method files() {
     my @files;
 
@@ -29,14 +37,23 @@ method files() {
     return @files.sort;
 }
 
+#|(
+    Filtered list of C<files> to return only Pod files.
+)
 method pods() {
     return $.files.grep({$_.ends-with: '.pod6'})
 }
 
+#|(
+    Filtered list of C<files> to return only Pod files and markdown.
+)
 method documents() {
     return $.files.grep({$_.ends-with: '.pod6' or $_.ends-with: '.md'})
 }
 
+#|(
+    Filtered list of C<files> to return only test files.
+)
 method tests() {
     return $.files.grep({$_.ends-with: '.t'})
 }

util/update-and-test

@@ -4,9 +4,12 @@
 
 Not everyone runs the extended test suite; this gives developers the ability
 to test as they go; it updates the repository, runs xtest only on those
-files that have changed in that update, and leaves a local 'retest' script
+files that have changed in that update, and leaves a local C<retest> script
 that can be rerun against those changes until xtest is clean.
 
+Note that test files are allowed to skip certain tests if they are run on a restricted
+subset of files; the full C<make xtest> should still be run on a regular basis.
+
 =end overview
 
 # Get the old and new commit IDs

xt/search-categories.t

@@ -32,11 +32,14 @@ for @files -> $file {
     }
 }
 
-# Note: if run on a subset of files, this will report false positives
-subtest "Category usage" => {
-    for @categories -> $category {
-        ok %*used-categories{$category}:exists, "Category「$category」is used in documentation";
+if Test-Files.all-files {
+    subtest "Category usage" => {
+        for @categories -> $category {
+            ok %*used-categories{$category}:exists, "Category「$category」is used in documentation";
+        }
     }
+} else {
+    skip "Can't check category usage when testing subset of files", 1;
 }
 
 sub test-ref ($ref) {