Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gianluigip/spectacle
Living Documentation for Distributed Systems
https://github.com/gianluigip/spectacle
bdd documentation-tool kotlin testing
Last synced: 3 months ago
JSON representation
Living Documentation for Distributed Systems
- Host: GitHub
- URL: https://github.com/gianluigip/spectacle
- Owner: gianluigip
- License: lgpl-3.0
- Created: 2022-01-25T13:50:43.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2023-10-04T23:48:23.000Z (over 1 year ago)
- Last Synced: 2024-10-09T17:30:50.552Z (3 months ago)
- Topics: bdd, documentation-tool, kotlin, testing
- Language: Kotlin
- Homepage:
- Size: 1.44 MB
- Stars: 6
- Watchers: 1
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://search.maven.org/artifact/io.github.gianluigip/spectacle-dsl-bdd)
[](https://hub.docker.com/r/gianluigipp/spectacle-central)
# Spectacle
### Living Documentation for Distributed Systems
In modern distributed systems the behavior of the product is defined across multiple components and
services, and usually developed by multiple teams, as a result, the documentation is fragmented and
difficult to find.
Additionally, the system tends to change faster than the documentation which makes the latter
unreliable.
Spectacle provides a solution for generating documentation from the multiple codebases in a modern
system and then storing it in a central repository that anyone can access.
It has two main components:
* `spectacle-dsl`: a Kotlin lib for transforming regular tests into specs that can be published to a
central repository of specifications.
* `spectacle-central`: a repository for specifications that allow to find and share the behaviour of
all the features in the system.
Spectacle follows the philosophy that only the code and by extension the tests provide accurate
documentation of the system, so it provides a DSL for writing readable tests that can be published
into a central repository to allows everyone to review.
## [Spectacle DSL](./spectacle-dsl/spectacle-dsl-publisher/README.md)
A Kotlin multiplatform library for generating documentation from tests and Markdown files, it can be
used as a standalone tool for improving the readability of tests or in combination
with `Spectacle Central` to generate living documentation.
Add dependencies:
```kotlin
testImplementation("io.github.gianluigip:spectacle-dsl-bdd:VERSION")
testImplementation("io.github.gianluigip:spectacle-dsl-assertions:VERSION")
testImplementation("io.github.gianluigip:spectacle-dsl-publisher:VERSION")
testImplementation("io.github.gianluigip:spectacle-dsl-http:VERSION")
testImplementation("io.github.gianluigip:spectacle-dsl-protobuf:VERSION")
```
Example of a JVM spec class:
```kotlin
@Feature("First Feature", description = "Description defining the feature.")
@ExtendWith(JUnitSpecificationReporter::class)
class JunitExampleTest {
@Test
@Specification
fun `DSL allow to write specs with minimum overhead`() =
given("a test with multiple steps") {
} whenever "it executes" run {
} then "it should register all the BDD steps" runAndFinish {
}
}
```
Review [Spectacle DSL README](./spectacle-dsl/spectacle-dsl-publisher/README.md) for more details.
## [Spectacle Central](./spectacle-central/README.md)
Repository for the living documentation generated by `Spectacle DSL`, it allows to centralize the
documentation generated from multiple executions of the `DSL` across multiple repositories, so even
though the docs are generated from multiple sources it can be queried from a central place which
increase the value for the organization as a whole.
### [Live Demo](https://spectacle-central.herokuapp.com/)
* Username: `guest`
* Password: `guest`
Review [Spectacle Central README](./spectacle-central/README.md) for more details.