Merge pull request #4105 from apostasie/tigron-doc

[DOC]: mod/tigron/require documentation

Author: AkihiroSuda

mod/tigron/require/doc.md

@@ -0,0 +1,63 @@
+# Requirements
+
+Any `test.Case` has a `Require` property that allow enforcing specific, per-test requirements.
+
+A `Requirement` is expected to make you `Skip` tests when the environment does not match
+expectations.
+
+A number of ready-made requirements are provided:
+
+```go
+require.Windows // a test runs only on Windows
+require.Linux // a test runs only on Linux
+test.Darwin // a test runs only on Darwin
+test.OS(name string) // a test runs only on the OS `name`
+require.Binary(name string) // a test requires the binary `name` to be in the PATH
+require.Not(req Requirement) // a test runs only if the opposite of the requirement `req` is fulfilled
+require.All(req ...Requirement) // a test runs only if all requirements are fulfilled
+```
+
+## Custom requirements
+
+A requirement is a simple struct (`test.Requirement`), that must provide a `Check` function.
+
+`Check` function signature is `func(data Data, helpers Helpers) (bool, string)`, that is expected
+to return `true` if the environment is fine to run that test, or `false` if not.
+The second parameter should return a meaningful message explaining what the requirement is.
+
+For example: `found kernel version > 5.0`.
+
+Given requirements can be negated with `require.Not(req)`, your message should describe the state of the environment
+and not whether the conditions are met (or not met).
+
+A `test.Requirement` can optionally provide custom `Setup` and `Cleanup` routines, in case you need to perform
+specific operations before the test run (and cleanup something after).
+
+`Setup/Cleanup` will only run if the requirement `Check` returns true.
+
+Here is for example how the `require.Binary` method is implemented:
+
+```go
+package thing
+
+func Binary(name string) *test.Requirement {
+    return &test.Requirement{
+        Check: func(_ test.Data, _ test.Helpers) (bool, string) {
+            mess := fmt.Sprintf("executable %q has been found in PATH", name)
+            ret := true
+            if _, err := exec.LookPath(name); err != nil {
+                ret = false
+                mess = fmt.Sprintf("executable %q doesn't exist in PATH", name)
+            }
+
+            return ret, mess
+        },
+    }
+}
+```
+
+## Gotcha
+
+Obviously, `test.Not(otherreq)` will NOT perform any `Setup/Cleanup` provided by `otherreq`.
+
+Ambient requirements are currently undocumented.