lsd-consulting / lsd-core Goto Github PK

View Code? Open in Web Editor NEW

6.0 3.0 1.0 1.58 MB

Core components for generating reports with sequence diagrams

License: MIT License

Java 3.74% HTML 60.88% CSS 2.94% JavaScript 1.36% Shell 0.58% Handlebars 3.06% Kotlin 27.44%

sequence-diagrams lsd

lsd-core's Introduction

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).

Usage

Add dependency for version:

Maven

  <dependency>
      <groupId>io.github.lsd-consulting</groupId>
      <artifactId>lsd-core</artifactId>
      <version>X.X.X</version>
  </dependency>

Gradle

    implementation 'io.github.lsd-consulting:lsd-core:X.X.X'

User lsd context singleton to capture messages (and other events):

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:

ACTOR
BOUNDARY
COLLECTIONS
CONTROL
DATABASE
ENTITY
PARTICIPANT
QUEUE

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.

PageTitle - Sets a title on the diagram
NoteLeft - Create a note (can be to the left of a provided participant)
NoteRight - Similar to NoteLeft but on the right
NoteOver - Create a note in the middle of a participant lifeline
TimeDelay - Shows that a period of time has elapsed (optional label can be provided)
Newpage - Splits a diagram into a new page at the point this event was captured
ActivateLifeline - Activates a participant lifeline (colour can be provided)
DeactivateLifeline - Deactivates a lifeline that has been activated

Additional options

A html index file can be generated if multiple reports are captured:
```
    lsd.createIndex()
```
Generate a component diagram for events included from multiple scenarios and reports
```
    lsd.completeComponentsReport("Relationships")
```

To draw attention to some interesting details you can include facts e.g.

    // instances of the keyword Lorem will be highlighted on the report
    lsd.addFact("Something to highlight", "Lorem")

Advanced users may want to include additional files for additional icons etc. For example to include a heart icon on a note:

      lsd.includeFiles(listOf("tupadr3/font-awesome-5/heart"))

      lsd.capture(NoteLeft("Friends <$heart{scale=0.4,color=red}>"))

Properties

The following properties can be overridden by adding a properties file called lsd.properties on the classpath of your application or by setting a System property. Note that System properties override file properties.

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.)

Gallery


