5 nitunit - executes the unit tests from Nit source files.
9 nitunit [*options*] FILE...
13 Unit testing in Nit can be achieved in two ways:
15 * using `DocUnits` in code comments or in markdown files
16 * using `TestSuites` with test unit files
18 `DocUnits` are executable pieces of code found in the documentation of groups, modules,
19 classes and properties.
20 They are used for documentation purpose, they should be kept simple and illustrative.
21 More advanced unit testing can be done using TestSuites.
23 `DocUnits` can also be used in any markdown files.
25 `TestSuites` are test files coupled to a tested module.
26 They contain a list of test methods called TestCase.
28 ## Working with `DocUnits`
30 DocUnits are blocks of executable code placed in comments of modules, classes and properties.
31 The execution can be verified using `assert`.
37 # assert foo.bar == 10
42 Everything used in the test must be declared.
43 To test a method you have to instantiate its class:
47 # assert foo.bar == 10
50 # assert foo.baz(1, 2) == 3
51 fun baz(a, b: Int) do return a + b
54 In a single piece of documentation, each docunit is considered a part of a single module, thus regrouped when
56 Therefore, it is possible (and recommended) to split docunits in small parts if it make the explanation easier.
59 # Some example of grouped docunits
61 # Declare and initialize a variable `a`.
65 # So the value of `a` can be used
69 # even in complex operations
75 Sometime, some blocks of code has to be included in documentation but not considered by `nitunit`.
76 Those blocks are distinguished by their tagged fences (untagged fences or fences tagged `nit` are considered to be docunits).
88 The special fence-tag `nitish` could also be used to indicate pseudo-nit that will be ignored by nitunit but highlighted by nitdoc.
89 Such `nitish` piece of code can be used to enclose examples that cannot compile or that one do not want to be automatically executed.
95 # var a: Int = someting
97 # if a == 1 then something else something-else
100 # Some code to not try to execute automatically
107 The `nitunit` command is used to test Nit files:
111 Groups (directories) can be given to test the documentation of the group and of all its Nit files:
115 Finally, standard markdown documents can be checked with:
119 ## Working with `TestSuites`
121 TestSuites are Nit files that define a set of TestCases for a particular module.
123 The test suite must be called `test_` followed by the name of the module to test.
124 So for the module `foo.nit` the test suite will be called `test_foo.nit`.
126 The structure of a test suite is the following:
128 # test suite for module `foo`
130 import foo # can be intrude to test private things
132 # test case for `foo::Foo::baz`
134 var subject = new Foo
135 assert subject.baz(1, 2) == 3
139 Test suite can be executed using the same `nitunit` command:
143 `nitunit` will execute a test for each method named `test_*` in a class named `Test*`
144 so multiple tests can be executed for a single method:
148 var subject = new Foo
149 assert subject.baz(1, 2) == 3
152 var subject = new Foo
153 assert subject.baz(1, -2) == -1
157 `TestSuites` also provide methods to configure the test run:
159 `before_test` and `after_test`: methods called before/after each test case.
160 They can be used to factorize repetitive tasks:
164 # Mandatory empty init
166 # Method executed before each test
171 assert subject.baz(1, 2) == 3
174 assert subject.baz(1, -2) == -1
178 When using custom test attributes, an empty `init` must be declared to allow automatic test running.
180 `before_module` and `after_module`: methods called before/after each test suite.
181 They have to be declared at top level:
183 module test_bdd_connector
185 # Testing the bdd_connector
187 # test cases using a server
189 # Method executed before testing the module
191 # start server before all test cases
193 # Method executed after testing the module
195 # stop server after all test cases
198 ## Generating test suites
200 Write test suites for big modules can be a repetitive and boring task...
201 To make it easier, `nitunit` can generate test skeletons for Nit modules:
203 $ nitunit --gen-suite foo.nit
205 This will generate the test suite `test_foo` containing test case stubs for all public
206 methods found in `foo.nit`.
212 : Process also imported modules.
214 By default, only the modules indicated on the command line are tested.
216 With the `--full` option, all imported modules (even those in standard) are also precessed.
219 : Output name (default is 'nitunit.xml')
221 `nitunit` produces a XML file comatible with JUnit.
224 : Working directory (default is '.nitunit')
226 In order to execute the tests, nit files are generated then compiled and executed in the giver working directory.
229 : Does not compile and run tests.
232 : Only run test case with name that match pattern. Examples: `TestFoo`, `TestFoo*`, `TestFoo::test_foo`, `TestFoo::test_foo*`, `test_foo`, `test_foo*`
234 `-t`, `--target-file`
235 : Specify test suite location.
240 : Generate test suite skeleton for a module
243 : Force test generation even if file exists.
245 Any existing test suite will be overwritten.
248 : Also generate test case for private methods.
251 : Only display the skeleton, do not write any file.
255 The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>