["shell/test", "script"]: make TEST_RUN_NUMBER available

If RUNS_PER_TEST is given, inform each individual test action about
the run number it is executing. This can be used, e.g., to set
random seeds appropriately.

3 files changed, 28 insertions, 4 deletions

diff --git a/README.md b/README.md
index d2b7e9a..c991c72 100644
--- a/README.md
+++ b/README.md
@@ -146,12 +146,12 @@ Shell test, given by a test script
 | `"keep"` | List of names (relative to the test working directory) of files that the test might generate that should be kept as part of the output. This might be useful for further analysis of the test |
 | `"name"` | A name for the test, used in reporting, as well as for staging the test result tree in the runfiles |
 | `"deps"` | Any targets that should be staged (with artifacts and runfiles) into the tests working directory |
-| `"test"` | The shell script for the test, launched with sh.  An empty directory is created to store any temporary files needed by the test, and it is made available in the environment variable TEST_TMPDIR. The test should not assume write permissions outside the working directory and the TEST_TMPDIR. For convenience, the environment variable TMPDIR is also set to TEST_TMPDIR. |
+| `"test"` | The shell script for the test, launched with sh.  An empty directory is created to store any temporary files needed by the test, and it is made available in the environment variable TEST_TMPDIR. The test should not assume write permissions outside the working directory and the TEST_TMPDIR. For convenience, the environment variable TMPDIR is also set to TEST_TMPDIR.  If the configuration variable RUNS_PER_TEST is set, the environment variable TEST_RUN_NUMBER will also be set to the number of the attempt, counting from 0. |
 
 | Config variable | Description |
 | --------------- | ----------- |
 | `"RUNS_PER_TEST"` | The number of times the test should be run in order to detect flakyness. If set, no test action will be taken from cache. |
-| `"TEST_ENV"` | The environment for executing the test runner. |
+| `"TEST_ENV"` | Additional environment for executing the test runner. |
 
 ### Rule `["CC/foreign/cmake", "library"]`
 
diff --git a/rules/shell/test/EXPRESSIONS b/rules/shell/test/EXPRESSIONS
index d1d7e64..ea36b32 100644
--- a/rules/shell/test/EXPRESSIONS
+++ b/rules/shell/test/EXPRESSIONS
@@ -132,7 +132,27 @@
         , {"type": "++", "$1": [["./runner"], {"type": "var", "name": "keep"}]}
         ]
       , [ "test_env"
-        , {"type": "var", "name": "TEST_ENV", "default": {"type": "empty_map"}}
+        , { "type": "map_union"
+          , "$1":
+            [ { "type": "if"
+              , "cond":
+                { "type": "=="
+                , "$1": {"type": "var", "name": "ATTEMPT"}
+                , "$2": null
+                }
+              , "then": {"type": "empty_map"}
+              , "else":
+                { "type": "singelton_map"
+                , "key": "TEST_RUN_NUMBER"
+                , "value": {"type": "var", "name": "ATTEMPT"}
+                }
+              }
+            , { "type": "var"
+              , "name": "TEST_ENV"
+              , "default": {"type": "empty_map"}
+              }
+            ]
+          }
         ]
       ]
     , "body":
diff --git a/rules/shell/test/RULES b/rules/shell/test/RULES
index 98bf27c..19f859f 100644
--- a/rules/shell/test/RULES
+++ b/rules/shell/test/RULES
@@ -12,6 +12,10 @@
       , "TEST_TMPDIR. The test should not assume write permissions"
       , "outside the working directory and the TEST_TMPDIR."
       , "For convenience, the environment variable TMPDIR is also set to TEST_TMPDIR."
+      , ""
+      , "If the configuration variable RUNS_PER_TEST is set, the environment"
+      , "variable TEST_RUN_NUMBER will also be set to the number of the attempt,"
+      , "counting from 0."
       ]
     , "name":
       [ "A name for the test, used in reporting, as well as for staging"
@@ -32,7 +36,7 @@
       [ "The number of times the test should be run in order to detect flakyness."
       , "If set, no test action will be taken from cache."
       ]
-    , "TEST_ENV": ["The environment for executing the test runner."]
+    , "TEST_ENV": ["Additional environment for executing the test runner."]
     }
   , "tainted": ["test"]
   , "artifacts_doc":