nitunit manual: document NIT_TESTING, SRAND and NIT_TESTING_ID

[nit.git] / share / man / nitunit.md

diff --git a/share/man/nitunit.md b/share/man/nitunit.md
index 09d2467..e80e80e 100644 (file)
--- a/share/man/nitunit.md
+++ b/share/man/nitunit.md
@@ -118,6 +118,15 @@ Finally, standard markdown documents can be checked with:
 
     $ nitunit foo.md
 
 
     $ nitunit foo.md
 

+When testing, the environment variable `NIT_TESTING` is set to `true`.
+This flag can be used by libraries and program to prevent (or limit) the execution of dangerous pieces of code.
+
+~~~~~
+# NIT_TESTING is automatically set.
+#
+#     assert "NIT_TESTING".environ == "true"
+~~~~
+

 ## Working with `TestSuites`
 
 TestSuites are Nit files that define a set of TestCases for a particular module.
 ## Working with `TestSuites`
 
 TestSuites are Nit files that define a set of TestCases for a particular module.

@@ -160,6 +169,34 @@ class TestFoo
 end
 ~~~~
 
 end
 ~~~~
 

+## Black Box Testing
+
+Sometimes, it is easier to validate a `TestCase` by comparing its output with a text file containing the expected result.
+
+For each TestCase `test_bar` of a TestSuite `test_mod.nit`, if the corresponding file `test_mod.sav/test_bar.res` exists, then the output of the test is compared with the file.
+
+The `diff(1)` command is used to perform the comparison.
+The test is failed if non-zero is returned by `diff`.
+
+~~~
+module test_mod is test_suite
+class TestFoo
+       fun test_bar do
+               print "Hello!"
+       end
+end
+~~~
+
+Where `test_mod.sav/test_bar.res` contains
+
+~~~raw
+Hello!
+~~~
+
+If no corresponding `.res` file exists, then the output of the TestCase is ignored.
+
+## Configuring TestSuites
+

 `TestSuites` also provide methods to configure the test run:
 
 `before_test` and `after_test`: methods called before/after each test case.
 `TestSuites` also provide methods to configure the test run:
 
 `before_test` and `after_test`: methods called before/after each test case.

@@ -226,20 +263,28 @@ By default, only the modules indicated on the command line are tested.
 With the `--full` option, all imported modules (even those in standard) are also precessed.
 
 ### `-o`, `--output`
 With the `--full` option, all imported modules (even those in standard) are also precessed.
 
 ### `-o`, `--output`

-Output name (default is 'nitunit.xml')
+Output name (default is 'nitunit.xml').

 
 

-### `nitunit` produces a XML file comatible with JUnit.
+`nitunit` produces a XML file compatible with JUnit.

 
 ### `--dir`
 
 ### `--dir`

-Working directory (default is '.nitunit')
+Working directory (default is '.nitunit').

 
 In order to execute the tests, nit files are generated then compiled and executed in the giver working directory.
 
 
 In order to execute the tests, nit files are generated then compiled and executed in the giver working directory.
 

+### `--nitc`
+nitc compiler to use.
+
+By default, nitunit tries to locate the `nitc` program with the environment variable `NITC` or heuristics.
+The option is used to indicate a specific nitc binary.
+

 ### `--no-act`
 Does not compile and run tests.
 
 ### `-p`, `--pattern`
 ### `--no-act`
 Does not compile and run tests.
 
 ### `-p`, `--pattern`

-Only run test case with name that match pattern. Examples: `TestFoo`, `TestFoo*`, `TestFoo::test_foo`, `TestFoo::test_foo*`, `test_foo`, `test_foo*`
+Only run test case with name that match pattern.
+
+Examples: `TestFoo`, `TestFoo*`, `TestFoo::test_foo`, `TestFoo::test_foo*`, `test_foo`, `test_foo*`

 
 ### `-t`, `--target-file`
 Specify test suite location.
 
 ### `-t`, `--target-file`
 Specify test suite location.

@@ -247,7 +292,7 @@ Specify test suite location.
 ## SUITE GENERATION
 
 ### `--gen-suite`
 ## SUITE GENERATION
 
 ### `--gen-suite`

-Generate test suite skeleton for a module
+Generate test suite skeleton for a module.

 
 ### `-f`, `--force`
 Force test generation even if file exists.
 
 ### `-f`, `--force`
 Force test generation even if file exists.

@@ -260,6 +305,36 @@ Also generate test case for private methods.
 ### `--only-show`
 Only display the skeleton, do not write any file.
 
 ### `--only-show`
 Only display the skeleton, do not write any file.
 

+
+# ENVIRONMENT VARIABLES
+
+### `NITC`
+
+Indicate the specific Nit compiler executable to use. See `--nitc`.
+
+### `NIT_TESTING`
+
+The environment variable `NIT_TESTING` is set to `true` during the execution of program tests.
+Some libraries of programs can use it to produce specific reproducible results; or just to exit their executions.
+
+Unit-tests may unset this environment variable to retrieve the original behavior of such piece of software.
+
+### `SRAND`
+
+In order to maximize reproducibility, `SRAND` is set to 0.
+This make the pseudo-random generator no random at all.
+See `Sys::srand` for details.
+
+To retrieve the randomness, unit-tests may unset this environment variable then call `srand`.
+
+### `NIT_TESTING_ID`
+
+Parallel executions can cause some race collisions on named resources (e.g. DB table names).
+To solve this issue, `NIT_TESTING_ID` is initialized with a distinct integer identifier that can be used to give unique names to resources.
+
+Note: `rand` is not a recommended way to get a distinct identifier because its randomness is disabled by default. See `SRAND`.
+
+

 # SEE ALSO
 
 The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>
 # SEE ALSO
 
 The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>