Documentation from tests?

[Michael1993]

I was wondering if it is possible to generate documentation from test code. I just saw a talk that demonstrated ArchUnit creating human readable strings from test code and thought it would make sense to "lift" this text into the documentation?

The example was something like:

classes()
.that().areAnnotatedWith(Marker.class)
.should().haveSimpleNameEndingWith("Marker")
.because("marker classes should be easy to find")

Which generated

"Classes that are marked with @Marker should end with 'Marker' because marker classes should be easy to find."

[codecholeric]

I'm not sure what your specific requirements are. But principally I would say "of course" 😉 If you pick up the rules in some way yourself you can always just call ArchRule.getDescription(), which would yield exactly the text from your example.

Other than that, there is the concept of an "ArchUnit extension". You can check an example here.
It pretty much involves implementing com.tngtech.archunit.lang.extension.ArchUnitExtension and declaring the fully qualified class name in META-INF/services/com.tngtech.archunit.lang.extension.ArchUnitExtension (this is the standard JAVA SPI mechanism, check e.g. this tutorial).
Anyway, you could e.g. implement something like

public class DocsExtensions implements ArchUnitExtension {
    @Override
    public String getUniqueIdentifier() {
        return "custom-docs";
    }

    @Override
    public void configure(Properties properties) {
        // could read some custom props from archunit.properties
        // e.g. `custom-docs.path=path/in/ci/rules.txt`
    }

    @Override
    public void handle(EvaluatedRule evaluatedRule) {
        String ruleText = evaluatedRule.getRule().getDescription();
        // write ruleText to docs
    }
}

Then add a file META-INF/services/com.tngtech.archunit.lang.extension.ArchUnitExtension with the content

com.myapp.DocsExtensions

(with the fully qualified name of the extensions class). During your test run every rule that gets evaluated would cause this extension handle method to be called, so you could create the docs during your test run 🤷

On the other hand, if that is what you want you might also be able to just parse the standard test report of the test tool and extract the rule descriptions there 🤪