ScxmlEditor-Tutorial

Contents SCXML Wiki Forum

How to debug SCXML statecharts

ScxmlEditor has an ability to execute SCXML statecharts via testing applications or to listen external UDP commands such as state enter or exit, etc.

Local debugging

ScxmlEditor starts a testing application, intercepts its command line output and may communicate in two modes:

There are two ready-to-use testing applications:

  1. Based on USCXML framework. Supports null, lua, ecmascript(since 2.1.5.1507) datamodels

  2. QtScxmlTester - based on Qt SCXML framework Supports null, ecmascript datamodels

Also you may write your own testing application using the corresponding API

Receive API:

Commands to clear state charts

State chart processing commands

  1. Type - integer type of command: 1 - AfterEnter, 2 - BeforeEnter, 3 - AfterExit, 4 - BeforeExit, 5 - Step, 6 - BeforeExecContent, 7 - AfterExecContent, 8 - BeforeInvoke, 9 - AfterInvoke, 10 - BeforeUnInvoke, 11 - AfterUnInvoke, 12 - BeforeTakingTransition, 13 - AfterTakingTransition, 14 - StableConfiguration, 15 - BeforeProcessingEvent
  2. ScxmlName - name of <scxml>
  3. Msg - message which depends on type of command. For example: for BeforeEnter or BeforeExit - it is the id(name) of states, for BeforeInvoke or BeforeUnInvoke it is the name of invoked element, etc.
  4. Id - identifier of the invoked state machine (Since ScxmlEditor 2.2). Can be empty for root machines

BeforeEnter graphically highlight and BeforeExit unhighlight the corresponding states, other commands are displayed in CallStack panel

Since ScxmlEditor 2.3 there is an option to highlight taking transitions in BeforeTakingTransition Message format: FromState|TransitionIndex where TransitionIndex is transition xml child index

Example of commands:

You can also trace the execution of the chart and use breakpoints.

Send API:

It is similar to SCXML send events logic

Testing application receives events as UDP string packages in the next format:

Option 1. With single content expression

<EVENT name="%EVENT_NAME%" >
	<content type="%DATA_TYPE%" >
		%CONTENT_DATA%
	</content>
</EVENT>

Option 2. With multiple params

<EVENT name="%EVENT_NAME%" >
	<param name="%PARAM_NAME%" type="%DATA_TYPE%" expr="%PARAM_DATA%">
	<param name="%PARAM_NAME%" type="%DATA_TYPE%" expr="%PARAM_DATA%">
</EVENT>

Triggers

Triggers are used to submit events to the state machine

Transition Triggers

For simple events you can double click (or click depending on settings) on event name to trigger an event

TriggerWhere
TriggerDoubleClick

GUI Triggers

Triggers will create a GUI elements for passing data to statechart

TriggerPanel

TriggerSimple

Type of triggers representation

Default

CheckBox

ComboBox

TrackBar

Nested event.data params

If you need to pass nested event.data like event.data.val there is a menu Params in inspector EventDataParams

DEMO. In runtime params will be represented as edits with buttons

EventDataParamsDemo

Breakpoints

You can associate breakpoints with states. When the state with breakpoint set is entered, state machine events queue is interrupted and program highlights the breakpoint and changes the scxml root element background into light yellow colour. BreakpointsIdle

Adding breakpoints

BreakpointsAdd

Trace mode

In trace mode state machine event queue is interrupted and waits for user 'Next Step' button is clicked.

This mode is activated when:

BreakpointsAdd

How to debug multiple invoked state machines

Let's take a look at the example when state machine invokes two same nested state machines DebugInvoke

Invoke ID

DebugInvoke2

If invoke identifier of submachine is not set then the first identifier is used

DebugInvoke3

How to change current Invoke ID

DebugInvoke3

DebugInvoke4

External debugging

In this mode ScxmlEditor only listens UDP commands for highlighting states and displaying messages in CallStack panel

Qt SCXML framework debugging

NEW! Qt SCXML Debug Via SVG

It was an old dream to monitor state machine workflow without any external dependencies in Qt and finally it comes true. We prepared some native SCXML SVG monitors:

StopWatchDemo

Since ScxmlEditor 2.2.1 you can export SCXML to SVG, include only monitor headers in your app and create monitor instances any time.

NOTICE: While state machine pointer is not set, the monitor does nothing and can be left in Release.

Qt SCXML External Debugging with ScxmlEditor

For Qt SCXML applications you may include scxmlexternmonitor2.h header to your project and follow the instructions

Example of debugging Qt Calculator-QML project

MonitorQML1

  1. Select Run->Start listening from external application
  2. Select Run->Run
  3. Launch Calculator-QML.exe
  4. Use Pause for tracing (optionally)

CalculatorDebug

Option to pass event or custom data to CallStack View

If you need to pass event or custom data to CallStack view, you can override monitor class.

Debug_ProcessEventData

class MyMonitor: public Scxmlmonitor::UDPScxmlExternMonitor {
    public:
        inline explicit MyMonitor(QObject *parent = nullptr): Scxmlmonitor::UDPScxmlExternMonitor(parent) {}
    protected:
        inline virtual void processEventMessage(QScxmlStateMachine *machine, const QString &id, const QScxmlEvent &event) {
            const QString sEventData = event.data().toString();
            processMonitorMessage(machine->name(),
                                  id,
                                  sEventData.isEmpty() ? event.name() : (event.name() + ": [" + sEventData + "]"),
                                  Scxmlmonitor::smttBeforeTakingTransition);
            // ---> example: add custom info to all events, that starts with 'in.'
            if (event.name().startsWith("in.")) {
                processMonitorMessage(machine->name(),
                                      id,
                                      "my custom data: " + sEventData,
                                      Scxmlmonitor::smttBeforeProcessingEvent);
            }
        }
};

You should enable custom data types in ScxmlEditor settings if you want to receive it in CallStack View process_events_settings

Custom testing application setup

Since version 2.1.8 there is an option to communicate with testing applications via pipes.

Example: how to setup The SCION command-line tool as custom testing application

  1. install SCION CLI by command npm install -g @scion-scxml/cli
  2. after installation check c:\Users\USER_NAME\AppData\Roaming\npm\node_modules@scion-scxml\cli\bin\cli.js is to be the latest from the corresponding gitlab repo
  3. run any test scxml file in CMD to check that SCION CLI is working without errors SCION_CLI_console
  4. open Settings->TestApplicationPresets and check that it is properly adjusted according to the image below Tutorial_CustomTesterScion Tutorial_CustomOutputCapture

If API is changed in the future you may edit regular expressions to capture enter-exit events properly

  1. select SCION CLI in application run presets Tutorial_CustomSelectTester
  2. if everything is set properly you will see callstack messages and state machine will flow from state to state Tutorial_CustomDebug
TOP Contents SCXML Wiki Forum