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 With DocUnits, executable code can be 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 The `nitunit` command is used to test Nit files:
  53
  54     $ nitunit foo.nit
  55
  56 ## Working with `TestSuites`
  57
  58 TestSuites are Nit files that define a set of TestCases for a particular module.
  59
  60 The test suite must be called `test_` followed by the name of the module to test.
  61 So for the module `foo.nit` the test suite will be called `test_foo.nit`.
  62
  63 The structure of a test suite is the following:
  64
  65     # test suite for module `foo`
  66     module test_foo
  67     import foo # can be intrude to test private things
  68     class TestFoo
  69         # test case for `foo::Foo::baz`
  70         fun test_baz do
  71             var subject = new Foo
  72             assert subject.baz(1, 2) == 3
  73         end
  74     end
  75
  76 Test suite can be executed using the same `nitunit` command:
  77
  78     $ nitunit foo.nit
  79
  80 `nitunit` will execute a test for each method named `test_*` in a class named `Test*`
  81 so multiple tests can be executed for a single method:
  82
  83     class TestFoo
  84         fun test_baz_1 do
  85             var subject = new Foo
  86             assert subject.baz(1, 2) == 3
  87         end
  88         fun test_baz_2 do
  89             var subject = new Foo
  90             assert subject.baz(1, -2) == -1
  91         end
  92     end
  93
  94 `TestSuites` also provide methods to configure the test run:
  95
  96 `before_test` and `after_test`: methods called before/after each test case.
  97 They can be used to factorize repetitive tasks:
  98
  99     class TestFoo
 100         var subject: Foo
 101         # Mandatory empty init
 102         init do end
 103         # Method executed before each test
 104         fun before_test do
 105             subject = new Foo
 106         end
 107         fun test_baz_1 do
 108             assert subject.baz(1, 2) == 3
 109         end
 110         fun test_baz_2 do
 111             assert subject.baz(1, -2) == -1
 112         end
 113     end
 114
 115 When using custom test attributes, an empty `init` must be declared to allow automatic test running.
 116
 117 `before_module` and `after_module`: methods called before/after each test suite.
 118 They have to be declared at top level:
 119
 120     module test_bdd_connector
 121     import bdd_connector
 122     # Testing the bdd_connector
 123     class TestConnector
 124         # test cases using a server
 125     end
 126     # Method executed before testing the module
 127     fun before_module do
 128         # start server before all test cases
 129     end
 130     # Method executed after testing the module
 131     fun after_module do
 132         # stop server after all test cases
 133     end
 134
 135 ## Generating test suites
 136
 137  Write test suites for big modules can be a repetitive and boring task...
 138  To make it easier, `nitunit` can generate test skeletons for Nit modules:
 139
 140     $ nitunit --gen-suite foo.nit
 141
 142  This will generate the test suite `test_foo` containing test case stubs for all public
 143  methods found in `foo.nit`.
 144
 145
 146 # OPTIONS
 147
 148 `--full`
 149 :   Process also imported modules.
 150
 151     By default, only the modules indicated on the command line are tested.
 152
 153     With the `--full` option, all imported modules (even those in standard) are also precessed.
 154
 155 `-o`, `--output`
 156 :   Output name (default is 'nitunit.xml')
 157
 158     `nitunit` produces a XML file comatible with JUnit.
 159
 160 `--dir`
 161 :   Working directory (default is '.nitunit')
 162
 163     In order to execute the tests, nit files are generated then compiled and executed in the giver working directory.
 164
 165 `--no-act`
 166 :   Does not compile and run tests.
 167
 168 `-p`, `--pattern`
 169 :   Only run test case with name that match pattern. Examples: `TestFoo`, `TestFoo*`, `TestFoo::test_foo`, `TestFoo::test_foo*`, `test_foo`, `test_foo*`
 170
 171 `-t`, `--target-file`
 172 :   Specify test suite location.
 173
 174 ## SUITE GENERATION
 175
 176 `--gen-suite`
 177 :   Generate test suite skeleton for a module
 178
 179 `-f`, `--force`
 180 :   Force test generation even if file exists.
 181
 182     Any existing test suite will be overwritten.
 183
 184 `--private`
 185 :   Also generate test case for private methods.
 186
 187 `--only-show`
 188 :   Only display the skeleton, do not write any file.
 189
 190 # SEE ALSO
 191
 192 The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>