1 # Test unit generation and execution for Nit.
3 In Nit, unit testing can be achieved in two ways:
5 * using `DocUnits` in code comments
6 * using `TestSuites` with test unit files
8 DocUnits are executable pieces of code found in the documentation of modules,
9 classes and properties.
10 They are used for documentation purpose, they should be kept simple and illustrative.
11 More advanced unit testing can be done using TestSuites.
13 TestSuites are test files coupled to a tested module.
14 They contain a list of test methods called TestCase.
16 ## Working with `DocUnits`
18 With DocUnits, executable code can be placed in comments of modules, classes and properties.
19 The execution can be verified using `assert`
26 # assert foo.bar == 10
31 Everything used in the test must be declared.
32 To test a method you have to instanciate its class:
37 # assert foo.bar == 10
40 # assert foo.baz(1, 2) == 3
41 fun baz(a, b: Int): Int do return a + b
44 `nitunit` is used to test Nit files:
50 ## Working with `TestSuites`
52 TestSuites are Nit files that define a set of TestCase for a particular module.
54 The test suite module must be declared using the `test` annotation.
55 The structure of a test suite is the following:
58 # test suite for module `foo`
59 module test_foo is test
61 import foo # can be intrude to test private things
66 # test case for `foo::Foo::baz`
69 assert subject.baz(1, 2) == 3
74 Test suite can be executed using the same `nitunit` command:
80 To be started automatically with nitunit, the module must be called `test_`
81 followed by the name of the module to test.
82 So for the module `foo.nit` the test suite will be called `test_foo.nit`.
83 Otherwise, you can use the `-t` option to specify the test suite module name:
86 $ nitunit foo.nit -t my_test_suite.nit
89 `nitunit` will execute a test for each method annotated with `test` in a class also annotated with `test`
90 so multiple tests can be executed for a single method:
98 assert subject.baz(1, 2) == 3
102 var subject = new Foo
103 assert subject.baz(1, -2) == -1
108 `TestSuites` also provide methods to configure the test run:
110 `before` and `after` annotations can be added to methods that must be called before/after each test case.
111 They can be used to factorize repetitive tasks:
117 var subject: Foo is noinit
119 # Method executed before each test
120 fun set_up is before do
125 assert subject.baz(1, 2) == 3
129 assert subject.baz(1, -2) == -1
134 When using custom test attributes, a empty init must be declared to allow automatic test running.
136 At class level, `before_all` and `after_all` annotations can be set on methods that must be called before/after all the test cases in the class:
142 var subject: Foo is noinit
144 # Method executed before all tests in the class
145 fun set_up is before_all do
150 assert subject.baz(1, 2) == 3
154 assert subject.baz(1, -2) == -1
159 `before_all` and `after_all` annotations can also be set on methods that must be called before/after each test suite when declared at top level:
162 module test_bdd_connector
166 # Testing the bdd_connector
169 # test cases using a server
172 # Method executed before testing the module
173 fun setup_db is before_all do
174 # start server before all test cases
177 # Method executed after testing the module
178 fun teardown_db is after_all do
179 # stop server after all test cases
183 When dealing with multiple test suites, niunit allows you to import other test suites to factorize your tests:
186 module test_bdd_users
188 import test_bdd_connector
190 # Testing the user table
193 # test cases using the db server from `test_bdd_connector`
196 fun setup_table is before_all do
200 fun teardown_table is after_all do
205 Methods with `before*` and `after*` annotations are linearized and called in different ways.
207 * `before*` methods are called from the least specific to the most specific
208 * `after*` methods are called from the most specific to the least specific
210 In the previous example, the execution order would be:
212 1. `test_bdd_connector::setup_db`
213 2. `test_bdd_users::setup_table`
214 3. `all test cases from test_bdd_users`
215 4. `test_bdd_users::teardown_table`
216 5. `test_bdd_connector::teardown_db`
218 ## Generating test suites
220 Write test suites for big modules can be a pepetitive and boring task...
221 To make it easier, `nitunit` can generate test skeletons for Nit modules:
224 $ nitunit --gen-suite foo.nit
227 This will generate the test suite `test_foo` containing test case stubs for all public
228 methods found in `foo.nit`.
230 Useful options with `--gen-suite`:
232 * `--private`: also generate tests for protected and private methods
233 * `--force`: force generation of the skeleton (existing test suite will be overwritten)