Generation of Sequence Diagrams
Since 1.4 it is possible to generate sequence diagrams with the help of UMLGraph and the Plotutils Package. With 1.6 also the format of websequence diagrams is supported for the generation.
Write a Unit Test
Although it is not required to write a unit test for sequence diagram generation it is a good starting point. To demonstrate we write an additional unit test for the Account class of JFS210 sample of PatternTesting (see AccountTest):
@Test
public void testTransfer() {
Account other = new Account(2, new User("r2d2"));
account.transfer("47.11", other);
assertEquals(new BigDecimal("47.11"), other.getBalance());
assertEquals(new BigDecimal("-47.11"), account.getBalance());
}
This is a simple unit test for the transfer method but should be sufficient for the first step.
@DrawSequenceDiagram (websequencediagrams.com)
If PatternTesting Runtime is added as AspectJ library (see [Hello World] how to do it) you need only to put the annotation @DrawSequenceDiagram in front of your test:
@Test
@DrawSequenceDiagram("target/test-transfer.txt")
public void testTransfer() {
Account other = new Account(2, new User("r2d2"));
account.transfer("47.11", other);
assertEquals(new BigDecimal("47.11"), other.getBalance());
assertEquals(new BigDecimal("-47.11"), account.getBalance());
}
The only difference to the unit test above is the line
@DrawSequenceDiagram("target/test-transfer.txt")
It triggers the generation of the sequence diagram and put the result in a textual representation in the file "target/test-transfer.txt":
title test-transfer
# AccountTest -> +Account 2: <<create>>
AccountTest -> +Account 1: transfer("47.11", Account-2)
Account 1 -> +Account 1: debit("47.11")
Account 1 -> +Account 1: debit(47.11)
Account 1 --> -Account 1:
Account 1 --> -Account 1:
Account 1 -> +Account 2: deposit("47.11")
Account 2 -> +Account 2: deposit(47.11)
Account 2 --> -Account 2:
Account 2 --> -Account 1:
Account 1 --> -AccountTest:
AccountTest -> +Account 2: getBalance()
Account 2 --> -AccountTest: 47.11
AccountTest -> +Account 1: getBalance()
Account 1 --> -AccountTest: -47.11
You can copy this text and put it into https://www.websequencediagrams.com/. This site will generate a graphical representation.
@DrawSequenceDiagram (UMLGraph)
If you replace the suffix ".txt" with ".pic" the sequence diagram will be generated for UMLGraph:
@Test
@DrawSequenceDiagram("target/test-transfer.pic")
public void testTransfer() {
Account other = new Account(2, new User("r2d2"));
account.transfer("47.11", other);
assertEquals(new BigDecimal("47.11"), other.getBalance());
assertEquals(new BigDecimal("-47.11"), account.getBalance());
}
To view the generated file you have to use the plotutils which are based on GNUPlot.
Install GNUPlot and plotutils
The generated diagram file is a readable plot file. To be able to print it or show it on the screen you need GNUPlot and plotutils to convert it into another format. If you have Linux -- good choice. Here it is probably part of your distribution. For Mac OS-X see GNUPlot & pic2plot on Mac, for Windows I guess it is part of the Cygwin toolchain.
Convert Sequence Diagram into PostScript
To convert the generated plot file "target/test-transfer.pic" into another format take a look at the header of this file:
#
# Sequence Diagram
# ================
#
# To convert this pic file into another format (e.g. PostScript) use the
# pic2plot command from the GNU Plotutils:
#
# pic2plot -Tps file.pic > file.ps
#
# NOTE: The encoding if this file is ISO-8859-1.
# see also www.gnu.org/software/plotutils/manual/en/html_node/index.html
#
Here you see an example of the conversion into a PostScript file. So go the the directory with your .pic file, start the command line and type
pic2plot -Tps test-transfer.pic > test-transfer.ps
The result should be "test-transfer.ps" of type PostScript which you put into you favorite PostScript viewer (e.g. Ghostview) and send to the printer.
Result
This is the result of the generated sequence diagram, converted into SVG (option "-Tsvg") and then converted to PNG.
Troubleshooting
Strings Look Strange
This feature is still experimental in v1.4. E.g. in v1.4.0 String are not correct escaped (see bug 25). As workaround you can edit the generated .pic file. Look for the line
# ------------------------- Begin of Sequence Diagram -------------------------
and correct the lines after manually. Or use v1.4.1.
If you find another error please create a bug report with the needed infos how to reproduce it.
Diagram Shows Only Direct Calls
To avoid too many elemens in a sequence diagram (and to avoid to much overhead) only the direct calls of the annotated method (e.g. "testTransfer() in the example above) will be used for the generation of the diagram. If you want more calls in the diagram annotated the calls of the methods you want to see also in the diagram. In the example above the method "transfer" in the Account class is also annotated with "@DrawSequenceDiagram".
Elements Missing in Diagram
To avoid too much details in the generated sequence diagram only the call of public (and non static) methods are logged. Also calls of classes from JDK (and AspectJ) classes are excluded.
