
p. 

==<div style="counter-reset: h1 7">==

h1(#sctunit_test-driven_statechart_development_with_sctunit). Test-driven statechart development with SCTUnit

h2(#sctunit_brief_introduction_to_test-driven_development). Brief introduction to test-driven development

In "test-driven development":https://en.wikipedia.org/wiki/Test-driven_development, before writing any code the developer creates a _unit test_ that checks the to-be-established implementation for correctness. Only after that, the developer codes the implementation and executes the test. If the test fails, the developer has to fix the implementation – perhaps repeatedly – until the test succeeds.

Tests are not written for the complete software product in advance, but rather on a per-feature basis. That is, the developer writes tests only for the one single feature he is going to implement next. Having successfully finished that implementation, the developer should _refactor_ his code and his tests. The most recent additions might have opened opportunities to restructure one or the other, thus reducing complexity and/or adding readability. "Refactoring":https://en.wikipedia.org/wiki/Code_refactoring must never change the semantics of the code. To ensure that, tests come in handy and should be run after each refactoring step.




h2(#sctunit_test-driven_statechart_modelling). Test-driven statechart modelling

In "model-driven software development (MDSD)":https://en.wikipedia.org/wiki/Model-driven_software_development, specific parts of the software are created by a code generator instead of being written manually. This also pertains to code "generated from statechart models":../user-guide/code_generation_intro.html#codegen_generating_state_machine_code.

The nice thing about generated code is that we can safely assume it to be correct – at least as long as the code generator developers have tested their product thoroughly enough. However, what about the model? While the generated code might be correct, this won't help at all if the underlying model is broken in the first place.

SCTUnit is a scripting and testing framework for writing unit tests for statechart models. You can validate the behaviour of your statechart by running these tests. Each test, written in the SCTUnit language, consists of a well-defined sequence of instructions. When running a test, these instructions are applied to a state machine under control and possibly changes that state machine in a specific way. You put down the expected effects of these changes as _assertions_. An assertion is used to check whether a specific condition is fulfilled, for example certain states being active or not, variables having specific values, operations having been executed, etc. SCTUnit allows test-driven development of statechart models on the semantic level.

The subsequent sections will first "introduce SCTUnit by example":#sctunit_sctunit_by_example and then explain "the SCTUnit language in full":#sctunit_the_sctunit_language.




h2(#sctunit_sctunit_by_example). SCTUnit by example

This section introduces SCTUnit by a simple statechart example that models a light switch. We will develop this statechart step by step using a test-driven approach. That is, for each single development step, we will first write a test, then change our statechart model, then run all the tests we created so far until they succeed. After that, we will proceed with the next development step.



h3(#sctunit_light_switch_requirements). Light switch requirements

Before implementing any tests or models, let's write down the requirements for our light switch statechart model:
# When the state machine starts, the model is in the *Off* state (initially the light is off).
# If the *Off* state is active and the _operate_ event occurs (a user _operates_ the light switch), the state machine changes from the *Off* state to the *On* state (the light is switched on).
# If the *On* state is active and the _operate_ event occurs (a user _operates_ the light switch), the state machine changes from the *On* state to the *Off* state (the light is switched off).



h3(#sctunit_specifying_the_initial_behaviour_as_a_test). Specifying the initial behaviour as a test

Now we need an Eclipse project to host our statechart model. So let's create one, naming it _light_switch_. Within the project, we create two folders, _model_ and _test_, for – you guessed it – the model and the tests, respectively.

In the _test_ directory, proceed as follows to create a SCTUnit test file:
# In the _project explorer_ view, right-click on the _test_ folder. The context menu opens.
# In the context menu, select _New → Other…_. The _New_ wizard opens.
# In the wizard, select _YAKINDU SCT → SCTUnit test case_.
# Click _Next >_. The wizard switches to the _New SCTUnit Test Class_ page.
# In the _Filename_ text field, specify the name of the file to contain the SCTUnit tests, say, _light_switch.sctunit_. The filename extension must always be _.sctunit_.
# Click _Finish_.
# If a dialog appears asking whether you want to add the Xtext nature to the project, please click _Yes_.

As a result, the empty file _light_switch.sctunit_ is created in the _test_ folder and is opened in an editor.

In the spirit of test-driven development, create a test for the light switch model's initial behaviour by writing the following in the _light_switch.sctunit_ file:

bc.. 
testclass light_switch_tests for statechart light_switch {

    @Test
    operation isStateOffActiveAfterInit () {
        enter
        assert active (light_switch.main_region.Off)
    }

}

p. Let's walk through this example line by line and see what all of this means.

* @testclass light_switch_tests for statechart light_switch {@
** The keyword @testclass@ introduces a test class, a collection of tests. In this example, it is named _light_switch_tests_.
** A test class always refers to a statechart that is under control and is to be tested. This relationship is established by the _for statechart_ clause. The keywords @for statechart@ are followed by the name of the statechart, here: _light_switch_. However, since there is no _light_switch_ statechart yet, an error marker is attached to the statechart name, as shown in the following screenshot:<br/>!images/sctunit_light_switch_010_initial_test.png(Initial test)!
** The body of the test class is bracketed in braces, i.e., between @{@ and @}@.
* <code>@Test</code><br/><code>operation isStateOffActiveAfterInit () {</code>
** Each test is an _operation_ that is annotated by <code>@Test</code>. This example defines the operation _isStateOffActiveAfterInit_. It has no parameters, which is indicated by <code>()</code>. As we will see later, an operation does not necessarily have to be a test, but can be a mere subroutine. Such operations can have parameters. The operation's body is bracketed in braces.
* @enter@
** The _enter_ statement initializes and starts the state machine; it "enters" it. As a consequence, the state machine activates the state that is pointed to by the initial state.
* @assert active (light_switch.main_region.Off)@
** The _assert_ statement expects that a specified condition is fulfilled. Using the built-in _active_ function, our example's assertion expects that the state *Off* is active. The state is addressed in a fully-qualified manner, i.e., _statechart_._region_._state_. However, since we don't have a statechart model yet and less than ever any state, the *Off* state in the assertion is flagged as an error.



h3(#sctunit_implementing_a_minimal_light_switch_model). Implementing a minimal light switch model

Since the test has error markers, we can say that it fails even without being run. So let's fix that with minimal effort and create a model that is called _light_switch_ and has a state *Off*. Also, change the annotation @EventDriven@ to @CycleBased(200)@. Figure "&quot;First step of creating a light switch model&quot;":#sctunit_fig_first_step_of_creating_a_light_switch_model shows the resulting model.

p(#sctunit_fig_first_step_of_creating_a_light_switch_model). 

!images/sctunit_light_switch_020_first_step.png(First step of creating a light switch model)!

p=. First step of creating a light switch model



h3(#sctunit_running_the_test). Running the test

Figure "&quot;First step of creating a light switch model&quot;":#sctunit_fig_first_step_of_creating_a_light_switch_model also shows that the error markers of the test class have been cleared, because our minimal statechart model has the name that is specified in the test and it also contains the *Off* state.

Now we can execute the test class. In order to do so, proceed as follows:
* Right-click on the _light_switch.sctunit_ file in the _test_ directory. The context menu opens.
* In the context menu, select _Run As → SCTUnit_<br/>!images/sctunit_light_switch_030_run_as_sctunit.png(Run as SCTUnit)!
* The test in the test class is executed.
* The results are displayed in the _JUnit_ tab. A green bar is shown, which means our model fulfills the expectations expressed in the test class.<br/>!(small)images/sctunit_light_switch_040_sctunit_success.png(SCTUnit test succeeded)!



h3(#sctunit_adding_more_tests). Adding more tests

h4. Writing a test for the second requirement

The model by now implements the first requirement specified in section "&quot;Light switch requirements&quot;":#sctunit_light_switch_requirements.

So let's take care of the second requirement, formulate it as a SCTUnit test, and add it to the test class.

The whole test class now looks like this:

bc.. 
testclass light_switch_tests for statechart light_switch {

    @Test
    operation isStateOffActiveAfterInit () {
        enter
        assert active (light_switch.main_region.Off)
    }

    @Test
    operation isStateOnActiveAfterOperateInOffState () {
        enter
        raise operate
        proceed 1 cycle
        assert active (light_switch.main_region.On)
    }
}

p. The @raise operate@ instruction raises the _operate_ event. However, aside from this event having been raised, nothing will happen yet. The next instruction will change that.

The @proceed 1 cycle@ instruction orders the state machine to execute one run-to-completion step (RTC). During this RTC, the state machine can react to the raised _operate_ event.

Processing the _operate_ event should cause the *On* state to become active. This is checked by the following assertion:<br/>@assert active (light_switch.main_region.On)@

To make the test class syntactically correct, the statechart model must be amended by the _operate_ event and by the *On* state.


h4. Detecting a semantically wrong implementation

However, in order to demonstrate what happens if an SCTUnit test fails, let's have a look at a wrong implementation, as shown in figure "&quot;Erroneous light switch model&quot;":#sctunit_fig_erroneous_light_switch_model. Here the _operate_ event does not trigger a transition from *Off* to *On* but from *Off* back to *Off*.

p(#sctunit_fig_erroneous_light_switch_model). 

!images/sctunit_light_switch_050_erroneous_light_switch_model.png(Erroneous light switch model)!

p=. Erroneous light switch model

The test operation _isStateOnActiveAfterOperateInOffState_ should detect this semantic error and alert us. Running the amended test class as an SCTUnit again indeed leads to the following result:

!(small)images/sctunit_light_switch_060_sctunit_failure.png(SCTUnit test failed)!

The large bar is red now instead of green, meaning that at least one test failed. Below the bar the test class and its tests are listed and it is indicated which tests succeeded and which tests failed. We can see that our _isStateOffActiveAfterInit_ test still succeeds; so while we didn't correctly implement the second requirement, we at least didn't break the first one.

Fixing the model as follows turns the test green:

!images/sctunit_light_switch_070_fixed_light_switch_model.png(Fixed light switch model)!


h4. Calling operations

Okay, so let's write a test for the third and final requirement:

bc. 
    @Test
    operation isStateOffActiveAfterOperateInOnState () {
        isStateOnActiveAfterOperateInOffState
        raise operate
        proceed 1 cycle
        assert active (light_switch.main_region.Off)
    }

A prerequisite for dealing with an _operate_ event in the *On* state is to get into that state in the first place. However, we have implemented the necessary actions before, namely in the test _isStateOnActiveAfterOperateInOffState_. The great thing is that we can just use that test by calling it as subroutine. This is like calling a function or method in any other programming language.

We know that after executing _isStateOnActiveAfterOperateInOffState_ the *On* state is active – we even _assert_ that in the called test operation. So now we just have to raise _operate_ again, cycle the statechart once and check whether we are in the *Off* state after that.


h4. Looping

By going from *Off* to *On* and back to *Off*, we have ensured now that the light switch model behaves as specified. However, we might want to check whether this is still the case if we go through this cycle a number of times, say twice or 20,000 times. To support scenarios like this, the SCTUnit language provides a couple of advanced features, see section "The SCTUnit language":#sctunit_the_sctunit_language. Here we use the _while_ loop to iterate over the off-on-off cycle a couple of times:

bc. 
    @Test
    operation isStateOffActiveAfter10Cycles () {
        enter
        var i: integer = 0
        while (i < 10) {
            raise operate
            proceed 1 cycle
            assert active (light_switch.main_region.On)
            raise operate
            proceed 1 cycle
            assert active (light_switch.main_region.Off)
            i = i + 1
        }
    }




h2(#sctunit_the_sctunit_language). The SCTUnit language

While section "&quot;SCTUnit by example&quot;":#sctunit_sctunit_by_example gave an overview of test classes and operation, the section at hand provides you with a complete description of the SCTUnit language. Since the SCTUnit language is an extension of the "statechart language":../user-guide/statechart_language.html, this section will focus on language elements that are specific to the SCTUnit language. Please see section "&quot;The statechart language&quot;":../user-guide/statechart_language.html#sclang_statechart_language_reference for everything else.

An important extension of the SCTUnit language over the statechart language is that you can write your own "operations":#sctunit_operations_and_tests (subroutines) and control statements, like "_if_":#sctunit_conditional_statements and "_while_":#sctunit_loops. They make it possible to "script" complex procedures, for example by raising different events under different conditions or by looping over a sequence of statements multiple times.

Please remember that you can always hit <code>[Ctrl]+[Space]</code> when editing SCTUnit language files within YAKINDU Statechart Tools. The editor will show you all possible input choices that are valid at your cursor location.



==<!-- Start sctunit_keyword_testclass -->==

h3(#sctunit_test_classes). Test classes

A _test class_ contains one or more "operations":#sctunit_operations_and_tests or test cases. It is contained in a file with a _.sctunit_ filename extension.

==<div class="example">==

Example:

bc.. 
testclass NameOfTheTestClass for statechart NameOfTheStatechart {

    const pi : real = 3.141592654
    var sum : integer = 0

    @Test
    operation isFeatureAvailable () {
        /* … */
    }
}
p. 

==</div>==

A test class consists of the keyword @testclass@, followed by the name of the test class, followed by the keywords @for statechart@, followed by the name of the statechart this test class relates to.

The test class imports the statechart, so all variables, operations, events, etc. that are defined in an interface in the statechart's definition section, as well as the statechart's states, are available in and accessible by the test class.

bq. *Please note:* Entities defined in a statechart's internal scope are not visible from the outside, including test classes controlling the statechart.

The _body_ of a test class is enclosed in braces (<code>{ … }</code>). It consists of an optional part with variable and constant definitions, followed by at least one "operation":#sctunit_operations_and_tests.

Figure "&quot;Test class grammar&quot;":#sctunit_fig_test_class_grammar summarizes the structure of a test class:

p(#sctunit_fig_test_class_grammar). 

!images/sctunit_grammar_020_sctunitclass.png(Test class grammar)!

p=. Test class grammar

Test classes are namespace-aware: Using the "_package_ statement":#sctunit_the_package_statement, you can insert a test class into a specific "namespace":#sctunit_namespaces.

Test classes can be grouped into a "test suite":#sctunit_test_suites.

==<!-- End sctunit_keyword_testclass -->==



==<!-- Start sctunit_keyword_operation -->==

h3(#sctunit_operations_and_tests). Operations and tests

_Operations_ are comparable to methods, functions, or subroutines in other programming languages. Operations are defined in "test classes":#sctunit_test_classes.

A _test_ is parameterless operation without a return type that is annotated with <code>@Test</code>.

==<div class="example">==

Example:

bc. 
    @Test
    operation isFeatureAvailable () {
        enter
        var i: integer = 0
        var countValue: integer = count
        while (i < 10) {
            raise do_cycle
            assert active (myStatechart.main_region.State_A)
            assert count == countValue + 1
            i = i + 1
        }
    }

==</div>==

p. An operation is defined by the keyword @operation@, followed by the name of the operation, followed by a parenthesized list of parameters, optionally followed by a colon and a return type. If no return type is specified, it is inferred from the operation's "_return_ statement(s)":#sctunit_returning_an_operations_result.

Operations can also be annotated. Operations annotated with @Test@ are automatically executed when the SCTUnit test is executed.

The _body_ of an operation is enclosed in braces (<code>{ … }</code>). It consists of a sequence of "statements":#sctunit_statements_and_expressions, which may be empty. If the operation specifies a return type different from @void@, the operation must return a value of that type, using the "_return_ statement":#sctunit_returning_an_operations_result.

Figure "&quot;Operation grammar&quot;":#sctunit_fig_operation_grammar summarizes the structure of an operation:

p(#sctunit_fig_operation_grammar). 

!images/sctunit_grammar_030_operation.png(Operation grammar)!

p=. Operation grammar


h4(#sctunit_scopes). Scopes

An operation can define its own variables. Aside from these
* local variables
it also has access to
* variables and operations defined in the test class,
* variables, operations, events, and states defined in an interface of the statechart controlled by the operation's test class,
* entities imported by the statechart controlled by the operation's test class.
###. CHECK IMPORT: * entities imported by the operation's test class.
###. CHECK IMPORT: Fix commas and full stop in the list above when "import" becomes available.

An operation can call other operations. This is like subroutine calls in other programming languages.

###. CHECK IMPORT: An operation can call other operations. This is like subroutine calls in other programming languages. Called operations can be …
###. CHECK IMPORT: * located in the same test class,
###. CHECK IMPORT: * located in "imported":#sctunit_the_import_statement test classes that pertain to the same statechart.

Operations that are declared in the statechart _cannot_ be called from a testclass.


h4. Annotations

When running a "test class":#sctunit_test_classes or a "test suite":#sctunit_test_suites as an SCTUnit, only those operations are executed as tests that are annotated with <code>@Test</code>. Operations annotated with <code>@Ignore</code> or not annotated at all will not be regarded as tests. However, they can be called by test operations.

While the <code>@Ignore</code> annotation and an omitted annotation have the same effect functionally, you should use the <code>@Ignore</code> annotation to mark operations that are intended as tests, but are (temporarily) disabled for one or the other reason. This differentiates them from other operations that are not tests, but mere subroutines called from elsewhere.



==<!-- End sctunit_keyword_operation -->==

h3(#sctunit_statements_and_expressions). Statements and expressions

The body of an "operation":#sctunit_operations_and_tests consists of _statements_. Many types of statements, like _variable definitions_, _assignments_, _event raisings_, or _operation calls_, are already defined in the statechart language and are described "in section &quot;Statements&quot; of the statechart language documentation":../user-guide/statechart_language.html#sclang_statements.

Statement types that are specific to the SCTUnit language are described in the following subsections.

h4(#sctunit_returning_an_operations_result). Returning an operation's result

==<!-- Start sctunit_keyword_return -->==

The _return_ statement terminates the execution of the current operation. It either returns nothing or the value of an expression to the caller. If an expression is returned, its type must match the operation's return type. If the operation returns nothing, its return type must be _void_, either implicitly or explicitly.

==<div class="example">==

Example:

bc. 
    operation getCircleArea (radius: real): real {
        const pi: real = 3.141592654
        return pi * pi * radius
    }

The _return_ statement evaluates the expression @pi * pi * radius@, i.e., the area of a circle with radius _radius_, and returns the result to the caller of the operation. .

==</div>==

Figure "&quot;Return statement grammar&quot;":#sctunit_fig_return_statement_grammar summarizes the structure of the _return_ statement:

p(#sctunit_fig_return_statement_grammar). 

!images/sctunit_grammar_020_returnstatement.png(Return statement grammar)!

p=. Return statement grammar

==<!-- End sctunit_keyword_return -->==


==<!-- Start sctunit_keyword_assert -->==

h4(#sctunit_assertions). Assertions

When it comes to testing, the most important statement is the _assertion_. It evaluates a condition that must be fulfilled for the test to not fail.

==<div class="example">==

Example 1:

bc. assert sum == 42

This statement asserts that the variable _sum_ has a value of 42. If this is the case, the operation continues. If not, the test fails and is stopped.

bq. Unlike some other test frameworks, SCTUnit does not differentiate between @assert@ and @assert fatal@ or similar. All assertions are "fatal", which means they stop the test when they fail.

==</div>==

==<div class="example">==

Example 2:

bc. assert active (myStatechart.main_region.State_A)
assert !active (myStatechart.main_region.State_B) message "State_B must not be active here."

The first statement asserts that state _State_A_ in region _main_region_ in statechart _myStatechart_ is active. If this is not the case, the test fails.

The second statement asserts that _State_B_ is not active. Otherwise the test fails with the error message "State_B must not be active here.". 

bq. *Please note:* "active(…)":../user-guide/statechart_language.html#sclang_active_state is a built-in function of the statechart language.

==</div>==

Generally, an assertion consists of the keyword @assert@, followed by a boolean expression, optionally followed by the keyword @message@ and an error message text (string literal). The assertion expects the boolean expression to be _true_ to continue the test. If it evaluates to _false_ the test fails. The optional message can be used to clarify what went wrong.

==<!-- Start sctunit_keyword_called -->==

h5. Asserting an operation call

A special assertion variant uses the @called@ keyword ("_assert called_ statement"). It checks whether a certain operation has been called (executed), typically by some action in the statechart.

==<div class="example">==

Example:

bc. assert called myOperation
assert called myOperation(42, 815)
assert called myOperation 4 times
assert called myOperation(42, 815) 1 times
assert ! called myError

The first assertion checks whether the operation _myOperation_ has been called during the execution of this test. If it hasn't, the test fails.

The second assertion not only checks whether the operation _myOperation_ has been called, but also checks whether it has been called with parameters 42 and 815. If the operation hasn't been called at all, the test fails. The test also fails if the operation has been called, but with different parameters than 42 and 815, e.g., @myOperation(1, 2)@.

The third assertion checks whether the operation _myOperation_ has been called exactly 4 times, no matter the arguments, while the fourth assertion checks if the operation has been called exactly one time with the specified parameters.

The fifth assertion checks if the "forbidden" operation @myError@ has been called, and fails in that case. 

==</div>==

==<!-- End sctunit_keyword_called -->==

h5. Asserting an outgoing event

Finally, you can use the _assert_ statement to check whether the state machine has raised an outgoing event. To do so, the @assert@ keyword is followed by the name of the desired event. It is also possible to assert the opposite, i.e., that the event has _not_ been raised. In this case, insert the negation operator @!@ between @assert@ and the event name.

Here's an example:

==<div class="example">==

The statechart below transitions from state *A* to state *B* on either the _e1_ or the _e2_ incoming event. However, on _e1_, the outgoing event _e3_ will be raised, while this is not the case on _e2_.

p(#sctunit_fig_statechart_raising_an_outgoing_event). 
!(small)images/sctunit_outgoing_event_010.png(Statechart raising an outgoing event)!

p=. Statechart raising an outgoing event

You can verify this behavior using the following SCTUnit test class. The statement
* @assert e3@
succeeds if the _e3_ event has been raised, while
* @assert ! e3@
succeeds if that event has _not_ been raised.

bc.. 
testclass outgoingEventTest for statechart raiseOutgoingEvent {

    @Test
    operation test_e1 () {
        enter
        raise e1
        proceed 1 cycle
        assert e3
        exit
    }

    @Test
    operation test_e2 () {
        enter
        raise e2
        proceed 1 cycle
        assert ! e3
        exit
    }
}
p. 

==</div>==

h5. Assertion grammar

Figure "&quot;Assertion grammar&quot;":#sctunit_fig_assertion_grammar summarizes the structure of an assertion:

p(#sctunit_fig_assertion_grammar). 
!images/sctunit_grammar_030_assertion.png(Assertion grammar)!

p=. Assertion grammar

==<!-- End sctunit_keyword_assert -->==


==<!-- Start sctunit_keyword_enter -->==

h4(#sctunit_entering_a_state_machine). Entering a state machine

The _enter_ statement serves to enter the statechart associated with this "test class":#sctunit_test_classes. The state machine is initialized and started. The state that is denoted by the initial state becomes active.

A test must execute the _enter_ statement before it can perform any sensible testing on the statechart. Unless the state machine is entered, all states are inactive.

Please see section "&quot;SCTUnit by example&quot;":#sctunit_sctunit_by_example for examples on how the _enter_ statement is used. Please also see the "section on the _exit_ statement":#sctunit_exiting_a_state_machine.

==<!-- End sctunit_keyword_enter -->==


==<!-- Start sctunit_keyword_exit -->==

h4(#sctunit_exiting_a_state_machine). Exiting a state machine

The _exit_ statement exits and quits a state machine. You can re-initialize and re-enter it using the "_enter_ statement":#sctunit_entering_a_state_machine.


==<div class="example">==

Example:

The statechart _myStatechart_ looks like this:

!(tiny)images/sctunit_myStatechart_010_simple.png(Statechart "myStatechart")!

p=. Statechart _myStatechart_

The _enter_ and _exit_ statements are explained by the comments of this test class:

bc.. 
testclass enter_exit_tests for statechart myStatechart {

    @Test
    operation checkState () {

        /* Before entering the state machine, all states are inactive: */
        assert !active (myStatechart.main_region.State_A)

        /* Now we are entering the state machine. The state that the
         * initial state points to becomes active: */
        enter
        assert active (myStatechart.main_region.State_A)

        /* The "exit" statement leaves the state machine. All of the 
         * latter's states are thus inactive:
         */
        exit
        assert !active (myStatechart.main_region.State_A)

        /* It is possible to re-enter the state machine or to be precise:
         * to enter a new instance of the state machine. As above,
         * "State_A" should be active now: */
        enter
        assert active (myStatechart.main_region.State_A)
    }
}
p. 

==</div>==

==<!-- End sctunit_keyword_exit -->==


==<!-- Start sctunit_keyword_raise -->==

h4(#sctunit_raising_an_event). Raising an event

The _raise_ statement raises one of the state machine's _incoming_ events.


==<div class="example">==

Example 1:

bc. raise operate

This statement raises the _operate_ event, defined in the state machine's default interface.

==</div>==

==<div class="example">==

Example 2:

bc. raise valueChanged : 3

This statement raises the valueChanged event, defined in the state machine's default interface, which is of type _integer_. Raising a typed event without a payload is not allowed.

==</div>==

==<div class="example">==

Example 3:

bc. raise user.click

This statement raises the _click_ event, defined in the state machine's _user_ interface.

==</div>==

Since state machine internals are inaccessible to SCTUnit tests and outgoing events cannot be raised in general, only incoming events can be raised. Internal events, defined in the internal scope, and all outgoing events defined in an interface cannot be raised.

bq. *Please note:* The _raise_ statement is not specific to the SCTUnit language, but is (also) part of the statechart language, see section "&quot;Raising an event&quot;":../user-guide/statechart_language.html#sclang_raising_an_event.

==<!-- End sctunit_keyword_raise -->==


==<!-- Start sctunit_keyword_proceed -->==

h4(#sctunit_proceeding_a_state_machine). Proceeding a state machine

The tested state machine does not execute any run-to-completion steps (RTC) by itself, but only if being told so by way of the _proceed_ statement. The latter can advance the state machine by a specified number of RTCs or by a certain period of time. Event driven state machines run RTCs when an incoming event is raised. The syntax @proceed _n_ cycle@ is not available for these state machines.

==<div class="example">==

Example:

bc. raise operate
raise user.click
proceed 1 cycle

This example raises the _operate_ and _user.click_ events. The subsequent statement @proceed 1 cycle@ causes the state machine to perform one run-to-completion step, potentially acting on the raised events.

==</div>==

The _proceed_ statement consists of the keyword @proceed@ and an indication by what to proceed. Two variants are available:
* @proceed@ _number_ @cycle@ – This variant instructs the state machine to perform _number_ run-to-completion steps. Not available for event driven state machines.
* @proceed@ _number_ _time_unit_ – This variant instructs the state machine to proceed by the specified time, e.g., @proceed 30 s@ proceeds by 30 seconds. Supported time units are:
** @s@ – seconds
** @ms@ – milliseconds
** @us@ – microseconds
** @ns@ – nanoseconds

When running an SCTUnit test, the state machine does not run in real time, but in virtual time. That is, a statement like @proceed 3600 s@ does not have to wait for one hour of real time to elapse. Instead the state machine "leaps" by one hour in an instant, raises all affected time events, and processes them.

Figure "&quot;Proceed statement grammar&quot;":#sctunit_fig_proceed_statement_grammar summarizes the structure of the _proceed_ statement:

p(#sctunit_fig_proceed_statement_grammar). 

!images/sctunit_grammar_030_proceed.png(Proceed statement grammar)!

p=. Proceed statement grammar

==<!-- End sctunit_keyword_proceed -->==


==<!-- Start sctunit_keyword_var -->==

h4(#sctunit_defining_variables_and_constants). Defining variables and constants

Variables and constants (for brevity we'll summarize both as "variables") can be defined as specified in the statechart language, please see sections "&quot;Variables&quot;":../user-guide/statechart_language.html#sclang_variables and "&quot;Constants&quot;":../user-guide/statechart_language.html#sclang_constants for all the details. 

However, variables in the SCTUnit language _must_ always be initialized. For example, while a definition like

bc. var sum: integer

is fine in the statechart language, it is an error in the SCTUnit language. You would rather have to write something like

bc. var sum: integer = 0

Variables can be defined in the scope of the test class or in operations.

==<!-- End sctunit_keyword_var -->==


==<!-- Start sctunit_keyword_if -->==
==<!-- Start sctunit_keyword_else -->==

h4(#sctunit_conditional_statements). Conditional statements

The _if_ statement executes a sequence of statements depending on a condition.

==<div class="example">==

Example 1:

bc. 
        if (i < 5) {
            raise do_cycle
        }

The _do_cycle_ event is raised if the variable _i_ has a value that is less than 5. Otherwise nothing happens.

==</div>==

==<div class="example">==

Example 2:

bc. 
        if (i < 5) {
            raise do_cycle
        } else {
            raise button5
        }

The _do_cycle_ event is raised if the variable _i_ has a value that is less than 5. If _i_ is equal to or greater than 5 the _button5_ event is raised instead.

==</div>==

The _if_ statement starts with the keyword @if@, followed by a boolean expression in parenthesis, followed by a sequence of statements in braces. The sequence of statements must contain at least one statement. It is executed if and only if the boolean expression evaluates to _true_.

And optional _else_ clause may follow. It consists of the keyword @else@, followed by a sequence of statements in braces. The sequence of statements must contain at least one statement. It is executed if and only if the boolean expression evaluates to _false_.

Figure "&quot;If statement grammar&quot;":#sctunit_fig_if_statement_grammar summarizes the structure of the _if_ statement:

p(#sctunit_fig_if_statement_grammar). 

!images/sctunit_grammar_020_ifexpression.png(If statement grammar)!

p=. If statement grammar

==<!-- End sctunit_keyword_if -->==
==<!-- End sctunit_keyword_else -->==


==<!-- Start sctunit_keyword_while -->==

h4(#sctunit_loops). Loops

The _while_ statement executes a sequence of statements repeatedly, as long as a condition is fulfilled.


==<div class="example">==

Example:

bc. 
        var i : integer = 0
        while (i < 10) {
            raise do_cycle
            proceed 1 cycle
            i = i + 1
        }

The statements in the _while_ loop's body are executed ten times.

==</div>==

The _while_ statement starts with the keyword @while@, followed by a boolean expression in parenthesis, followed by a sequence of statements in braces, the loop's body. The loop's body must contain at least one statement. It is executed repeatedly if and only if the boolean expression evaluates to _true_. The expression is evaluated before the first execution of the loop body and after each execution of the loop body.

Figure "&quot;While statement grammar&quot;":#sctunit_fig_while_statement_grammar summarizes the structure of the _while_ statement:

p(#sctunit_fig_while_statement_grammar). 

!images/sctunit_grammar_020_loopstatement.png(While statement grammar)!

p=. While statement grammar

==<!-- End sctunit_keyword_while -->==


==<!-- Start sctunit_keyword_is_active -->==
==<!-- Start sctunit_keyword_is_final -->==

h4(#sctunit_retrieving_the_state_machines_status). Retrieving the state machine's status

The keywords @active@, @is_active@ and @is_final@ make it possible to retrieve certain aspects of the state machine's status as boolean values and e.g., use them in "assertions":#sctunit_assertions.

==<div class="example">==

Example:

bc. assert is_active

The assertion succeeds if at least one state is active. This is always the case if the state machine has been "entered":#sctunit_entering_a_state_machine and has not been "exited":#sctunit_exiting_a_state_machine. Please note that a final state can be active, too.

The assertion fails if the state machine has not been "entered":#sctunit_entering_a_state_machine or has been "exited":#sctunit_exiting_a_state_machine.

==</div>==

==<div class="example">==

Example:

bc. assert is_final

The assertion succeeds if the state machine is active (see above) and all its active states are final states.

The assertion fails if the state machine is not active (see above) or it has at least one active state that is not a final state.

==</div>==

==<div class="example">==

Example:

bc. assert active(main_region.StateA)

The assertion succeeds if the specified state is active. States have to be fully qualified with their containing region etc., because state names are not unique in a statechart.

The assertion fails if the specified state is not active.

==</div>==

==<!-- End sctunit_keyword_is_final -->==
==<!-- End sctunit_keyword_is_active -->==


==<!-- Start sctunit_keyword_mock -->==

h4(#sctunit_mocking_an_operation_call). Mocking an operation call

The _mock_ statement allows you to mock the operations defined in the statechart. You can specify what should be returned when the operation is called, even depending on the given input parameters.

==<div class="example">==

Consider a complex operation _getNeutronFlux_, which takes a real value as an argument and returns a real value as a result. During _semantic unit testing_ of your statechart – as opposed to _integration testing_ –, you won't want to integrate the operation into your testing environment. Aside from that, it's currently not possible to call operations, for example defined in a Java class, from SCTUnit.

Your statechart, however, depends on _getNeutronFlux_ returning actual results, as can be seen in the simple model shown in figure "&quot;Neutron flux statechart&quot;":#sctunit_fig_neutron_flux_statechart:

p(#sctunit_fig_neutron_flux_statechart). 

!images/sctunit_neutron_flux_010_statechart.png(Neutron flux statechart)!

p=. Neutron flux statechart

While *State_A* is active, the state machine will call _getNeutronFlux(p)_ during each run-to-completion step and, depending on the results, will take the transition to *State_B* (or not).

==</div>==

However, how could you test the behaviour of your statechart if you cannot call an actual operation and retrieve its results?

That's what the _mock_ statement is for. It is a makeshift that mimics an actual operation call by two mechanisms:
# It creates a static mapping from a specific operation call with a specific list of parameter values to a specific return value.
# If that operation is called with exactly that specific list of parameter values the caller receives the mapped return value as a result.

A test can create an arbitrary number of such mappings, i.e., it can use the _mock_ statement multiple times for multiple operations, or for multiple parameter list of the same operation.

==<div class="example">==

Consider the following test:

bc. 
    @Test
    operation testNeutronFlux() {
        mock getNeutronFlux(12.0) returns (1000000000.0)
        mock getNeutronFlux(18.0) returns (4.3)
        enter
        p = 18.0
        proceed 1 cycle
        assert active(neutronFlux.main_region.State_A)
        p = 12.0
        proceed 1 cycle
        assert active(neutronFlux.main_region.State_B)
    }

The effect of the two _mock_ statements is as follows:
* If _getNeutronFlux(12.0)_ is called, the return value is 1000000000.0.
* If _getNeutronFlux(18.0)_ is called, the return value is 4.3.
* If _getNeutronFlux_ is called with any other parameter value, the return value is undefined.

The test assigns 18.0 to the statechart variable _p_, and performs one run-to-completion step. During this RTC, the state machine calls _getNeutronFlux(p)_ in order to evaluate the guard condition @[getNeutronFlux(p) >= 100.0]@. Since _p_ has a value of 18.0, the mocked operation returns 4.3, and the transition from *State_A* to *State_B* is not taken.

After that, the test sets _p_ to 12.0 and executes another RTC. This time, the mocked operation returns 1000000000.0, the guard condition evaluates to _true_ and the state machine transitions to *State_B*.

Calling _getNeutronFlux_ with any other parameter value than 12.0 or 18.0 would not only let the test fail, but would also throw an exception, because the actual operation cannot be called in test mode (simulation mode) and its return value is undefined.

==</div>==

In order to avoid an exception to be thrown, you can define a _mock_ statement with a _default_ return value. This value will be returned from all calls of the mocked operation that are not explicitly overridden by _mock_ statements with specific parameters.

==<div class="example">==

The _mock_ statements in the example above might have better been written as follows:

bc. 
        mock getNeutronFlux returns (-1.0)
        mock getNeutronFlux(12.0) returns (1000000000.0)
        mock getNeutronFlux(18.0) returns (4.3)

The first _mock_ statements defines a return value of -1.0 for each and every call to the _getNeutronFlux_ operation, irrespective of the parameter value. The following statements, however, override this setting for the parameter values 12.0 and 18.0.

bq. *Please note:* The order of the _mock_ statements is important! You should define the general case first, followed by specifying return values for specific parameter lists.

==</div>==

The type of the default value specified in the _mock_ statement must match the return type of the mocked operation.

Figure "&quot;Mock statement grammar&quot;":#sctunit_fig_mock_statement_grammar summarizes the structure of the _mock_ statement:

p(#sctunit_fig_mock_statement_grammar). 

!images/sctunit_grammar_020_mockreturnstatement.png(Mock statement grammar)!

p=. Mock statement grammar

==<!-- End sctunit_keyword_mock -->==


h3(#sctunit_test_suites). Test suites

==<!-- Start sctunit_keyword_testsuite -->==
A _test suite_ aggregates a set of "test classes":#sctunit_test_classes into a logical unit. It is contained in a file with a _.sctunit_ filename extension.

==<div class="example">==

Example:

bc. testsuite MyTestSuite {
    TestClassA,
    TestClassB,
    TestClassC
}

p. The test suite _MyTest_Suite_ comprises the test classes _TestClassA_, _TestClassB_, and _TestClassC_.

==</div>==

The nice thing about test suites is that you can run all tests of all the test classes at once. Right-click on the test suite file, say, _mytestsuite.sctunit_, and select _Run As → SCTUnit_ in the context menu. All tests in all test classes referenced in the test suite will be executed.

You can put test classes which test different statecharts into one test suite. However, all test classes within a test suite must pertain to statecharts using the same language domain. For example, if you have a statechart using YAKINDU Statechart Tools' default domain and another statechart using the "C domain":../user-guide/c-domain.html, you cannot put their respective test classes into the same test suite. Instead you would have to write two different test suites: one for the test classes testing your "normal" statecharts, the another one for testing your "C" statecharts.

A test suite is defined by the keyword @testsuite@, followed by the name of the test suite.

The _body_ of a test suite is enclosed in braces (<code>{ … }</code>). It consists of one or more names of test classes, separated by comma.

Figure "&quot;Test suite grammar&quot;":#sctunit_fig_test_suite_grammar summarizes the structure of a test suite:

p(#sctunit_fig_test_suite_grammar). 

!images/sctunit_grammar_020_sctunitsuite.png(Test suite grammar)!

p=. Test suite grammar

Test suites are namespace-aware: Using the "_package_ statement":#sctunit_the_package_statement, you can insert a test suite into a specific "namespace":#sctunit_namespaces.

###. CHECK IMPORT: You can "import":#sctunit_the_import_statement test suites and test classes from the same or from different namespaces into a test suite.

==<!-- End sctunit_keyword_testsuite -->==



h3(#sctunit_namespaces). Namespaces

You can organise your "test classes":#sctunit_test_classes and "test suites":#sctunit_test_suites in different namespaces. Each test class or test suite can assign itself to a namespace by the "_package_":#sctunit_the_package_statement statement.

###. CHECK IMPORT: It can import test classes and test suites from other namespaces by the "_import_":#sctunit_the_import_statement statement.


==<!-- Start sctunit_keyword_package -->==

h4(#sctunit_the_package_statement). The _package_ statement

Use the _package_ statement to determine a namespace for the test class or test suite in the current _.sctunit_ file. The _package_ statement is optional, but if you use it, it must be the first statement of your _.sctunit_ file. Test classes and test suites without a preceeding _package_ statement will be put into the default namespace.


==<div class="example">==

Example:

###.. CHECK IMPORT: bc.. package foo.light_switch.test
import bar.helper.steamgen
import bar.util.*

testclass light_switch_tests for statechart light_switch {
…
}

###.. CHECK IMPORT: Remove the bc.. block below when "import" is available.

bc.. package foo.light_switch.test

testclass light_switch_tests for statechart light_switch {
…
}
p. The _package_ statement puts the _light_switch_tests_ test class into the _foo.light_switch.test_ namespace.

==</div>==

The _package_ statement consists of the keyword @package@, followed by the package name (namespace). The package name is fully-qualified, i.e., in dot notation.

Please see section "&quot;Test units&quot;":#sctunit_test_units for a summary of the _package_ statement's and related statements' grammar.

==<!-- End sctunit_keyword_package -->==


###. CHECK IMPORT: ==<!-- Start sctunit_keyword_import -->==
###. CHECK IMPORT: 
###. CHECK IMPORT: h4(#sctunit_the_import_statement). The _import_ statement
###. CHECK IMPORT: 
###. CHECK IMPORT: Use the _import_ statement to make test classes and test suites from other namespaces available in the test class or test suite at hand.
###. CHECK IMPORT: 
###. CHECK IMPORT: ==<div class="example">==
###. CHECK IMPORT: 
###. CHECK IMPORT: The example given in section "&quot;The _package_ statement&quot;":#sctunit_the_package_statement uses two _import_ statements:
###. CHECK IMPORT: 
###. CHECK IMPORT: bc. import bar.helper.steamgen
###. CHECK IMPORT: 
###. CHECK IMPORT: Imports the _steamgen_ test class or test suite from the _bar.helper_ package.
###. CHECK IMPORT: 
###. CHECK IMPORT: ==</div>==
###. CHECK IMPORT: 
###. CHECK IMPORT: ==<div class="example">==
###. CHECK IMPORT: 
###. CHECK IMPORT: bc. import bar.util.*
###. CHECK IMPORT: 
###. CHECK IMPORT: Imports all test classes and test suites from the _bar.util_ package.
###. CHECK IMPORT: 
###. CHECK IMPORT: ==</div>==
###. CHECK IMPORT: 
###. CHECK IMPORT: Please see section "&quot;Test units&quot;":#sctunit_test_units for a summary of the _import_ statement's and related statements' grammar.
###. CHECK IMPORT: 
###. CHECK IMPORT: ==<!-- End sctunit_keyword_import -->==


h4(#sctunit_test_units). Test units

A _test unit_ is either a "test class":#sctunit_test_classes or a "test suite":#sctunit_test_suites. It is contained in a file with a _.sctunit_ filename extension.

###. CHECK IMPORT: Figure "&quot;test_unit_grammar&quot;":#sctunit_fig_test_unit_grammar summarizes the structure of a test unit:

###. CHECK IMPORT: p(#sctunit_fig_test_unit_grammar). 

###. CHECK IMPORT: !images/sctunit_grammar_030_test_unit.png(Test unit grammar)!

###. CHECK IMPORT: p=. Test unit grammar %{display: block; font-size: 50%; padding-left: 20%; padding-right: 20%;}*Please note:* The _PackageImport_ non-terminal symbol will be available in future versions of YAKINDU Statechart Tools.%




h2(#sctunit_generating_sctunit_source_code). Generating SCTUnit source code

Executing SCTUnit tests within the Eclipse development environment as described in section "&quot;Running the test&quot;":#sctunit_running_the_test is a nice and handy feature for the developers. However, it all happens on the modeling level, a higher abstraction level than the actual source code you are likely generating from your statechart. You will probably want to test the generated source code as well, especially in any safety critical environments.

Generating unit tests as source code comes as a solution. Source code can be inspected, compiled, and integrated wherever needed.

This section explains how you can generate your SCTUnit tests as source code with YAKINDU Statechart Tools. Supported programming languages are Java, C, and C++. The generated Java classes use "JUnit":http://junit.org/ as their testing framework and "Mockito":http://site.mockito.org/ for mocked methods. C and C++ sources rest upon the "Google Test":https://en.wikipedia.org/wiki/Google_Test unit testing library.

In order to use the SCTUnit code generators effectively, you should already be familiar with generating source code from statecharts, as explained in chapter "&quot;Generating state machine code&quot;":../user-guide/code_generation_intro.html#codegen_generating_state_machine_code. In fact, you have to generate your statechart as source code first, so that the SCTUnit tests have something to be executed upon. Below we are assuming that you have your statechart code generator model and the generated code handy. Generating SCTUnit test source code follows the same principcles as generating state machine source code, so we can focus on SCTUnit essentials here.



h3(#sctunit_creating_a_generation_model). Creating a generation model

The first step is to create a _generation model (SGen)_ for the SCTUnit test, similar to explanation in section "&quot;Generating state machine code&quot;":../user-guide/code_generation_custom.html#setting_up_a_code_generator_project.

# In the main menu, select _File → New → Other…_. The _New_ dialog opens.
# In the _New_ dialog, select _YAKINDU SCT → Code generator model_.
# Click on _Next_. The _YAKINDU generator model_ wizard opens.
# Select a project and a folder as the SGen model's location. The filename must end on _.sgen_.
# Click on _Next_.
# In the _Generator_ drop-down menu, select one of the source code generators whose names begin with "SCTUnit", e.g., "SCTUnit Java Code Generator". As a consequence, the _Choose_ list below the drop-down menu switches from showing statechart models to displaying SCTUnit files.
# In the _Choose_ list, check the SCTUnit files you want to generate as source code.
# Click on _Finish_.

As a result, the SGen model file is created. Figure "&quot;A sample SCTUnit SGen model&quot;":#sctunit_fig_a_sample_sctunit_sgen_model shows a generator model for the SCTUnit Java generator. The target language is reflected in the generator ID "sctunit::java". The generator IDs for C and C++ are "sctunit::c" and "sctunit::cpp", respectively. Each SCTUnit "test unit":#sctunit_test_units is contained in a section marked with the _test_ keyword, followed by the respective fully-qualified test unit name.

p(#sctunit_fig_a_sample_sctunit_sgen_model). 

!images/sctunit_genmodel_010_created.png(A sample SCTUnit SGen model)!

p=. A sample SCTUnit SGen model

In this example, the generation model refers to the SCTUnit sample test class defined in section "&quot;The _package_ statement&quot;":#sctunit_the_package_statement above. In that example, the test class is put into package _foo.light_switch.test_, while the test class itself is named _light_switch_tests_. Consequently, the test class' fully-qualified name is _foo.light_switch.test.light_switch_tests_, and that is what the generation model indicates in the _test_ statement.



h3. Features

A code generator's behavior can be controlled by so-called _features_. SCTUnit code generators are supporting the same set of features the all statechart code generators support. The same applies to the features of the respective language-specific generators. The *Outlet* feature is of particular importance, since it determines where the generated artifacts will be created.

Documentation of feature details you can find here:

* "Common features of all statechart code generators":../user-guide/code_generation_intro.html#codegen_configuring_a_generator
* "C statechart code generator features":../user-guide/code_generation_c.html#codegen_c_code_generator_features
* "C++ statechart code generator features":../user-guide/code_generation_cpp.html#codegen_cpp_code_generator_features
* "Java statechart code generator features":../user-guide/code_generation_java.html#codegen_java_code_generator_features



h3. The SCTUnit Java code generator's _StatechartNaming_ feature

For Java, the generated state machine code on one hand and the SCUnit test classes on the other hand may well belong to different packages. However, in order to be able to execute the state machine, the SCTUnit tests need to know what the state machine's package is.

This is what the *StatechartNaming* feature is good for. Let's assume we added the following *StatechartNaming* feature to the generation model shown "above":#sctunit_creating_a_generation_model:

bc. feature StatechartNaming {
    basePackage = "bar.light_switch"
    implementationSuffix = ""
    libraryTargetFolder = "src-timer"
}

With these settings, the SCTunit code generator creates the test classes in the _src-gen_ directory. Additionally, it creates a few timer classes. These classes provide the concept of "virtual" time and are used during test execution to simulate arbitrary long periods of time in an instant. The source code of these classes is generated in the directory denoted by the _libraryTargetFolder_ property, here: _src-timer_. The timer classes belong to the _bar.light_switch_ package. The test classes expect the timer classes and the state machine to reside in that very same package, in order to execute the state machine parameterized with the virtual timer.



h3. The generated Java test class

The Java source code generated from SCTUnit test classes or test suites takes the form of JUnit tests and can be integrated in CI environments, for example.

In Eclipse, you can execute such a generated JUnit test by right-clicking on the corresponding _.java_ file and selecting _Run As → JUnit Test_ in the context menu.

==</div>==
