jdoc-test

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;
    }
}

What?

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.

WHAT?

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.

⚠️ Library tests itself using itself executing own jdoc-spock tests written in javadocs.

WHAT???

Yes, see jdoc-spock and jdoc-cucumber test examples in source code.

HOW?

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