Support for top-level `fdescribes`?

[ivoanjo]

Hello there, and thanks for specnaz!

While trying to write a few examples to get acquainted with the library, I noticed that fdescribes is only defined on SpecBuilder but not on Specnaz.

This behavior was quite unexpected to me, as I had several fdescribes that worked, but one that behaved differently -- the top-level one.

Would you consider adding it? Thanks 🙏

[skinny85]

Hey @ivoanjo ,

thanks for opening the issue. You are correct that there is no fdescribes on the top level. Let me explain.

While Specnaz has its own API, it's limited in what it can actually accomplish by the frameworks it integrates with. In order to implement fdescribes on the top level correctly, we would need access to the entire test suite (all of the classes it contains) before starting execution of any single test class (to check whether any class uses fdescribes, and ignore all tests in classes using just regular describes). Unfortunately, the Runner API in JUnit 4 does not give you that access - you see only each class in isolation, so you cannot know whether any class in the suite uses fdescribes instead of describes. Because of this, using fdescribes with JUnit would not work (it would be the same as using a regular describes), and so, I decided not to add it, as I figured it would be too confusing.

Does this make sense?

[ivoanjo]

I see! Indeed it's a shame that JUnit 4's API cannot support this.

What do you think of adding a non-working version of it, for documentation?

/** Currently not supported, see https://github.com/skinny85/specnaz/issues/8 for
more details **/
@Deprecated
default void fdescribes(String description, Consumer<SpecBuilder> specClosure) {
    throw new UnsupportedOperationException("Unfortunately, and due to API limitations, fdescribes currently does not work on top-level specs. See https://github.com/skinny85/specnaz/issues/8 for more details");
}

This way, rather than getting a bit confused on why it doens't compile, users would get immediate IDE feedback -- it's deprecated and the documentation says it doesn't work, and if they missed it, they would get immediate feedback while starting up their test suite.

Edit: Either way, feel free to close the ticket and thanks for the feedback 😁

[skinny85]

Hmm, I think that might be a little harsh... what if fdescribes can be made to work with TestNG, or JUnit 5? I'd rather keep that door open :).

Thanks for opening the issue!