3 nitunit - executes the unit tests from Nit source files.
7 nitunit [*options*] FILE...
11 Unit testing in Nit can be achieved in two ways:
13 * using `DocUnits` in code comments or in markdown files
14 * using `TestSuites` with test unit files
16 `DocUnits` are executable pieces of code found in the documentation of groups, modules,
17 classes and properties.
18 They are used for documentation purpose, they should be kept simple and illustrative.
19 More advanced unit testing can be done using TestSuites.
21 `DocUnits` can also be used in any markdown files.
23 `TestSuites` are test files coupled to a tested module.
24 They contain a list of test methods called TestCase.
26 ## Working with `DocUnits`
28 DocUnits are blocks of executable code placed in comments of modules, classes and properties.
29 The execution can be verified using `assert`.
36 # assert foo.bar == 10
42 Everything used in the test must be declared.
43 To test a method you have to instantiate its class:
48 # assert foo.bar == 10
51 # assert foo.baz(1, 2) == 3
52 fun baz(a, b: Int) do return a + b
56 In a single piece of documentation, each docunit is considered a part of a single module, thus regrouped when
58 Therefore, it is possible (and recommended) to split docunits in small parts if it make the explanation easier.
61 # Some example of grouped docunits
63 # Declare and initialize a variable `a`.
67 # So the value of `a` can be used
71 # even in complex operations
77 Sometime, some blocks of code has to be included in documentation but not considered by `nitunit`.
78 Those blocks are distinguished by their tagged fences (untagged fences or fences tagged `nit` are considered to be docunits).
90 The special fence-tag `nitish` could also be used to indicate pseudo-nit that will be ignored by nitunit but highlighted by nitdoc.
91 Such `nitish` piece of code can be used to enclose examples that cannot compile or that one do not want to be automatically executed.
97 # var a: Int = someting
99 # if a == 1 then something else something-else
102 # Some code to not try to execute automatically
109 The `nitunit` command is used to test Nit files:
113 Groups (directories) can be given to test the documentation of the group and of all its Nit files:
117 Finally, standard markdown documents can be checked with:
121 When testing, the environment variable `NIT_TESTING` is set to `true`.
122 This flag can be used by libraries and program to prevent (or limit) the execution of dangerous pieces of code.
125 # NIT_TESTING is automatically set.
127 # assert "NIT_TESTING".environ == "true"
130 ## Working with `TestSuites`
132 TestSuites are Nit files that define a set of TestCases for a particular module.
134 The test suite must be called `test_` followed by the name of the module to test.
135 So for the module `foo.nit` the test suite will be called `test_foo.nit`.
137 The structure of a test suite is the following:
140 # test suite for module `foo`
142 import foo # can be intrude to test private things
144 # test case for `foo::Foo::baz`
146 var subject = new Foo
147 assert subject.baz(1, 2) == 3
152 Test suite can be executed using the same `nitunit` command:
156 `nitunit` will execute a test for each method named `test_*` in a class named `Test*`
157 so multiple tests can be executed for a single method:
162 var subject = new Foo
163 assert subject.baz(1, 2) == 3
166 var subject = new Foo
167 assert subject.baz(1, -2) == -1
174 Sometimes, it is easier to validate a `TestCase` by comparing its output with a text file containing the expected result.
176 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.
178 The `diff(1)` command is used to perform the comparison.
179 The test is failed if non-zero is returned by `diff`.
182 module test_mod is test_suite
190 Where `test_mod.sav/test_bar.res` contains
196 If no corresponding `.res` file exists, then the output of the TestCase is ignored.
198 ## Configuring TestSuites
200 `TestSuites` also provide methods to configure the test run:
202 `before_test` and `after_test`: methods called before/after each test case.
203 They can be used to factorize repetitive tasks:
208 # Mandatory empty init
210 # Method executed before each test
215 assert subject.baz(1, 2) == 3
218 assert subject.baz(1, -2) == -1
223 When using custom test attributes, an empty `init` must be declared to allow automatic test running.
225 `before_module` and `after_module`: methods called before/after each test suite.
226 They have to be declared at top level:
229 module test_bdd_connector
231 # Testing the bdd_connector
233 # test cases using a server
235 # Method executed before testing the module
237 # start server before all test cases
239 # Method executed after testing the module
241 # stop server after all test cases
245 ## Generating test suites
247 Write test suites for big modules can be a repetitive and boring task...
248 To make it easier, `nitunit` can generate test skeletons for Nit modules:
250 $ nitunit --gen-suite foo.nit
252 This will generate the test suite `test_foo` containing test case stubs for all public
253 methods found in `foo.nit`.
259 Process also imported modules.
261 By default, only the modules indicated on the command line are tested.
263 With the `--full` option, all imported modules (even those in standard) are also precessed.
266 Output name (default is 'nitunit.xml').
268 `nitunit` produces a XML file compatible with JUnit.
271 Working directory (default is 'nitunit.out').
273 In order to execute the tests, nit files are generated then compiled and executed in the giver working directory.
276 nitc compiler to use.
278 By default, nitunit tries to locate the `nitc` program with the environment variable `NITC` or heuristics.
279 The option is used to indicate a specific nitc binary.
282 Does not compile and run tests.
284 ### `-p`, `--pattern`
285 Only run test case with name that match pattern.
287 Examples: `TestFoo`, `TestFoo*`, `TestFoo::test_foo`, `TestFoo::test_foo*`, `test_foo`, `test_foo*`
289 ### `-t`, `--target-file`
290 Specify test suite location.
295 Generate test suite skeleton for a module.
298 Force test generation even if file exists.
300 Any existing test suite will be overwritten.
303 Also generate test case for private methods.
306 Only display the skeleton, do not write any file.
309 # ENVIRONMENT VARIABLES
313 Indicate the specific Nit compiler executable to use. See `--nitc`.
317 The environment variable `NIT_TESTING` is set to `true` during the execution of program tests.
318 Some libraries of programs can use it to produce specific reproducible results; or just to exit their executions.
320 Unit-tests may unset this environment variable to retrieve the original behavior of such piece of software.
324 In order to maximize reproducibility, `SRAND` is set to 0.
325 This make the pseudo-random generator no random at all.
326 See `Sys::srand` for details.
328 To retrieve the randomness, unit-tests may unset this environment variable then call `srand`.
332 Parallel executions can cause some race collisions on named resources (e.g. DB table names).
333 To solve this issue, `NIT_TESTING_ID` is initialized with a distinct integer identifier that can be used to give unique names to resources.
335 Note: `rand` is not a recommended way to get a distinct identifier because its randomness is disabled by default. See `SRAND`.
340 The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>