{"id":18645532,"url":"https://github.com/cscott/jdoctest","last_synced_at":"2025-04-11T12:31:23.218Z","repository":{"id":731638,"uuid":"380941","full_name":"cscott/JDoctest","owner":"cscott","description":"JDoctest is an implementation of Python's doctest for Java.","archived":false,"fork":false,"pushed_at":"2014-04-10T03:23:19.000Z","size":3920,"stargazers_count":9,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-25T13:51:10.143Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://cscott.net/Projects/JDoctest/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cscott.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2009-11-21T20:41:51.000Z","updated_at":"2025-03-25T06:07:57.000Z","dependencies_parsed_at":"2022-08-16T10:45:23.204Z","dependency_job_id":null,"html_url":"https://github.com/cscott/JDoctest","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cscott%2FJDoctest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cscott%2FJDoctest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cscott%2FJDoctest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cscott%2FJDoctest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cscott","download_url":"https://codeload.github.com/cscott/JDoctest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248401955,"owners_count":21097328,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T06:16:21.415Z","updated_at":"2025-04-11T12:31:22.849Z","avatar_url":"https://github.com/cscott.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JDoctest\n\n[![Build Status](https://travis-ci.org/cscott/JDoctest.png)](https://travis-ci.org/cscott/JDoctest)\n\nJDoctest is an implementation of Python's [doctest] for Java, based on the\nideas in [`doctestj`] and [Rhino's doctests].\n\nUnlike doctestj, JDoctest is a javadoc [`Taglet`], rather than a [`Doclet`].\nIt doesn't replace the standard javadoc, it just adds a new `@doc.test`\ntag.  We also use a multiline format similar to Python's doctest\n(based on Rhino's implementation) rather than insist on a single\nevaluated expression, as doctestj does.\n\nDoctest blocks are written in Javascript.  [Calling from Javascript into Java]\nis straightforward. An example from the top of the\n`net.cscott.jdoctest.JDoctest` class:\n\n```\n/**\n * A \"@doc.test\" tag specifies an interactive javascript\n * session, in an environment where the class' package has been imported.\n * The output of the javascript session should match the output\n * provided.\n *\n * @author C. Scott Ananian\n * @doc.test\n *   This is an example of a test which passes:\n *   js\u003e \"a\".equals(\"a\")\n *   true\n * @doc.test\n *   This is an example of a test which fails:\n *   js\u003e 1+2\n *   5\n * @doc.test\n *   We can write tests which expect exceptions to be thrown, although\n *   it's a little clunky (implementing doctest.ELLIPSIS or\n *   doctest.IGNORE_EXCEPTION_DETAIL would make this nicer):\n *   js\u003e try {\n *     \u003e   java.lang.String(\"hi\").charAt(3);\n *     \u003e } catch (e) {\n *     \u003e   print(e.javaException.getMessage())\n *     \u003e }\n *   String index out of range: 3\n * @doc.test\n *   This demonstrates that the current package has been imported:\n *   js\u003e JDoctest\n *   [JavaClass net.cscott.jdoctest.JDoctest]\n *   js\u003e Version.PACKAGE_NAME\n *   jdoctest\n * @doc.test\n *   Note that results referencing object hashes are properly handled in\n *   the output comparison function, even when Rhino gives a different hash\n *   at runtime:\n *   js\u003e o = new java.lang.Object()\n *   java.lang.Object@1d2068d\n *   js\u003e o\n *   java.lang.Object@1d2068d\n *   js\u003e new java.lang.Object()\n *   java.lang.Object@1ac2f9c\n */\npublic class JDoctest implements Taglet { ... }\n```\n## Build and install\n\nTo build:\n * You must have a JDK 1.5 or greater.  In JDoctest version 1.5 I removed\n   support for pre-1.5 JDKs.\n   * In older JDKs, you might need to copy `sample.build.properties`\n   to `build.properties` and edit it to properly reflect that path to\n   your JDK, so that we can find the JDK's `tools.jar` file.\n * Run `ant javadoc`, which will build the source code and then run its\n   doctests.\n * One (ignored) failure is to be expected as the tests are run; it is\n   included to show the results of a failing test in the output javadoc.\n\nTo install:\n\n * Move the generated `jdoctest-*.jar` as well as `lib/rhino*/js.jar` to\n   a directory in your project.  Below, we will assume\n   that you've placed both these files in `lib/jdoctest` in your project.\n * If you intend to use the JUnit test support, you wil also need\n   `lib/junit-4.6.jar` and the `tools.jar` from your JDK release in your\n   classpath (see junit rules for ant below).\n\n## Command-line usage\n\nTo invoke from the command line:\n\n```sh\n javadoc -taglet net.cscott.jdoctest.JDoctest \\\n         -tagletpath lib/jdoctest/jdoctest.jar:lib/jdoctest/js.jar:bin \\\n\t -J-ea \\\n         \u003cyour other javadoc options go here\u003e\n```\n\nThe above command-line assumes that your source code has been compiled\ninto `bin`; change that part of the `-tagletpath` if your classes are\nelsewhere.  Your compiled `.class` files must be included on the\n`tagletpath` so that we can run the doctests.\n\nNote that you need to use the `-J-ea` option if you want assertions to\nbe enabled during the evaluation of the doctests.  You can use\n`-J-ea:\u003cyour package\u003e...` to only enable assertions in your code (not in\nthe entire javadoc tool).\n\nAdd `-J-Dnet.cscott.jdoctest.output=\u003cdir\u003e` to emit the javascript doctests\ninto files in `\u003cdir\u003e` where they can be re-run standalone.  This is\nhelpful for debugging failing tests.\n\n## Ant integration\n\nAnt rule:\n```xml\n  \u003cjavadoc failonerror=\"true\" ...\u003e\n    \u003ctaglet name=\"net.cscott.jdoctest.JDoctest\"\n            path=\"lib/jdoctest/jdoctest.jar:lib/jdoctest/js.jar:bin\" /\u003e\n    \u003carg value=\"-J-ea\" /\u003e\n    \u003cclasspath\u003e ...your classpath here... \u003c/classpath\u003e\n  \u003c/javadoc\u003e\n```\n\nAs before, replace `bin` with the appropriate path to your compiled\nproject classes.  The `-J-ea` option ensures assertions are enabled\nin your code when doctests are evaluated. Add:\n```xml\n    \u003carg value=\"-J-Dnet.cscott.jdoctest.output=your/dir/here\" /\u003e\n```\nto dump the discovered doctests into `your/dir/here` for re-running\nstandalone.\n\n## Pretty output\n\nYou may want to add css rules to make the output prettier.  JDoctest has\nhooks to allow the use of [google-code-prettify],\nwhich will do syntax highlighting on the client side.  The [`build.xml`]\nfile for JDoctest shows how this might be hooked up.  The files in\n`src/doc-files` should be copied to a `doc-files` subdirectory of the top-level\nsource directory of your project.\n\n## JUnit test support\n\nThere are two ways to hook up doctests to JUnit.\n\nThe simplest uses the\n`net.cscott.jdoctest.output` option described above: running\n`net.cscott.jdoctest.RerunJDoctests` as a JUnit test will rerun all\nemitted standalone tests.  It assumes these tests were emitted into\n`api/tests`; if you prefer them someplace else, subclass `RerunJDoctests`\nand reimplement the `listTests()` method to call `listTests(String dirName)`\nwith the appropriate alternate directory name.\n\nThe following ant rule implements this option:\n```xml\n    \u003ctarget name=\"retest\" ...\u003e\n      \u003cjunit\u003e\n\t\u003cformatter type=\"plain\"/\u003e\n\t\u003ctest name=\"net.cscott.jdoctest.RerunJDoctests\" /\u003e\n\t\u003cclasspath refid=\"classpath.path\" /\u003e\n\t\u003cassertions\u003e\n\t  \u003cenable/\u003e\n\t\u003c/assertions\u003e\n      \u003c/junit\u003e\n    \u003c/target\u003e\n```\n\nA more elegant (but slower) mechanism invokes Javadoc on each of your\nsource files to extract and execute the doctests.  Simply annotate each\nof your doctest-containing classes with the JUnit annotation:\n```java\n    @RunWith(value=JDoctestRunner.class)\n```\nThe [`src/net/cscott/jdoctest/JDoctest.java`] file demonstrates how this is\ndone.  JUnit can then directly execute the doctests for your class.\n`JDoctestRunner` assumes that your sources are found below a directory\nnamed `src`; if your sources are elsewhere you can use the annotation:\n```java\n    @SrcRoot(value=\"src/dir/here\")\n```\nIf you need to use the `@SrcRoot` annotation extensively, you might find it\neasier to subclass `JDoctestRunner` and override its `defaultSrcRoot()` method.\n\nThe following ant rule implements this option:\n```xml\n    \u003ctarget name=\"test\" ...\u003e\n      \u003cjunit printsummary=\"yes\" fork=\"yes\" forkmode=\"once\" haltonfailure=\"yes\"\u003e\n\t\u003cformatter type=\"plain\"/\u003e\n\t\u003ctest name=\"...your source files here...\" /\u003e\n\t\u003cclasspath refid=\"classpath.path\" /\u003e\n\t\u003cassertions\u003e\n\t  \u003cenable /\u003e\n\t\u003c/assertions\u003e\n      \u003c/junit\u003e\n    \u003c/target\u003e\n```\nThe `fork=\"yes\"` option is necessary here, or else the embedded javadoc doesn't\nget the correct classpath: ant seems to use a classloader which knows the\ncorrect classpath but leaves the system property `java.class.path` set\narbitrarily (ie, wrong), and the embedded javadoc looks at `java.class.path`,\nnot its classloader, when resolving source references.\n\n## See also\n\n*  http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/taglet/overview.html\n\n## LICENSE\n\n    JDoctest, a doctest module for javadoc.\n    Copyright (C) 2009,2014 C. Scott Ananian \u003ccscott@cscott.net\u003e\n\n    This program is free software; you can redistribute it and/or modify\n    it under the terms of the GNU General Public License as published by\n    the Free Software Foundation; either version 2 of the License, or\n    (at your option) any later version.\n\n    This program is distributed in the hope that it will be useful,\n    but WITHOUT ANY WARRANTY; without even the implied warranty of\n    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n    GNU General Public License for more details.\n\n    You should have received a copy of the GNU General Public License\n    along with this program; if not, write to the Free Software\n    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA\n\n[doctest]:              https://docs.python.org/3/library/doctest.html\n[`doctestj`]:           http://code.google.com/p/doctestj/\n[Rhino's doctests]:     http://blog.norrisboyd.com/2008/03/doctest-in-rhino.html\n[Calling from JavaScript into Java]: https://developer.mozilla.org/en-US/docs/Rhino/Scripting_Java\n[`Taglet`]:             http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/taglet/overview.html\n[`Doclet`]:             http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/doclet/overview.html\n[google-code-prettify]: http://code.google.com/p/google-code-prettify/\n[`build.xml`]:          ./build.xml\n[`src/net/cscott/jdoctest/JDoctest.java`]: ./src/net/cscott/jdoctest/JDoctest.java\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcscott%2Fjdoctest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcscott%2Fjdoctest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcscott%2Fjdoctest/lists"}