GUI
Last updated at 2018-01-09
Sprockets test_driver expands state transition graphs based on STL. Since the number of vertexes (i.e. states) and edges (i.e. transitions) could be expanded much more than ones specified in STL, an effective visual graph representation would be much helpful for users to understand what is going on currently and which state transitions fail during test.
This document shows general flow how test_driver interacts with a web browser to draw a graph for test and represent its progress.
This document compares 2 graph representations, graphviz and sigma.js in details.
(Original diagram can be editted from here)
When test_driver is running, it hosts a web server waiting for web socket connections from GUI pages. It supports multiple GUI pages connecting simultaneously.
A GUI page on a web browser connects a web socket to the web server running in test_driver, fetches the state transition information, and renders a directed graph representing the state transition. Since graph can be too big to show in a page, GUI page should support
- Zooming in/out
- Scrolling up/down/left/right, and
- Auto focusing on current transition when current transition goes out of screen.
GUI server running in test_driver.py forwards any state transition happening or error/success/progress messages to GUI page to refresh the graph. GUI pages highlight current state transition (i.e. edge) and (optionally) print error/success/progress messages in a separate console window.
graphviz is used to convert state transition graph to SVG. GUI client in GUI page updates SVG properties according to state transition progress.
(Original diagram was rendered by js-sequence-diagram. To update the diagram:
- Open raw content of gist of this diagram.
- Copy content from after
<source><![CDATA[to before]]></source>. - Paste copied text into one of text areas in js-sequence-diagram.
- Update diagram accordingly.
- Download "Simple" theme as SVG.
- Update gist of this diagram with new SVG.
- Create new entry in rawgit.com.
- Update the URLs of diagram and of raw content.)
The protocol specification is defined in a separate page.
GUI client and server should comply these requirements:
- test_driver.py has a mode to accept a websocket from GUI to control test flow. GUI should be able to start the test specified in the manifest, stop the test, get the entire graph of the test, and get current test status.
- error_handler in test_driver.py reports compile-time parsing errors and run-time state transition progress including successes and errors.
- GUI interprets and presents the graph and state transition progress in the main window.
- When user selects a node, a pop-up window shows detailed information of given node including states.
- When user selects an edge, a pop-up window shows detailed information of given edge including events and error_states. Note that pre_states and post_states are obvious from graph.
- GUI prints messages of state transition progress including error messages in the console window.
- GUI associates graph edges and error messages. When user selects an edge in the graph window, the console window scrolls to the latest error message associated to the edge. Or vice versa.
- [Stretched] GUI supports zooming, panning, and automatic focusing on current state.
- [Stretched] For each state transition failures, GUI can instruct test_drivier.py to restart the test only to test the given transition. test_driver.py knows shortest path to test the given state transition.
After 2 options were investigated in detail, graphviz has been chosen because it has more pros than sigma.js.
4.1. graphviz
graphviz
- pros
- Actual representation of graph is automatically calculated including node positions, edge shapes, etc.
- Multiple ways to draw graph.
- webgraphviz with public viz.js
- pygrahpviz since sprockets is made by python
- networkx used by test_driver.py already depends on pygraphviz
- Can change color of nodes and edges. So, possible to present progress.
- Display node & edge titles when mouse hovers over them on Chrome. Not tested with other browsers.
- cons (if we use SVG without any changes. See below to overcome these)
- Cannot make interactions: clicking nodes/edges, zooming, panning, etc.
- Need to parse entire graph always.
An html example to draw a diagram with webgraphviz:
<!DOCTYPE html>
<html>
<head>
<style type="text/css">
#graph-container {
width: 98vw;
height: 98vh;
}
</style>
</head>
<body>
<div id="graph-container"></div>
<script src="http://www.webgraphviz.com/viz.js"></script>
<script>
var data = 'digraph G {"Welcome" -> "To"; "To" -> "Web"; "To" -> "GraphViz!"}';
var svg = Viz(data, 'svg');
document.getElementById('graph-container').innerHTML = svg;
</script>
</body>
</html>
A python example to draw a diagram with pygraphviz:
>>> import pygraphviz
>>> a = pygraphviz.AGraph('digraph G { "Welcome" -> "To"; "To" -> "Web"; "To" -> "GraphViz!"}')
>>> a.draw(format='svg', prog='dot')
The returned SVG looks like:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
...
<!-- Welcome -->
<g id="node1" class="node">
<title>Welcome</title>
<ellipse fill="none" stroke="black" cx="79" cy="-162" rx="48.0542" ry="18"/>
<text text-anchor="middle" x="79" y="-157.8" font-family="Times,serif" font-size="14.00">Welcome</text>
</g>
<!-- To -->
<g id="node3" class="node">
<title>To</title>
<ellipse fill="none" stroke="black" cx="79" cy="-90" rx="27" ry="18"/>
<text text-anchor="middle" x="79" y="-85.8" font-family="Times,serif" font-size="14.00">To</text>
</g>
<!-- Welcome->To -->
<g id="edge2" class="edge">
<title>Welcome->To</title>
<path fill="none" stroke="black" d="M79,-143.697C79,-135.983 79,-126.712 79,-118.112"/>
<polygon fill="black" stroke="black" points="82.5001,-118.104 79,-108.104 75.5001,-118.104 82.5001,-118.104"/>
</g>
...
To overcome cons above, when returned SVG is set to the main window, we should
- browse SVG DOM tree and map DOM nodes to corresponding graph node and edge data entries.
- replace the title of DOM nodes with that of graph node and edge data entries.
- insert onclick event callback into DOM nodes to pop up a window to display detailed information of graph node and edge data entries.
- change 'stroke' and 'fill' color of DOM nodes on state transition progress.
- zooming and panning could be done with normal javascript operation on main window.
- focusing on current state could be calculated with cx, cy, rx, ry values.
4.2. sigma.js
- pros
- Supports most requirements to manipulate the state transition graph efficiently. It can zoom, have different views, hover over nodes & edges, add callbacks, change colors of nodes & edges, etc.
- MIT license which allows modification by any purpose.
- cons
- Node position should be provided. Not calulated.
- Edge is always straight. When 3 nodes are on the same line, it is hard to distinguish edges.
- sigma.min.js should be hosted somewhere. However, this might not be a big deal since it can be hosted together with GUI files.
An html example to draw a diagram:
<!DOCTYPE html>
<html>
<head>
<style type="text/css">
#graph-container {
width: 98vw;
height: 98vh;
}
</style>
</head>
<body>
<div id="graph-container"></div>
<script src="sigma.min.js"></script>
<script>
var s = new sigma('graph-container');
s.graph.read({
nodes: [{ id:'n1', x:0, y:0, size:1 },
{ id:'n2', x:1, y:0, size:1 },
{ id:'n3', x:1, y:1, size:1 },
],
edges: [{ id:'e1', source:'n1', target:'n2' },
{ id:'e2', source:'n1', target:'n3' },
],
});
s.refresh();
</script>
</body>
</html>