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) do return a + b
44 `nitunit` is used to test Nit files:
48 ## Working with `TestSuites`
50 TestSuites are Nit files that define a set of TestCase for a particular module.
52 The test suite module must be declared using the `test_suite` annotation.
53 The structure of a test suite is the following:
55 # test suite for module `foo`
56 module test_foo is test_suite
58 import test_suite # import the `TestSuite` class and the `test_suite` annotation
59 import foo # can be intrude to test private things
64 # test case for `foo::Foo::baz`
67 assert subject.baz(1, 2) == 3
71 Test suite can be executed using the same `nitunit` command:
75 To be started automatically with nitunit, the module must be called `test_`
76 followed by the name of the module to test.
77 So for the module `foo.nit` the test suite will be called `test_foo.nit`.
78 Otherwise, you can use the `-t` option to specify the test suite module name:
80 $ nitunit foo.nit -t my_test_suite.nit
82 `nitunit` will execute a test for each method named `test_*` in a class named `Test*`
83 so multiple tests can be executed for a single method:
90 assert subject.baz(1, 2) == 3
95 assert subject.baz(1, -2) == -1
99 `TestSuites` also provide methods to configure the test run:
101 `before_test` and `after_test`: methods called before/after each test case.
102 They can be used to factorize repetitive tasks:
107 var subject: Foo is noinit
109 # Method executed before each test
110 redef fun before_test do
115 assert subject.baz(1, 2) == 3
119 assert subject.baz(1, -2) == -1
123 When using custom test attributes, a empty init must be declared to allow automatic test running.
125 `before_module` and `after_module`: methods called before/after each test suite.
126 They have to be declared at top level:
128 module test_bdd_connector
133 # Testing the bdd_connector
136 # test cases using a server
139 # Method executed before testing the module
140 redef fun before_module do
141 # start server before all test cases
144 # Method executed after testing the module
145 redef fun after_module do
146 # stop server after all test cases
149 ## Generating test suites
151 Write test suites for big modules can be a pepetitive and boring task...
152 To make it easier, `nitunit` can generate test skeletons for Nit modules:
154 $ nitunit --gen-suite foo.nit
156 This will generate the test suite `test_foo` containing test case stubs for all public
157 methods found in `foo.nit`.
159 Useful options with `--gen-suite`:
161 * `--private`: also generate tests for protected and private methods
162 * `--force`: force generation of the skeleton (existing test suite will be overwritten)