Architecture and Design
This document contains the architecture and design of the system.
LivingDoc 2 uses a JUnit derived test annotation to declare tests. It’s main goal is the execution of table or textbased scenarios.
The graphic shows the class-hierarchy of Examples (named TestData in the code). There are two kinds of Examples. DecisionTables and Scenarios.
The class-hierarchy for the test-results is similarly structured.
The following graphic visualized the work-flow during tests. First, business-experts define tests in form of tables (DecisionTable) or text (scenarios).
The next step is for test-engineers to write the logical part of the tests, which is called fixtures.
LivingDoc extends the JUnit-engine to execute the tests.
The outcome are results (for details of the types of results, check the graphic above). These results are used to create reports in html or json form. The report types are also extendable (See #29).
Package livingdoc-api
All annotations used for writing fixtures are defined in the api-package.
Package livingdoc-config
The central ConfigProvider manages and loads the yaml configuration and provide simple type safe access to it for all other components.
Package livingdoc-converters
The converter package contains the available converters to convert the content of the examples (written in html- or md-files) to Kotlin-types.
Package livingdoc-junit-engine
The livingdoc-junit-engine subproject contains a JUnit test engine that can be used to run livingdoc tests by JUnit.
The class org.livingdoc.junit.engine.LivingDocTestEngine is the main entrypoint for the JUnit test engine.
The JUnit TestEngine is currently the only test engine supported.
The subproject livingdoc-engine contains the implementation of the test logic independent of the testing tool.
Package livingdoc-engine
We use domain-driven design to define the internal data model of LivingDoc. The domain model is independent of:
-
TestEngine (e.g. JUnit)
-
JVM language
-
Testcase structure
graph LR
Group --- DocumentFixture --- Fixture
The Fixture maps Test Inputs to a series of interactions with the System under Test and evaluates Expectations. Fixture`s are an abstraction of the fixtures coded by a developer, a fixture is used to execute a Test Case. Each fixture type is respresented by an implementation of `Fixture. (e.g. Decisiontable - DecisionTableFixtureWrapper /Scenario - ScenarioFixtureWrapper)
A fixture can be executed using the execute method which takes the Testdata as an argument.
DocumentFixture represents a fixture for a complete document and uses Fixture`s to execute all `Testdata of the document.
The DocumentFixture abstracts the code structure of the test cases e.g. the used fixture implementation can be external or nested classes.
A DocumentFixture can be executed using the execute method without arguments.
Groups group DocumentFixture`s. The `Group can be executed so using the execute method without arguments, which then executes all `DocumentFixture`s of the `Group`s.
The class LivingDoc is used as API entry point. It provides methods to execute Group and DocumentFixture. LivingDoc first creates the domain model and then calls the execute function on all `Group`s.
Package livingdoc-repositories
The repositories package contains the functionality stubs to decide the document type and parse html documents. It uses the ServiceLoader API and jsoup.
Package livingdoc-repository-file
Based on the repository the file repository contains the format (html vs. markdown) and the file fucntionality (load, configuration, structure, indentification). Basically the FileRepository is a something like [DocumentRepository] in a local filesystem.
Package livingdoc-results
Contains the results of the execution. The results are separated from the engine because extending the results would require the programmer to import the whole engine. This way only the result package can be imported.