share/man/nitunit.md

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