From 3a0d0ce00dd0140295834f06566500f4cf20f76b Mon Sep 17 00:00:00 2001 From: Jenny Date: Thu, 15 Jun 2023 14:45:13 +0200 Subject: [PATCH] Readme Getting Started Section (#125) * restructure getting started section #77 * add getting started discription, adjust other part #77 * add frontend setup * change yarn code blocks #77 * change back #77 --- README.md | 85 ++++++++++++++++++++++++++++------------------------ package.json | 2 +- 2 files changed, 47 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index ffc7299..5d21aba 100644 --- a/README.md +++ b/README.md @@ -6,25 +6,26 @@ SpockReact is an easy way to automatically generate documentation from Spock tes ## 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. +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](https://github.com/renatoathaydes/spock-reports) plugin -and a set of [template files](spock-conf/templates) 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. +It is based on the [Spock Reports](https://github.com/renatoathaydes/spock-reports) plugin and a set of [template files](spock-conf/templates) 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. +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 -To create living react documentation from your Spock test suite, -you need a few simple dependencies: +First of all you need to [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo?tool=cli&platform=windows) 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](https://github.com/spockframework/spock): @@ -33,9 +34,7 @@ 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: +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: ```groovy plugins { @@ -44,8 +43,7 @@ plugins { } ``` -And finally you need the [Spock reports plugin](https://github.com/renatoathaydes/spock-reports) -which is used to generate the raw json files from your Spock tests: +And finally you need the [Spock reports plugin](https://github.com/renatoathaydes/spock-reports) which is used to generate the raw json files from your Spock tests: ```groovy // you can use testRuntimeClasspath if you don't want to use spock-report-specific features in your Specs @@ -57,11 +55,7 @@ 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. +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: @@ -86,25 +80,38 @@ your-project ``` -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! +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! +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! -You have to specify this same location in the form -of a URL in the `environment.json` file. -So if you host your documentation on GitHub, you might have a URL -looking something like this: `https://raw.githubusercontent.com/user/proj-reo/master/docs/spock/reports` +### Frontend -## Frontend +First, all dependencies must be installed. To do this, run the following command in a terminal in the root folder: -// TODO +```yarn +yarn +``` + +To verify that the project build, execute the following command: + +```yarn +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](https://github.com/Sonatai/spock-react#documentation)). + +Now you can run your project locally: + +```yarn +yarn dev +``` + +If you want to deploy the project from a local command, then you need to run these two commands: + +```yarn +yarn build +yarn deploy +``` ## Documentation diff --git a/package.json b/package.json index d32e6ce..203e958 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "test-vite-react-github-pages", - "version": "0.2.3", + "version": "0.3.0", "scripts": { "dev": "vite", "build": "tsc && vite build",