Write BDD tests in javadocs!
Documentation (AI generated): https://boolivar.github.io/jdoc-test/
public class MathUtils {
/**
* Calculate square of x.
*
* <pre><code lang="spock">
* def "returns square"() {
* expect:
* MathUtils.sqr(2) == 4
* }
* </code></pre>
*
* <pre><code lang="gherkin">
* Feature: square calculation
* Scenario Outline: integers
* When input value equals <x>
* Then result should be <sqr>
* Examples:
* | x | sqr |
* | 0 | 0 |
* | 1 | 1 |
* | 2 | 4 |
* |-1 | 1 |
* | 10| 100 |
* | 11| 121 |
* </code></pre>
*/
public static int sqr(int x) {
return x * x;
}
}jdoc-test is a framework for javadoc sourced java tests.
Javadoc writing is cumbersome. Documentation quickly becomes outdated. There is no guarantee that code does what documentation says.
Developers often prefer to write tests instead of documentation. Tests never lie.
So why not just write tests in documentation? BDD frameworks use test specifications written in (more or less) human language. Such documentation goes in sync with actual code and shows code usage example. Java code, tests and documentation become tightly coupled by putting BDD specification in javadoc.
| Component | Type | Description |
|---|---|---|
| jdoc-spock | junit engine library | Runs spockframework test specifications written in javadocs. |
| jdoc-spock-gradle-plugin | gradle plugin | Automates spockframework specs generation and testing. |
| jdoc-cucumber | junit engine library | Runs gherkin features written in javadocs. |
| jdoc-cucumber-gradle-plugin | gradle plugin | Automates cucumber feature generation and testing. |
jdoc-spock tests written in javadocs.
Yes, see jdoc-spock and jdoc-cucumber test examples in source code.
See the component READMEs for detailed usage:
- jdoc-spock — write and run Spock specs from javadocs using JUnit engine
- jdoc-cucumber — write and run Gherkin features from javadocs using JUnit engine
- jdoc-spock-gradle-plugin — automate Spock spec generation and testing via Gradle
- jdoc-cucumber-gradle-plugin — automate Cucumber feature generation and testing via Gradle