haxe-doctest 1.0.4

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

Released 2017-04-19.

To install, run:

haxelib install haxe-doctest 1.0.4

See using Haxelib in Haxelib documentation for more information.

This is not the latest stable version of haxe-doctest. See version 1.1.2 for the latest version.

Maintainervegardit
Websitehttps://github.com/vegardit/haxe-doctest
Current version1.1.2
StatisticsInstalled 2101 times
LicenseApache
Tags

README.md

haxe-doctest - Haxedoc based unit testing.

  1. What is it?
  2. Declaring test assertions
  3. Why doc-testing?
  4. Doc-testing with MUnit
  5. Doc-testing with Haxe Unit
  6. Doc-testing with FlashDevelop
  7. Installation
  8. Using the latest code
  9. 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.

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.

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("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.

@:build(hx.doctest.DocTestGenerator.generateDocTests())
class MyHaxeUnitTest extends haxe.unit.TestCase {

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

    function new() {
        super();
    }
}

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.

@:build(hx.doctest.DocTestGenerator.generateDocTests())
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);
        runner.run([MyMUnitDocTestSuite]);
    }
    
    public function new() {
        super();
        add(MyMUnitDocTests);
    }
}

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.

@:build(hx.doctest.DocTestGenerator.generateDocTests())
class MyDocTestRunner extends hx.doctest.DocTestRunner {

    public static function main() {
        var runner = new MyDocTestRunner();
        runner.runAndExit();
    }
    
    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.

InvokeMenuItem|FileMenu.Save
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.

Installation

  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

License

All files are released under the Apache License 2.0.