LSD Reports with metrics enabled	Popups contain additional data. They open when the arrows are clicked
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()`	Index pages contain links to all reports that were generated prior to the index page being rendered

Related Libraries

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

Java 17 JDK

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

lsd-core's People

Contributors

Stargazers

Watchers

Forkers

bonified080

lsd-core's Issues

Add maven-central badge

Useful for showing latest released version

Fix tooltip on arrow hyperlinks (when prefixed with whitespace)

When the label starts with whitespace the plantUml markup becomes invalid so the tooltip is included in the hyperlink text.
Trimming any leading or trailing space should do the trick

Potentially remove the String DSL for creating SequenceEvent types

Simplify the API by removing the ability to use the DSL (non Builder)

Remove plantuml markup from report - make available via popup instead

By default the plantuml should be hidden
The uml can be displayed via popup instead

Automate image/giphy creation of example report

Use a tool to take a screenshot or create a giphy of an example report so that the README can stay up to date without too much manual effort.
This could be done per release perhaps - maybe github actions could be used

Highlight facts

When a provided fact value matches values in the popups or labels we can emphasise those words.

Add additional SequenceEvent types

For convenience extra sequence diagram event types can be created.

Some ideas:

Note to the right
Time-delay
Short inbound arrow
Short outbound arrow
Arrow from Beginning
Arrow to end
Start group/End group (perhaps a group object could encapsulate other events to auto close etc.)

Add contents section to report page

Each report should have a contents sections with hyperlinks to each scenario to allow for easy navigation to different parts of the report.

Remove duplicate entries from the component diagrams

Duplicate interactions should be removed from the component diagrams since we just want an idea of which components interact with which.

Add links for going to the top of a page within a report

Each section should have a link to go back to the top of the page

Add short message type (and short response)

For events that show that an action has occurred without coming from/to a participant (using the plantUml '?' syntax)

Add default output directory back to the LsdProperties to avoid errors when no properties are set

To prevent errors when a new project is being setup we should have a default output directory set that can be overridden if necessary.

Add some simple styling for keywords in scenario descriptions

Given, When, And, Then etc. within the scenario descriptions could have some basic styling.

Deploy the static files (JS, CSS) to a CDN

It would make it much easier to develop other projects based on lsd-core if the static files were deployed outside the project.

Add top level Index/Contents page

A html page that lists all the report titles (with hyperlinks)
It should also include links to the scenarios in each report

Add optional component diagram

If the user contains Graphviz/Dot on their system they can get a Component diagram along with the sequence diagram.

Perhaps this could be disabled via property if the user wants/needs to disable the extra diagram.

Automate releasing, publishing and changelog

Use semantic-release Github action to automate the release versioning and changelog updates
Move sonatype (for maven central) publishing to a Github action

Look at using smetana as an alternative to requiring the graphviz (dot) binary for component diagrams

To avoid requiring the user to install Graphviz the following could be applied to the component diagrams:

!pragma layout smetana

The advantage being that this should work out the box without the need to additional tools to be installed on the client's machine.

Possible downsides - the smetana implementation is a port of the graphviz dot functionality so won't be as rich and may contain some bugs but since we only use a tiny bit of the library for layout if could be a good option.

Fix duplicated participants in the LSD source section

Multiple calls to

lsdContext.addParticipants()

cause duplicates in the list of participants in the LSD source section:

Add "copy to clipboard" option to data popups

Particularly the source/markup popups so that it is easy to grab the content into the clipboard

Fix key fact highlighting for popups

Popups containing keywords / facts are not being highlighted in some situations. Needs further investigation.

Add ability to split sequence diagram every x number of interactions

To help make viewing larger diagrams easier (where it is hard to see the participants because they may be off the screen) it would be useful to split the diagram into new pages.

Add property to specify how many interactions before a newpage is issued for the diagram
Set a sensible default value

Deprecate the old yatspec fork

Add deprecation notice with details on where to find the new replacement repositories.

Create cucumber plugin library

Similar to the JUnit5 extension we need a library for cucumber

Fix component diagram markup

The participant names are being altered incorrectly when there is no spaces e.g. OneTwoThree is being converted to Onetwothree which no longer matches the actual participant names.

Allow colours for sequence events

Add option to colour a sequence event
This could be useful for highlighting failures, warnings or colour coordinating a group of related events (e.g. from same thread of execution or http trace Ids etc.)

Add usage instructions and how the API works to README

This should be intended for other devs who would like to develop a plugin.

Add links to other related libraries that make use of the lsd-core library

Make it easy to find related libraries that may be of interest via the README page

Make popup scrollable

Large texts such as stacktraces don't scroll making it difficult to view the full value

Fix squashed up Component diagrams

When no participant type is specified for several participants the generated component diagram uses a strange default type which is usually very small and bunches up the text (names) of the participants and becomes unreadable.

One solution is to default to component type in the component diagrams if none is provided.

Add instructions for contributing to the project

Some simple instructions for contributing.

Add the spring-configuration-metadata.json file

So that the LSD Core properties are picked up by IDEs.

Read system properties

To enable consistent passing of properties from plugins to the core, we should consider including the system properties in properties read/loaded by default.

Component diagram - hide @unlinked no longer working

Since switching to !pragma layout smetana for component diagrams (to remove the need for Graphviz) I noticed that unlinked components are no longer being removed from component diagrams.

Extract styling to separate file

Reference a local css file instead now that the file is getting big
Share the file with the Index page to keep the styles in sync.

Fix report output directory creation when multiple new directories need creating

The output report is not being created if multiple new directories need to be created.

Index page links should highlight failed and aborted tests

Include colour coding that matches the reports for errors, warnings and success reports
If any of the scenarios contain an error mark the report hyperlink with an error class or if any contain a warning then mark the hyperlink with a warning class otherwise we can use a success class.

Fix "squashed" sequence diagrams

When the page is resized or the image is too wide the diagrams can be caused to disappear off the left hand size of the screen.

Instead the image should be allowed to scroll so that no part of the image is unviewable.

Update groupId to reflect new github organisation for the LSD projects

Use new value: io.github.lsd-consulting

Add example report to README

Add example(s) of what a report looks like (maybe animated gif etc.)

Remove SequenceDiagram section when there isn't a diagram to show

No point in having an empty sequence diagram sections
The markup section should also be removed

Add the ability to generate a report without generating the report file(s)

There are the following use cases for having the report generate a string in memory:

testing lsd-core plugins
embedding the report within a dynamically generated page, eg. in an app for generating LSD reports from db stored interactions.

Accept string pattern for sequence events

Sometimes it's easier to use simple string patterns instead of builders, e.g.

sending a message from A to B could be parsed using regex to create a message event (along with a second argument to capture the popup data (and possibly a third for colour once that's implemented).

This library should provide a test extension that will build up the report and titles based on test names etc.

Set expected order of precedence for properties

System properties should take precedence over the lsd.properties file values. The lsd.properties values should take precedence over the default properties.

Loading them in this order should result in the above order of precedence being true.

Default values
Properties File values
System Property values

Add link back to index page from reports

Make it easier to navigate back to the index page since using the 'back' button will need to go back through various clicks for popups etc.

Close popup on clicking outside of window

Print the absolute report path

Currently the path printed is the relative path which prevents a clickable hyperlink from being generated in IDEs.