SoftwareX 12 (2020) 100590

Contents lists available at ScienceDirect

SoftwareX
journal homepage: www.elsevier.com/locate/softx

Original software publication

Sismic—A Python library for statechart execution and testing

∗
Alexandre Decan , Tom Mens
Software Engineering Lab, University of Mons, Belgium

article info a b s t r a c t

Article history: Statecharts are a well-known visual modelling language for representing the executable behaviour of
Received 15 May 2019 complex reactive event-based systems. The essential complexity of statechart models solicits the need
Received in revised form 9 March 2020 for advanced model testing and validation techniques, such as test-driven development, behaviour-
Accepted 14 September 2020
driven development, design by contract, and property statecharts for monitoring of violations of
Keywords: behavioural properties during statechart execution. Sismic is an open-source Python library providing
Statechart a tool suite to define, simulate, execute and test statecharts with all of the aforementioned techniques.
Executable modelling © 2020 The Author(s). Published by Elsevier B.V. This is an open access article under the CC BY license
Behaviour-driven development (http://creativecommons.org/licenses/by/4.0/).
Design by contract
Runtime verification

Current code version

Code metadata

Current code version 1.4.1 (commit d61e748)

Permanent link to code/repository used for this code version https://github.com/ElsevierSoftwareX/SOFTX_2019_181
Code Ocean compute capsule Not applicable
Legal Code Licence GNU Lesser General Public Licence version 3.0 (LGPLv3)
Code versioning system used git
Software code languages, tools, and services used Python
Compilation requirements, operating environments & dependencies Python 3.5+; ruamel.yaml, schema, behave, typing
If available Link to developer documentation/manual https://sismic.readthedocs.io
Support email for questions alexandre.decan@lexpage.net

Current executable software version

Software metadata
Current software version 1.4.1
Permanent link to executables of this version https://github.com/AlexandreDecan/sismic
Legal Software Licence GNU Lesser General Public Licence version 3.0 (LGPLv3)
Computing platforms/Operating Systems Linux, OS X, Microsoft Windows
Installation requirements & dependencies Python 3.5+; ruamel.yaml, schema, behave, typing
If available, link to user manual–if formally published include a reference to the https://sismic.readthedocs.io
publication in the reference list
Support email for questions alexandre.decan@lexpage.net

1. Motivation and significance automata. Statecharts are part of the UML standard and constitute
a popular notation for representing the executable behaviour
Statecharts are a visual executable modelling language intro- of complex reactive event-based systems. They are frequently
duced by David Harel [1] as an extension of hierarchical finite used in industry for the development of real-time systems and
state machines with characteristics of both Mealy and Moore embedded systems, relying on commercial tools such as IBM
Rational Rhapsody, The Mathworks Stateflow, itemis Yakindu Stat-
∗ Corresponding author. echart Tools, IAR Systems visualSTATE, and QuantumLeaps QM.
E-mail addresses: alexandre.decan@umons.ac.be (A. Decan), Most of these tools support visualisation, modification and sim-
tom.mens@umons.ac.be (T. Mens). ulation of statecharts, as well as code generation from statechart

https://doi.org/10.1016/j.softx.2020.100590
2352-7110/© 2020 The Author(s). Published by Elsevier B.V. This is an open access article under the CC BY license (http://creativecommons.org/licenses/by/4.0/).
A. Decan and T. Mens SoftwareX 12 (2020) 100590

models. The more advanced tools also provide support for model 2.2. Software architecture
debugging and model verification.
A wide variety of testing techniques and associated tools is Sismic provides a modular, easily extensible architecture, sum-
available for developing source code in programming languages. marised in Fig. 1. Experienced Python developers may choose
These techniques include test-driven development (TDD) [2], to directly create and manipulate statecharts through the sis-
behaviour-driven development (BDD) [3], and design by contract mic.model API. In practice, it is more convenient to create stat-
(DbC) [4]. These techniques have proven their usefulness for echarts using either a text-based markup editor or an external
‘‘classical’’ programming languages. Since the statechart formal- visual editor, and import these models through the sismic.io
ism is Turing-complete [5], such techniques can also be beneficial API. This API has support for exporting statecharts to PlantUML
during the development of executable statecharts. (plantuml.com) in order to visualise them by means of automatic
For this purpose, we have developed Sismic (a recursive layout features. This is how Fig. 2 has been generated.
acronym for Sismic Interactive Statechart Model Interpreter and Sismic’s main component is the sismic.interpreter module. In
Checker), a modular Python library for executing, testing and order to execute a statechart model, an interpreter must be
instantiated. This interpreter relies on an action code evaluator
validating executable statecharts based on the techniques of TDD,
to execute any code contained in the actions or guards of the
BDD, DbC, and property statecharts that allow to monitor for
statechart specification. Module sismic.code provides such an
violations of behavioural properties during statechart execution.
evaluator to express action code using regular Python.
Sismic targets both researchers and practitioners interested in
The interpreter supports run-time monitoring of contract vi-
exploring and putting these techniques into practice in their
olations. Contracts are specified directly as part of the state-
software development projects. Sismic provides a flexible API
chart description using the language supported by the action
to facilitate its use in regular Python code or to facilitate its code evaluator, and can use a range of predefined predicates.
extension by other researchers. Sismic has been validated through The interpreter also provides built-in support for runtime mon-
a controlled user study in [6] and is used by multiple companies. itoring properties expressed as statecharts. These properties are
expressed as statecharts that express functional properties of the
2. Software description intended behaviour in terms of the events that are consumed or
sent, or in terms of the states that are entered or exited by a
statechart being monitored. Finally, module sismic.bdd provides
Sismic is a statechart library for Python (version 3.5 or higher)
support for BDD by providing a flexible way to define, map and
providing a set of tools to define, execute and test statecharts.
execute BDD scenarios.
The library is distributed through the Python Package Index.1
Its source code is available on GitHub2 under the open-source
3. Illustrative example
licence LGPLv3. Sismic is extensively documented on sismic.re
adthedocs.ioand comes with an extensive test suite with high
To illustrate the use of Sismic, consider the example of a
code coverage. The tests, examples and code fragments of the
simplified microwave controller in Fig. 2, visually rendered with
documentation are automatically executed as part of a continuous
PlantUML. The code fragment below shows part of the YAML
integration process.
description of this statechart:

2.1. Software functionalities statechart:

name: Simple microwave controller
root state:
Sismic provides an easy way to define and import statecharts, name: microwave controller
based on the human-friendly YAML markup language. Visuali- initial: door closed
on entry: timer = 0
sation of these statecharts is realised through an interface with states:
PlantUML. - name: door opened
Sismic’s statechart interpreter offers a discrete, step-by-step, on entry: send(’lamp_on’)
observable simulation engine, supporting the main statechart on exit: send(’lamp_off’)
transitions:
concepts. The default interpreter uses an inner-first/source-state - event: door_closed
and run-to-completion semantics (a.k.a. big step semantics [7]), target: door closed
but it can be tuned to other semantics by subclassing this in-
terpreter. To support timed events, the interpreter comes with This statechart can be executed through API calls to Sismic’s
controllable simulation clock that supports both real and simu- interpreter:
lated time. Statechart actions and guards can be expressed using
from sismic.io import import_from_yaml
regular Python code as the action language, but Sismic can be
from sismic.interpreter import Interpreter
extended to support other action languages as well. Sismic also statechart = import_from_yaml(filepath=’microwave.yaml’)
provides support for communication between statecharts, as well interpreter = Interpreter(statechart)
as for allowing regular Python code to be called from within interpreter.queue(’timer_inc’, ’cooking_start’)
interpreter.execute()
statecharts and vice versa. assert ’cooking’ in interpreter.configuration
With respect to statechart testing, Sismic supports regular unit
testing of statecharts; a DbC approach to specify invariants, pre- Contracts are defined as part of the statechart. At runtime, the
and postconditions on states and transitions [4]; BDD [3]; and interpreter will verify the conditions specified by the contracts.
runtime checking of behavioural properties that are expressed as The example below shows a contract for the ‘‘cooking’’ state of
statecharts themselves. the microwave:

contract:
1 pypi.org/project/sismic.
- before: timer > 0
2 github.com/AlexandreDecan/sismic. - after: received(’door_opened’) or timer == 0

2
A. Decan and T. Mens SoftwareX 12 (2020) 100590

Fig. 1. High-level architectural overview of Sismic.

Fig. 2. Visual representation of a simplified microwave controller.

Sismic supports BDD to express scenarios or test cases by is an interpreter inside an interpreter and as such, has some
domain experts in natural language. This allows designers to overhead compared to plain Python code. So far, none of the
focus on the purpose of the model rather than the technical Sismic users has reported any limitation related to performance.
details. Given an appropriate mapping, the following scenario Sismic could be extended with more advanced automated
can be executed and checked by Sismic using the command-line support for statechart testing, such as the generation of state-
utility sismic-bdd: charts from scenarios, the generation of contracts for a given
statechart (similar to the automated generation of contracts over
Scenario: Heating is on while cooking
Given I open the door programmes [8]), the generation of tests from contract specifi-
And I place an item in the oven cations [9], the use of mutation testing and concolic testing at
And I close the door the level of statecharts [10,11], the detection and improvement
And I press increase timer button 5 times of quality problems in statechart and contract specifications, and
When I press start button
Then heating turns on so on.

4. Impact 5. Conclusions

We have carried out a controlled user study to evaluate the

To conclude, Sismic is an open source and extensible Python
feasibility, usefulness and adequacy of using Sismic for the pur-
library with full-fledged support for defining and executing stat-
pose of defining, validating and testing executable statecharts [6].
echarts, and these statecharts can be validated using a portfolio of
The thirteen participants to the study indicated that the tech-
techniques including unit testing, behaviour-driven development,
niques implemented by Sismic were easy to use. The received
design by contract, and property statecharts for monitoring of
feedback provided evidence that BDD scenarios and runtime
violations of behavioural properties during execution.
monitoring of contracts and property statecharts are beneficial
during statechart design. Most participants indicated that they
were likely to use these techniques in the future for the purpose Declaration of competing interest
of creating new statecharts, or for verifying or modifying existing
ones. The authors declare that they have no known competing finan-
Sismic is being used successfully by several companies, no- cial interests or personal relationships that could have appeared
tably for model-in-the-loop testing and simulations, for workflow to influence the work reported in this paper.
and business process support, and for the execution and valida-
tion of concurrent distributed statecharts. We also use Sismic in
the classroom for teaching executable behavioural modelling to Acknowledgement
bachelor students.
Since Sismic is a pure Python implementation of a statechart This paper was carried out in the context of Excellence of Sci-
execution engine, its performance mainly depends on the perfor- ence project O.0157.18F-RG43 ‘‘SECO-Assist’’ financed by Fonds
mance of the underlying Python engine. By construction, Sismic de la Recherche Scientifique—FNRS.
3
A. Decan and T. Mens SoftwareX 12 (2020) 100590

References [7] Esmaeilsabzali S, Day NA, Atlee JM, Niu J. Deconstructing the semantics
of big-step modelling languages. Requir Eng 2010;15(2):235–65. http:
[1] Harel D. On visual formalisms. Commun ACM 1988;31(5):514–30. http: //dx.doi.org/10.1007/s00766-010-0102-z.
//dx.doi.org/10.1145/42411.42414. [8] Ernst MD, Perkins JH, Guo PJ, McCamant S, Pacheco C, Tschantz MS,
[2] Beck K. Test-driven development by example. Addison-Wesley; 2002, http: Xiao C. The daikon system for dynamic detection of likely invariants.
//dx.doi.org/10.5555/579193. Sci Comput Program 2007;69(1–3):35–45. http://dx.doi.org/10.1016/j.scico.
[3] North D. Behavior modification: The evolution of behavior-driven 2007.01.015.
development. Better Softw 2006. [9] Meyer B. Contract-driven development. In: Int’l conf. fundamental ap-
[4] Meyer B. Applying ‘‘design by contract’’. IEEE Comput 1992;25(10):40–51. proaches to software engineering (FASE). Lect. notes in computer science,
http://dx.doi.org/10.1109/2.161279. vol. 4422, Springer; 2007, p. 11. http://dx.doi.org/10.1007/978-3-540-
[5] Lu H, Yu S. On the computing power of statecharts. In: Proceedings of 71289-3_2.
the international conference on foundations of computer science (FCS). [10] Fabbri SCPF, Maldonado JC, Sugeta T, Masiero PC. Mutation testing applied
Citeseer; 2011, p. 1. to validate specifications based on statecharts. In: Int’l symp. software
[6] Mens T, Decan A, Spanoudakis NI. A method for testing and validating reliability engineering (ISSRE). IEEE Computer Society; 1999, p. 210–9.
executable statechart models. Softw Syst Model 2019;18(2):837–63. http: http://dx.doi.org/10.1109/ISSRE.1999.809326.
//dx.doi.org/10.1007/s10270-018-0676-3. [11] Sen K. Concolic testing. In: Int’l conf. automated software engineering.
ACM; 2007, p. 571–2. http://dx.doi.org/10.1145/1321631.1321746.