Home

Spock React is intended to provide an easy way to generate complete documentation from a Spock test suite.

Motivation

My goal was to allow my friend to generate a documentation page using his testsuit. Most of the time, writing documentation is a tedious task and many developers - including me - are not that enthusiastic about it. However, documentation is an important thing, as are tests. Well written tests cover many functionalities => from that we could derive a technical documentation. With additional features we can enhance the technical documentation.

And that is the goal of this project. To combine two important things and thus minimize the effort for a developer.

This project provides a template website that can be hosted and managed on Github. At the moment (as of 12.2023) there is one design - this will be extended in the future! However, the goal is to implement all basic features in V1 and to offer a standardized documentation webpage. Later the website will be expanded more and more 🤟

How it works

Spock-React dynamically serves Spock test reports and makes them browsable, effectively turning your Spock test suite into living documentation, on the fly.

It is based on the Spock Reports plugin and a set of template files that are used to generate raw (test report) json files every time a test run is executed on your project. You can then use Spock-React to point to the location of these json files, and it will fetch them and generate a documentation website complete with examples and code snippets on the fly.

So every time you run your tests and the json files are updated, the documentation website will be updated as well because it is served dynamically.

Getting Started

First of all you need to fork this repository.

Two parts must be set up:

• Spock Templates
• React Frontend

The Spock templates are there to generate json files from the Spock tests, which can then be read by the React frontend. You also need to set up and configure the React frontend.

Spock Templates

To create living react documentation from your Spock test suite, you need a few simple dependencies:

First and foremost, the Spock test framework:

testImplementation platform("org.spockframework:spock-bom:$spockVersion")
testImplementation "org.spockframework:spock-core"

Keep in mind that Spock is based on Groovy, so make sure you have the Groovy plugin for Gradle, otherwise Gradle will not be able to find (and execute) your Spock tests:

plugins {
    id 'groovy'
    // ... some other plugins ...
}

And finally you need the Spock reports plugin which is used to generate the raw json files from your Spock tests:

// you can use testRuntimeClasspath if you don't want to use spock-report-specific features in your Specs
testImplementation( "com.athaydes:spock-reports:$spockReportsVersion" ) {
    transitive = false // this avoids affecting your version of Groovy/Spock
}
// if you don't already have slf4j-api and an implementation of it in the classpath, add this! (needed for reports)
testImplementation 'org.slf4j:slf4j-api:1.7.30'
testImplementation 'org.slf4j:slf4j-simple:1.7.30' // You might need to adjust the version for spock-reports...

After you have added the dependencies to your project, you need to give the report plugin some configuration and templates to work with. All of this can be found in the ./spock-conf folder of this repository. You simply need to copy the contents of this folder into your project's ./src/test/resources folder.

This should then look something like this:

your-project
│   ...
│
└───src
    │
    └───main
    │       ...
    │
    └───test
        │
        └───resources
            │   SpockConfig.groovy
            │
            │
            └───templates
                    spec-template.json
                    summary-template.json

I encourage you to take a look at the SpockConfig.groovy file because there you can configure the report plugin to your needs (e.g. project name, version etc.). It also specifies where the templates produced by the plugin should be written to after a test run!

This is by default set to ./docs/spock, but you can change it to whatever location you want. This is also the location where you will want the Spock-React website to look for the json files so that it can read them and generate the documentation!

Frontend

As a prerequisite you have to install yarn and NodeJS (see version above). Normally npm will be install in the matching version - please check if the version match with above.

Then, all dependencies must be installed. To do this, run the following command in a terminal in the root folder:

yarn

To verify that the project build, execute the following command:

yarn run build

Next you have to configure the project! All settings can be found in ./environment.json. There you have to store all the URLs (see also Documentation).

Now you can run your project locally:

yarn dev

If you want to deploy the project from a local command, then you need to run these two commands:

yarn build
yarn deploy