trickert76/livingdoc

Write and manage your acceptance tests in any format you like incl. in Atlassian Confluence.

LivingDoc 2

The next version of LivingDoc, the acceptance testing tool with integrated support for Atlassian Confluence.

Features

LivingDoc 2 allows you to apply behaviour driven development by allowing users to create and define test cases. These test cases can be written as plain text (scenario fixtures) or as tables with input values and formulas with results (decision tables).

Concept

When developing software, it is important that all participants have a common knowledge base on which to discuss functions and define goals. Each stakeholder has a specific task with LivingDoc. They can be defined as follows.

Example of roles

• User: Writes the Example/TestData. He therefore describes in a record or table what the input parameters are and what the result must be.

• Tester: Is responsible for writing the test fixtures. They get their input values and the results via annotations. The test cases are then implemented to verify that the implementation is correct.

• Developer: Implements the required functionality in the system under test.

Supported Platforms

As for now, local files, Confluence and REST Repositories are supported. For more information, on how to use the different repositories see Repository documentation.

You should also take a look at the Quality Goals defined for LivingDoc 2.

Getting started

There is several documentation available:

• The Developer Documentation focuses on topics that are important for developers of LivingDoc 2. In addition, the repository contains architectural decisions besides other documents and the code documentation is extracted to Github Pages.

• The End-User Documentation focuses on topics that are relevant for users of LivingDoc 2, either test engineers or business experts. Its ASCIIDoc-based source is included in the repository.

If you want to start working with LivingDoc 2 you will need to clone this repository or add dependencies to your project via Maven or Gradle. You can use the following fragment from our demo project to add the necessary dependencies.

build.gradle.kts

dependencies {
        ...
	testRuntime("org.livingdoc:livingdoc-junit-engine:2.0-SNAPSHOT")
	testRuntime("org.livingdoc:livingdoc-repository-file:2.0-SNAPSHOT")
	testRuntime("org.livingdoc:livingdoc-repository-rest:2.0-SNAPSHOT")

	testImplementation("org.livingdoc:livingdoc-api:2.0-SNAPSHOT")
        ...
}

Because the LivingDoc 2 Engine is an extension of the JUnit 5 Engine, you will need to add JUnit 5 to your project as well.

How to install

Depending on your environment you can use the gradle wrapper gradlew and gradlew.bat or install gradle globally on your machine. For convenience we will use gradle in the rest of the documentation as command name. So for example gradle build means:

• Windows wrapper: gradlew.bat build

• Linux wrapper: ./gradlew build

• Linux without wrapper: gradle build

If you want to use your own build of livingdoc in other projects on your machine, you can publish the artifacts to your local maven repository by running gradle publishToMavenLocal. After this step the livingdoc Test Framework can be used in other projects by importing them with the group id org.livingdoc and the artifact id matching the project name.

If you are interested in a simple example, we refer to our QuickStart.adoc guide.

How to write tests

A good point to learn how to write the tests behind is documented at the Fixture Description. There, you’ll find a detailed description on how Decision Tables and Scenario Fixtures work.

Contributing

LivingDoc 2 is developed using Kotlin and Gradle.

How to import/open with IntelliJ

1. Cloning this repository

2. File → Open

3. Search for your cloned repository

4. Select the file build.gradle.kts → Press Ok

Structure

When your IDE is finished and the project is loaded, you will see the components LivingDoc 2 consists of. The engine is the heart of the project. It contains the logic of how the repository contents are handled and used. Each of the repository components defines its own approach to receiving data. For example, via local files or REST. There is also a test project. It contains a first starting point if you want to see some executable fixtures.

Architectural Decision Records can be found at the documentation of ADR.

You can find the description of some keywords at the Glossary.

External example project

We did set up an external project using LivingDoc 2. Head over to the Demo Project to see LivingDoc 2 in action!

License

LivingDoc 2 is licensed under the Apache License 2.0.

See LICENSE for the full license.