Changed layout to match boost

doc/getting_started.qbk

@@ -0,0 +1,100 @@
+[/
+ / Copyright (c) 2014 Mathieu Champlon
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section Getting Started]
+[import example/getting_started.cpp]
+
+This section introduces most of the library features in a series of use cases built on the example from the [link turtle.motivation motivation] section.
+
+For all the code examples the following is assumed :
+
+[prerequisite]
+
+[section Create, expect, trigger, verify]
+
+A simple unit test with mock objects usually splits into several phases as illustrated by :
+
+[phases]
+
+Triggering the object under test in turn calls methods on the mock objects, and any unexpected call raises an error.
+
+Mock objects are automatically verified during their destruction and an error is signalled if any unfulfilled expectation remains.
+
+More sophisticated tests sometimes require more complex use cases and in particular might need to verify or reset mock objects.
+
+Here is an example highlighting the different possibilities :
+
+[verify_reset]
+
+Note that all verifications upon destruction will be disabled if the mock objects are destroyed in the context of an exception being raised.
+
+[endsect]
+
+[section Expectation selection algorithm]
+
+A method can be configured with several expectations, for instance :
+
+[expectations]
+
+Each method call is then handled by processing the expectations in the order they have been defined :
+
+# looking for a match with valid parameter constraints evaluated from left to right
+# checking that the invocation count for this match is not exhausted
+
+An error is raised if none can be found.
+
+By default the relative order of the calls does not matter. It can however be enforced :
+
+[sequence]
+
+Therefore an error will be issued if the second expectation is matched before the first one has been exhausted.
+
+An expectation can be part of several sequences :
+
+[several_sequences]
+
+[endsect]
+
+[section Error diagnostic]
+
+During the execution of a test case, an error can happen for one of the following reasons :
+
+* unexpected call when no match can be found for the given arguments (typically logs an error and throws an exception)
+* sequence failure when an enforced call sequence has not been followed (typically logs an error and throws an exception)
+* verification failure if a remaining match has not been fulfilled upon manual verification (typically logs an error)
+* untriggered expectation if a remaining match has not been fulfilled when destroying the mock object (typically logs an error)
+* missing action if a method supposed to return something else than void has not been configured properly (typically logs an error and throws an exception)
+
+The exact type of the exception thrown depends on the [link turtle.customization.test_framework_integration test framework integration] used.
+
+An error log typically looks like :
+
+ unknown location(0): error in "zero_plus_zero_is_zero": unexpected call: v.mock_view::display( 0 )
+ v once().with( 1 )
+ v once().with( 2 )
+ . once().with( 3 )
+
+On the first line is the description of what happened : here the display method of object v of class mock_view has been called with an actual value of 0.
+
+The following lines list the set expectations with the check (the v character) meaning the expectation has been exhausted.
+It therefore means that the two first expectations have been fulfilled by two calls, and then instead of 3 in the third call 0 has been erroneously passed on to the mock object.
+
+Another common error looks like :
+
+ src/tests/turtle_test/Tutorial.cpp(73): error in "zero_plus_zero_is_zero": untriggered expectation: v.mock_view::display
+ v once().with( 1 )
+ v once().with( 2 )
+ . once().with( 3 )
+
+The first line tells that a set expectation has not been fulfilled. The file and line number give the location where the corresponding expectation has been configured.
+
+The following lines once again list the set expectations.
+It means the two first calls correctly passed the expected values to the mock object, but then no third call happened.
+
+[endsect]
+
+[endsect]