<commit_before># haxe-doctest - Haxedoc based unit testing.

1. [What is it?](#what-is-it)
1. [Declaring test assertions](#declaring-test-assertions)
1. [Why doc-testing?](#why-doc-testing)
1. [Doc-testing with MUnit](#doctest-with-munit)
1. [Doc-testing with Haxe Unit](#doctest-with-haxeunit)
1. [Doc-testing with FlashDevelop](#doctest-testrunner)
1. [Installation](#installation)
1. [Using the latest code](#latest)
1. [License](#license)


## <a name="what-is-it"></a>What is it?

A [haxelib](http://lib.haxe.org/documentation/using-haxelib/) inspired by
Python's [doctest](https://docs.python.org/2/library/doctest.html) 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](http://haxe.org/manual/std-unit-testing.html), [MUnit](https://github.com/massiveinteractive/MassiveUnit), and it's own [test runner](#doctest-testrunner) which is recommended for efficient testing from within FlashDevelop.

    
## <a name="declaring-test-assertions"></a>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.

```haxe
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;
    }
}
```


## <a name="why-doc-testing"></a>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 defined 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.

1. 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.


## <a name="doctest-with-haxeunit"></a>Doc-testing with Haxe Unit<commit_msg>update doc<commit_after># haxe-doctest - Haxedoc based unit testing.

1. [What is it?](#what-is-it)
1. [Declaring test assertions](#declaring-test-assertions)
1. [Why doc-testing?](#why-doc-testing)
1. [Doc-testing with MUnit](#doctest-with-munit)
1. [Doc-testing with Haxe Unit](#doctest-with-haxeunit)
1. [Doc-testing with FlashDevelop](#doctest-testrunner)
1. [Installation](#installation)
1. [Using the latest code](#latest)
1. [License](#license)


## <a name="what-is-it"></a>What is it?

A [haxelib](http://lib.haxe.org/documentation/using-haxelib/) inspired by
Python's [doctest](https://docs.python.org/2/library/doctest.html) 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](http://haxe.org/manual/std-unit-testing.html), [MUnit](https://github.com/massiveinteractive/MassiveUnit), and it's own [test runner](#doctest-testrunner) which is recommended for efficient testing from within FlashDevelop.

    
## <a name="declaring-test-assertions"></a>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.

```haxe
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;
    }
}
```


## <a name="why-doc-testing"></a>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.
   
2. For users of your code, the doc-test assertions act as method documentation and code examples.

3. 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.


## <a name="doctest-with-haxeunit"></a>Doc-testing with Haxe Unit
{'fraction_non_alphanumeric': 0.13625077591558038, 'fraction_numerical': 0.00558659217877095, 'mean_word_length': 3.506993006993007, 'pattern_counts': {'":': 0, '<': 49, '<?xml version=': 0, '>': 105, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '844320', 'n_tokens_mistral': 2000, 'n_tokens_neox': 1903, 'n_words': 630}