share/man/nitunit.md

   1 # NAME
   2
   3 nitunit - executes the unit tests from Nit source files.
   4
   5 # SYNOPSIS
   6
   7 nitunit [*options*] FILE...
   8
   9 # DESCRIPTION
  10
  11 Unit testing in Nit can be achieved in two ways:
  12
  13 * using `DocUnits` in code comments or in markdown files
  14 * using `TestSuites` with test unit files
  15
  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.
  20
  21 `DocUnits` can also be used in any markdown files.
  22
  23 `TestSuites` are test files coupled to a tested module.
  24 They contain a list of test methods called TestCase.
  25
  26 ## Working with `DocUnits`
  27
  28 DocUnits are blocks of executable code placed in comments of modules, classes and properties.
  29 The execution can be verified using `assert`.
  30
  31 Example with a class:
  32
  33 ~~~
  34 module foo
  35 #    var foo = new Foo
  36 #    assert foo.bar == 10
  37 class Foo
  38     var bar = 10
  39 end
  40 ~~~
  41
  42 Everything used in the test must be declared.
  43 To test a method you have to instantiate its class:
  44
  45 ~~~
  46 module foo
  47 #    var foo = new Foo
  48 #    assert foo.bar == 10
  49 class Foo
  50     #    var foo = new Foo
  51     #    assert foo.baz(1, 2) == 3
  52     fun baz(a, b: Int) do return a + b
  53 end
  54 ~~~
  55
  56 In a single piece of documentation, each docunit is considered a part of a single module, thus regrouped when
  57 tested.
  58 Therefore, it is possible (and recommended) to split docunits in small parts if it make the explanation easier.
  59
  60 ~~~~
  61 # Some example of grouped docunits
  62 #
  63 # Declare and initialize a variable `a`.
  64 #
  65 #     var a = 1
  66 #
  67 # So the value of `a` can be used
  68 #
  69 #     assert a == 1
  70 #
  71 # even in complex operations
  72 #
  73 #     assert a + 1 == 2
  74 fun foo do end
  75 ~~~~
  76
  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).
  79
  80 ~~~~
  81 # Some ASCII drawing
  82 #
  83 # ~~~~raw
  84 #   @<
  85 # <__)
  86 # ~~~~
  87 fun foo do end
  88 ~~~~
  89
  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.
  92
  93 ~~~~
  94 # Some pseudo-nit
  95 #
  96 # ~~~~nitish
  97 # var a: Int = someting
  98 # # ...
  99 # if a == 1 then something else something-else
 100 # ~~~~
 101 #
 102 # Some code to not try to execute automatically
 103 #
 104 # ~~~~nitish
 105 # system("rm -rf /")
 106 # ~~~~
 107 ~~~~
 108
 109 The `nitunit` command is used to test Nit files:
 110
 111     $ nitunit foo.nit
 112
 113 Groups (directories) can be given to test the documentation of the group and of all its Nit files:
 114
 115     $ nitunit lib/foo
 116
 117 Finally, standard markdown documents can be checked with:
 118
 119     $ nitunit foo.md
 120
 121 ## Working with `TestSuites`
 122
 123 TestSuites are Nit files that define a set of TestCases for a particular module.
 124
 125 The test suite must be called `test_` followed by the name of the module to test.
 126 So for the module `foo.nit` the test suite will be called `test_foo.nit`.
 127
 128 The structure of a test suite is the following:
 129
 130 ~~~~
 131 # test suite for module `foo`
 132 module test_foo
 133 import foo # can be intrude to test private things
 134 class TestFoo
 135     # test case for `foo::Foo::baz`
 136     fun test_baz do
 137         var subject = new Foo
 138         assert subject.baz(1, 2) == 3
 139     end
 140 end
 141 ~~~~
 142
 143 Test suite can be executed using the same `nitunit` command:
 144
 145     $ nitunit foo.nit
 146
 147 `nitunit` will execute a test for each method named `test_*` in a class named `Test*`
 148 so multiple tests can be executed for a single method:
 149
 150 ~~~~
 151 class TestFoo
 152     fun test_baz_1 do
 153         var subject = new Foo
 154         assert subject.baz(1, 2) == 3
 155     end
 156     fun test_baz_2 do
 157         var subject = new Foo
 158         assert subject.baz(1, -2) == -1
 159     end
 160 end
 161 ~~~~
 162
 163 `TestSuites` also provide methods to configure the test run:
 164
 165 `before_test` and `after_test`: methods called before/after each test case.
 166 They can be used to factorize repetitive tasks:
 167
 168 ~~~~
 169 class TestFoo
 170     var subject: Foo
 171     # Mandatory empty init
 172     init do end
 173     # Method executed before each test
 174     fun before_test do
 175         subject = new Foo
 176     end
 177     fun test_baz_1 do
 178         assert subject.baz(1, 2) == 3
 179     end
 180     fun test_baz_2 do
 181         assert subject.baz(1, -2) == -1
 182     end
 183 end
 184 ~~~~
 185
 186 When using custom test attributes, an empty `init` must be declared to allow automatic test running.
 187
 188 `before_module` and `after_module`: methods called before/after each test suite.
 189 They have to be declared at top level:
 190
 191 ~~~~
 192 module test_bdd_connector
 193 import bdd_connector
 194 # Testing the bdd_connector
 195 class TestConnector
 196     # test cases using a server
 197 end
 198 # Method executed before testing the module
 199 fun before_module do
 200     # start server before all test cases
 201 end
 202 # Method executed after testing the module
 203 fun after_module do
 204     # stop server after all test cases
 205 end
 206 ~~~~
 207
 208 ## Generating test suites
 209
 210 Write test suites for big modules can be a repetitive and boring task...
 211 To make it easier, `nitunit` can generate test skeletons for Nit modules:
 212
 213     $ nitunit --gen-suite foo.nit
 214
 215 This will generate the test suite `test_foo` containing test case stubs for all public
 216 methods found in `foo.nit`.
 217
 218
 219 # OPTIONS
 220
 221 ### `--full`
 222 Process also imported modules.
 223
 224 By default, only the modules indicated on the command line are tested.
 225
 226 With the `--full` option, all imported modules (even those in standard) are also precessed.
 227
 228 ### `-o`, `--output`
 229 Output name (default is 'nitunit.xml').
 230
 231 ### `nitunit` produces a XML file comatible with JUnit.
 232
 233 ### `--dir`
 234 Working directory (default is '.nitunit').
 235
 236 In order to execute the tests, nit files are generated then compiled and executed in the giver working directory.
 237
 238 ### `--no-act`
 239 Does not compile and run tests.
 240
 241 ### `-p`, `--pattern`
 242 Only run test case with name that match pattern.
 243
 244 Examples: `TestFoo`, `TestFoo*`, `TestFoo::test_foo`, `TestFoo::test_foo*`, `test_foo`, `test_foo*`
 245
 246 ### `-t`, `--target-file`
 247 Specify test suite location.
 248
 249 ## SUITE GENERATION
 250
 251 ### `--gen-suite`
 252 Generate test suite skeleton for a module.
 253
 254 ### `-f`, `--force`
 255 Force test generation even if file exists.
 256
 257 Any existing test suite will be overwritten.
 258
 259 ### `--private`
 260 Also generate test case for private methods.
 261
 262 ### `--only-show`
 263 Only display the skeleton, do not write any file.
 264
 265 # SEE ALSO
 266
 267 The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>