I haven't used Geci, so can't really comment on all the things it
might be capable of.
With respect to something equivalent to Python doctests, in the Groovy
project we
have JavadocAssertionTestBuilder and JavadocAssertionTestSuite classes.
Feel free to look to those for inspiration (at least).
For Javadoc containing specially marked code blocks (assumes code is
in <pre>...</pre> tags and has the special attribute
class="groovyTestCase") the content is stripped out and placed into
JUnit tests and run as a suite - giving the correct line number
information if it fails. We do it for Groovy code but it could be done
for just Java code.
Examples:
<pre class="groovyTestCase">assert [4,5] ==
[1,2,3,4,5].intersect([4,5,6,7,8])</pre>
/**
* Randomly reorders the elements of the specified array.
* <pre class="groovyTestCase">
* Integer[] array = [10, 5, 20]
* def origSize = array.size()
* def copy = array.toList()
* array.shuffle()
* assert array.size() == origSize
* assert copy.every{ array.contains(it) }
* </pre>
*
* @param self an array
* @since 3.0.0
*/
You can stop using the JavadocAssertionTestSuite at any time.
The code will still be in the Javadoc as documentation but just won't
be tested any more as part of your test suite.
P.S. I haven't used JavadocAssertionTestSuite with Maven, just Gradle.
On Wed, Aug 28, 2019 at 11:43 AM Bruno P. Kinoshita <ki...@apache.org> wrote:
>
> In Python doctests are handy, where you can write documentation with code
> blocks, that can be executed with a unit-test running tool, validating the
> docs.
> It's the first time I heard about Geci. But if you could perhaps show the
> pros and cons, what is the maintenance involved, whether it would change
> anything in the final binary that the user sees or not, and any other
> risks/issues.
> If you are keen to show it in a PR, maybe just one or two examples would be
> enough to show how it works.
> Thanks! And thanks for your recent contributions to Commons Lang too Peter.
> Bruno
>
> On Wednesday, 28 August 2019, 1:00:50 am NZST, Peter Verhas
> <pe...@verhas.com> wrote:
>
> I have seen looking over the code of the LANG3 project that there are a lot
> of places where the code is copy/paste. Many times these copy/paste code is
> the result of the shortages of the Java language. We implement methods that
> look more or less the same but they have to be created for all primitive
> types. The maintenance of this code is cumbersome, changed at one place has
> to be changed at the other places as well.
>
> The framework Java::Geci can automate the maintenance of those code
> fragments. The framework is a test dependency ONLY, so it does not present
> an extra dependency for the users.
>
> The application of the framework can also be used to automatically
> copy/update code from the unit tests into the JavaDoc documentation, like
> copying and converting assertion statements into tables with inputs and
> results.
>
> I would be happy to create a few pull requests as a demonstration of how
> Java::Geci can be used for the purposes.
>
> QUESTION:
>
> What is your attitude towards a new tool like this? I do not ask a final
> decision for "yes we want to use it" or "no we do not want". I just want to
> know if the developer community would consider the use of such a tool.
>
> A last note: The tool is extremely non-invasive. Any project using it can
> decide at any point to discontinue the use. All it needs is to delete the
> tests that start the tool, remove the dependency from the POM file and that
> is it.
>
> --
> Peter Verhas
> pe...@verhas.com
> t: +41791542095
> skype: verhas
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
