Python inspired doc-testing for Haxe. Allows unit-testing based on test assertions in haxedoc. Integrates with Haxe Unit, MUnit and Tink Testrunner

To install, run:

haxelib install haxe-doctest 1.1.3 

See using Haxelib in Haxelib documentation for more information.


haxe-doctest - Haxedoc based unit testing.

Build Status Release License

  1. What is it?
  2. Declaring test assertions
  3. Why doc-testing?
  4. Doc-testing with Tink Testrunner
  5. Doc-testing with Haxe Unit
  6. Doc-testing with MUnit
  7. Doc-testing with hx.doctest.DocTestRunner
  8. Doc-testing with FlashDevelop
  9. Installation
  10. Using the latest code
  11. License

What is it?

A haxelib inspired by Python's doctest command that generates unit tests based on assertions declared within the Haxedoc comments of source code.

haxe-doctest supports the generation of test cases for Haxe Unit, MUnit, and it's own test runner which is recommended for efficient testing from within FlashDevelop.

Requires Haxe 3.2 or higher.

Declaring test assertions

Doc-test assertions are written as part of the source code documentation and are identified by three leading right angle brackets >>> before the assertion.

The left and the right side of the assertion must be separated by one of the comparison operators <, >, !=, <=, >= or the throws keyword.

If the right side expression is a regeex, e.g. ~/my string/ then it will be matched against the string representation of the left side expression.

class MyTools {

     * <pre><code>
     * >>> MyTools.isValidName(null)   == false
     * >>> MyTools.isValidName("")     == false
     * >>> MyTools.isValidName("John") == true
     * </code></pre>
    public static function isValidName(str:String):Bool {
        return str != null && str.length > 0;

class MyObject {

    var data:String;

     * <pre><code>
     * >>> new MyObject(null) throws "[data] must not be null!"
     * >>> new MyObject(null) throws ~/must not be null/
     * >>> new MyObject("ab") throws nothing
     * </code></pre>
    public function new(data:String) {
        if(data == null) throw "[data] must not be null!";
        this.data = data;

     * <pre><code>
     * >>> new MyObject("ab").length()  > 1
     * >>> new MyObject("ab").length()  <= 2
     * >>> new MyObject("abc").length() != 2
     * </code></pre>
    public function length():Int {
        return data == null ? 0 : data.length;

Why doc-testing?

  1. Doc-testing supports super fast test-driven development: First you write your method header, then the in-place documentation including your test assertions defining the expected behavior and then implement until all your declared tests pass.

No need to create separate test classes with individual test methods. Implementing and testing happens at the same code location.

  1. For users of your code, the doc-test assertions act as method documentation and code examples.

  2. Since doc-testing actually means testing the documentation against the documented code, a method's documentation always represents the actual behavior of it's implementation and can't get accidently outdated.

Doc-testing with Haxe Unit

Annotate a class extending haxe.unit.TestCase with @:build(hx.doctest.DocTestGenerator.generateDocTests()). The doc-test assertions from your source code will then be added as test methods to this class.

class MyHaxeUnitTest extends haxe.unit.TestCase {

    public static function main() {
        var runner = new haxe.unit.TestRunner();
        runner.add(new MyHaxeUnitTest());

    function new() {

Doc-testing with Tink Testrunner

Annotate a class extending tink.testrunner.BasicSuite with @:build(hx.doctest.DocTestGenerator.generateDocTests()). The doc-test assertions from your source code will then be added as test methods to this class.

class MyTinkTestrunnerTest extends tink.testrunner.Suite.BasicSuite {

    public static function main() {
        Runner.run(new MyTinkTestrunnerTest());

    function new() {
        super({name: Type.getClassName(Type.getClass(this))}, []);


Doc-testing with MUnit

Annotate a test class with @:build(hx.doctest.DocTestGenerator.generateDocTests()). The doc-test assertions from your source code will then be added as test methods to this class.

class MyMUnitDocTests {
    public function new() { }

Then add the test class to a testsuite

class MyMUnitDocTestSuite extends massive.munit.TestSuite {
    public static function main() {
        var client = new massive.munit.RichPrintClient();
        var runner = new massive.munit.TestRunner(client);

    public function new() {

Doc-testing with hx.doctest.DocTestRunner

haxe-doctest also comes with it's own Testrunner which is recommended for local testing as it generates console output that is parseable by FlashDevelop. When executed from within FlashDevelop, test failures will be displayed in the result panel as clickable errors that directly navigate your to the location in your source code.

To use it, annotate a class extending hx.doctest.DocTestRunner with @:build(hx.doctest.DocTestGenerator.generateDocTests()). The doc-test assertions from your source code will then be added as test methods to this class.

class MyDocTestRunner extends hx.doctest.DocTestRunner {

    public static function main() {
        var runner = new MyDocTestRunner();

    function new() { super(); }

To integrate this with FlashDevelop, create a batch file in your project root folder, e.g. called test-docs.cmd containing:

echo Compiling...
haxe -main mypackage.MyDocTestRunner ^
-cp src ^
-cp test ^
-neko target/neko/MyDocTestRunner.n || goto :eof

echo Testing...
neko target/neko/TestRunner.n

In FlashDevelop create a new macro in the macro editor (which is reachable via the menu Macros -> Edit Macros...) containing the following statements.

RunProcessCaptured|$(SystemDir)\cmd.exe;/c cd $(ProjectDir) & $(ProjectDir)\test-docs.cmd

Then assign the macro a short cut, e.g. [F4].

Now you can write your methods, document their behavior in the doc and by pressing [F4] your changes are saved and the doc-test assertions will be tested. Errors will showup as navigable events in the FlashDevelop's result panel.


  1. install the library via haxelib using the command:

    haxelib install haxe-doctest
  2. use in your Haxe project

  3. for OpenFL/Lime projects add <haxelib name="haxe-doctest" /> to your project.xml

  4. for free-style projects add -lib haxe-doctest to your *.hxml file or as command line option when running the Haxe compiler

Using the latest code

Using haxelib git

haxelib git haxe-doctest https://github.com/vegardit/haxe-doctest master D:\haxe-projects\haxe-doctest

Using Git

  1. check-out the master branch

    git clone https://github.com/vegardit/haxe-doctest --branch master --single-branch D:\haxe-projects\haxe-doctest
  2. register the development release with haxe

    haxelib dev haxe-doctest D:\haxe-projects\haxe-doctest

Using Subversion

  1. check-out the trunk

    svn checkout https://github.com/vegardit/haxe-doctest/trunk D:\haxe-projects\haxe-doctest
  2. register the development release with haxe

    haxelib dev haxe-doctest D:\haxe-projects\haxe-doctest


All files are released under the Apache License 2.0.

2 months ago

All libraries are free

Every month, more than thousand developers use haxelib to find, share, and reuse code — and assemble it in powerful new ways. Enjoy Haxe; It is great!

Explore Haxe

Haxe Manual

Haxe Code Cookbook

Haxe API documentation

You can try Haxe in the browser! try.haxe.org

Join us on Github!

Haxe is being developed on GitHub. Feel free to contribute or report issues to our projects.

Haxe on Github