Guide to adding support for new haxe targets

There are three steps to adding support for a new target

• Support of target in core unit testing framework codebase
• Support for target in the MUnit build tool for compiling, running and testing against that target
• Verifying (or updating) example application to support additional target

Existing target specific logic is handled by inbuilt compilation flags (flash, js, neko). New targets should follow similar conventions

In many cases the existing targets have functionality split between single threaded (js, flash) and multithreaded (neko) implementations for executing tests and pushing output (to console or on screen).

NOTE: The easiest thing is probably to do a search for 'if neko' to highlight target specific branching based on conditional compilation flags

Extending Core

There are a number of steps that may be required to add support for a new target

1. Add new target to tool/test.hxml and tool/build.hxml

Simply append the hxml files with the new target to start compiling :)

2. Test execution

TestRunner.run() may need to be updated to handle the execution thread on command line targets.

massive.munit.TestRunner.run()

3. Timers

TestRunner also utilises massive.munit.util.Timer for Async tests (see summary below)

The MUnit Timer class is based off haxe.Timer, with better support delay/stamp on neko target.

As each target is handled differently, this will need to be updated.

massive.munit.util.Timer

4. Reflection

MUnit relies heavily on reflection (Reflect) for identifying and executing tests at runtime. If there are target specific issues with reflection then the following classes may need target specific workarounds:

massive.munit.TestRunner
massive.munit.TestClassHelper
massive.munit.async.AsyncDelegate
massive.munit.async.AsyncFactory

5. Report Clients

There are a number of default report clients that contain target specific logic for printing output:

massive.munit.client.PrintClient
massive.munit.client.RichPrintClient
massive.munit.client.HTTPClient

The most basic support would require updates to PrintClient.print() and RichPrintClient.print(). As can be seen in the snippet below (from PrintClient) the basic output already has logic for several unsupported targets (php, cpp)

override public function print(value:Dynamic)
{
    super.print(value);
    
    #if flash9
        textField.appendText(value);
        textField.scrollV = textField.maxScrollV;
    #elseif flash
        value = untyped flash.Boot.__string_rec(value, "");
        textField.text += value;
        textField.scroll = textField.maxscroll;
    #end
    
    #if (js || flash)
        external.print(value);
    #elseif neko
        neko.Lib.print(value);
    #elseif cpp
        cpp.Lib.print(value);
    #elseif php
        php.Lib.print(value);
    #end
   }

Extending Tooling

The MUnit build tool must be updated to handle specific targets.

1. Add a new TargetType

In tool/massive/munit/Target.hx:

enum TargetType
{
    as2;
    as3;
    js;
    neko;
}

2. Update TestCommand

massive.munit.command.TestCommand

This command is responsible for parsing the test.hxml file, extracting valid targets and compiling them.

• extracts the types to test from the console (initialise)
• parsing and augmenting each target's compilation paramters in the test.hxml file (execute)

3. Update RunCommand

massive.munit.command.RunCommand

This command is responsible for determining which targets to run and creating the final test runner and report contents in the munit bin directory.

There are a number of methods that may need to be supported including:

• getTargetTypes() extracts the types from the console arguments
• gatherTestRunnerFiles() determines which compiled outputs need to be copied into the munit testrunner bin directory
• generateTestRunnerPages() determines if target needs to run in browser or command line
• launchFile() and launchNeko() - responsible for launching the target applications
• execute() - responsible for coordinating all of the above

4. Update help contents

tool/template/help_*.txt

Each command has corresponding inline help (haxelib run munit help [command]). These should be updated to reflect any additional targets

Updating Example app

Simply update the text.hxml and build.hxml file with the new target. Then run

haxelib run munit test

to test all targets, or

haxelib run munit test -[target]

to test new target in isolation.