lsd-core

semantic-release CI Nightly Build GitHub release Maven Central

LSD Core

A tool for creating sequence diagrams dynamically without needing to worry about markup.

This library generates html reports and each report contains one or more scenarios of captured events to be displayed on a sequence diagram.

(Additionally a component diagram is generated to show relationships).

LSD_example

Usage

Kotlin:

  fun main() {
    val lsd = LsdContext.instance
  
    lsd.capture(
      MessageBuilder.messageBuilder().from("A").to("B").label("message1").build(),
      MessageBuilder.messageBuilder().from("B").to("A").label("message2").build(),
    )
    lsd.completeScenario("<Scenario Title>")
    lsd.completeReport("<Report Title>")
  }

Java:

  public static void main(String[] args) {
      LsdContext lsd = LsdContext.getInstance();
      
      lsd.capture(
          MessageBuilder.messageBuilder().from("A").to("B").label("message1").build(),
          MessageBuilder.messageBuilder().from("B").to("A").label("message2").build()
      );
      lsd.completeScenario("<Scenario Title>", "<description>");
      lsd.completeReport("<Report Title>");
  }

Participants

Instead of using a String to specify a participant you can create a Participant type. This give you more options, e.g. to provide an alias , colour and type. So instead of "A" which will produce a default type of PARTICIPANT in the examples above you could use:

ACTOR.called("A", "Arnie", "blue") which will create a stickman labelled as “Arnie” and will be coloured in red.

ParticipantTypes include:

You can define participants upfront and register them using the lsd context, e.g.

    lsd.addParticipants(listOf(arnie, donnie))

The participants specified here will override any other participants with the same name so if you want to ensure colours or aliases are not overridden set them here before creating a report.

SequenceEvents

There are other event types that can be captured, other than messages.

Additional options

Property Name Default Description
lsd.core.label.maxWidth 200 The width in number of characters for the labels that appear on the diagrams before being abbreviated.
lsd.core.diagram.theme plain The plantUml theme to apply to the diagrams. See the available themes.
lsd.core.report.outputDir build/reports/lsd The directory to write the report files. (This can be a relative path).
lsd.core.ids.deterministic false Determines how the html element ids are generated. Allowing deterministic ids is useful when testing (e.g. approval tests of html output since the generated ids won’t be random. The default option which provides random ids should be preferred otherwise.
lsd.core.diagram.sequence.maxEventsPerDiagram 50 To help make really large diagrams easier to read this value is used to decide when to split a potentially large diagram into sub-diagrams. (Each sub diagram will remove any unused participants and include the participant headers and footers).
lsd.core.devMode true Offline mode with inline css and js. Helps development when amending css and js but can also be useful when runninng in environments without internet connectivity
lsd.core.metrics.enabled false Experimental feature to show a table of metrics on the report (e.g. top bottlenecks, time to generate the report etc.)
   
LSD Reports with metrics enabled LSD report example Popups contain additional data. They open when the arrows are clicked Popup example
Components Reports contain a component diagram of all participants from all reports and scenarios that were captured prior to generating the components report via completeComponentsReport() components report example Index pages contain links to all reports that were generated prior to the index page being rendered index page example
   

A few related libraries exist to automate some of the steps to capture scenarios and generate reports e.g. via JUnit or Cucumber as plugins or extentions to the libraries.

Building

Prerequisites

Git hooks

Git hooks will be configured automatically (to use the hooks in .githooks directory when the gradle clean task is invoked).

Build

./gradlew clean build

Troubleshooting

Static files stale

Since the static css and javascript files are cached on JSDelivr CDN it will occasionally be useful to force clear the cache to avoid waiting for several days (I think it’s up to 7 days). Use this tool to clear the cache and specify these files:

Note that the browser cache may also need to be cleared since the browser will also cache css and js files if they have the same url

This site is open source. Improve this page.