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