From: Alexandre Terrasa <alexandre@moz-code.org>
Date: Sat, 2 Aug 2014 17:48:47 +0000 (-0400)
Subject: nitunit: add README for group `testing` and redirect from nitunit doc.
X-Git-Tag: v0.6.9~61^2~1
X-Git-Url: http://nitlanguage.org

nitunit: add README for group `testing` and redirect from nitunit doc.

Signed-off-by: Alexandre Terrasa <alexandre@moz-code.org>
---

diff --git a/src/nitunit.nit b/src/nitunit.nit
index 7eb90bb..0a8973d 100644
--- a/src/nitunit.nit
+++ b/src/nitunit.nit
@@ -12,7 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Program to extract and execute unit tests from nit source files
+# Testing tool.
+# see `testing/README`
 module nitunit
 
 import testing
diff --git a/src/testing/README b/src/testing/README
new file mode 100644
index 0000000..772ec38
--- /dev/null
+++ b/src/testing/README
@@ -0,0 +1,162 @@
+# Test unit generation and execution for Nit.
+
+In Nit, unit testing can be achieved in two ways:
+
+* using `DocUnits` in code comments
+* using `TestSuites` with test unit files
+
+DocUnits are executable pieces of code found in the documentation of modules,
+classes and properties.
+They are used for documentation purpose, they should be kept simple and illustrative.
+More advanced unit testing can be done using TestSuites.
+
+TestSuites are test files coupled to a tested module.
+They contain a list of test methods called TestCase.
+
+## Working with `DocUnits`
+
+With DocUnits, executable code can be placed in comments of modules, classes and properties.
+The execution can be verified using `assert`
+
+Example with a class:
+
+	module foo
+
+	#    var foo = new Foo
+	#    assert foo.bar == 10
+	class Foo
+		var bar = 10
+	end
+
+Everything used in the test must be declared.
+To test a method you have to instanciate its class:
+
+	module foo
+
+	#    var foo = new Foo
+	#    assert foo.bar == 10
+	class Foo
+		#    var foo = new Foo
+		#    assert foo.baz(1, 2) == 3
+		fun baz(a, b: Int) do return a + b
+	end
+
+`nitunit` is used to test Nit files:
+
+	$ nitunit foo.nit
+
+## Working with `TestSuites`
+
+TestSuites are Nit files that define a set of TestCase for a particular module.
+
+The test suite module must be declared using the `test_suite` annotation.
+The structure of a test suite is the following:
+
+	# test suite for module `foo`
+	module test_foo is test_suite
+
+	import test_suite # import the `TestSuite` class and the `test_suite` annotation
+	import foo # can be intrude to test private things
+
+	class TestFoo
+		super TestSuite
+
+		# test case for `foo::Foo::baz`
+		fun test_baz do
+			var subject = new Foo
+			assert subject.baz(1, 2) == 3
+		end
+	end
+
+Test suite can be executed using the same `nitunit` command:
+
+	$ nitunit foo.nit
+
+To be started automatically with nitunit, the module must be called `test_`
+followed by the name of the module to test.
+So for the module `foo.nit` the test suite will be called `test_foo.nit`.
+Otherwise, you can use the `-t` option to specify the test suite module name:
+
+	$ nitunit foo.nit -t my_test_suite.nit
+
+`nitunit` will execute a test for each method named `test_*` in a class named `Test*`
+so multiple tests can be executed for a single method:
+
+	class TestFoo
+		super TestSuite
+
+		fun test_baz_1 do
+			var subject = new Foo
+			assert subject.baz(1, 2) == 3
+		end
+
+		fun test_baz_2 do
+			var subject = new Foo
+			assert subject.baz(1, -2) == -1
+		end
+	end
+
+`TestSuites` also provide methods to configure the test run:
+
+`before_test` and `after_test`: methods called before/after each test case.
+They can be used to factorize repetitive tasks:
+
+	class TestFoo
+		super TestSuite
+
+		var subject: Foo is noinit
+
+		# Method executed before each test
+		redef fun before_test do
+			subject = new Foo
+		end
+
+		fun test_baz_1 do
+			assert subject.baz(1, 2) == 3
+		end
+
+		fun test_baz_2 do
+			assert subject.baz(1, -2) == -1
+		end
+	end
+
+When using custom test attributes, a empty init must be declared to allow automatic test running.
+
+`before_module` and `after_module`: methods called before/after each test suite.
+They have to be declared at top level:
+
+	module test_bdd_connector
+
+	import test_suite
+	import bdd_connector
+
+	# Testing the bdd_connector
+	class TestConnector
+		super TestSuite
+		# test cases using a server
+	end
+
+	# Method executed before testing the module
+	redef fun before_module do
+		# start server before all test cases
+	end
+
+	# Method executed after testing the module
+	redef fun after_module do
+		# stop server after all test cases
+	end
+
+## Generating test suites
+
+Write test suites for big modules can be a pepetitive and boring task...
+To make it easier, `nitunit` can generate test skeletons for Nit modules:
+
+	$ nitunit --gen-suite foo.nit
+
+This will generate the test suite `test_foo` containing test case stubs for all public
+methods found in `foo.nit`.
+
+Useful options with `--gen-suite`:
+
+* `--private`: also generate tests for protected and private methods
+* `--force`: force generation of the skeleton (existing test suite will be overwritten)