haxe.unit, the unit testing package bundled in Haxe std library

May 18th, 2013  |  Published in Uncategorized

Not sure if you knew, there has been a minimal basic unit testing package, haxe.unit, bundled in the Haxe std library, since Haxe 1.02! Although its functionality is minimal, but it is enough for most of the projects and being very target independent. I would definitely recommend it to any beginner of writing unit test.

The haxe.unit package consists of only 4 classes:

  • TestCase
  • TestResult
  • TestRunner
  • TestStatus

Most of the time we need to use only 2 of them: TestCase and TestRunner. We subclass TestCase and put the test functions as class methods, and then create a TestRunner object to run one or multiple TestCase instances. I usually create one class for each class I want to test and create one test method for each of the methods.

For example we want to test the StringTools class in the top-level package of the Haxe std library. Here we wrote the test function for 2 methods, endsWith and hex:

class TestStringTools extends haxe.unit.TestCase {
	public function testEndsWith():Void {
		this.assertTrue(StringTools.endsWith("abcd", "cd"));
		this.assertFalse(StringTools.endsWith("abcde", "cd"));
	public function testHex():Void {
		this.assertEquals("FFFFFF", StringTools.hex(0xFFFFFF, 6));
		this.assertEquals("000000", StringTools.hex(0, 6));
	static function main():Void {
		var runner = new haxe.unit.TestRunner();
		runner.add(new TestStringTools());
		var success = runner.run();
		#if sys
		Sys.exit(success ? 0 : 1);

As illustrated above, to check the return values of the function calls, there are 3 methods come from the TestCase class we can make use of:

  • function assertTrue( b : Bool, ?c : PosInfos ) : Void;
  • function assertFalse( b : Bool, ?c : PosInfos ) : Void;
  • function assertEquals( expected : T, actual : T, ?c : PosInfos ) : Void;

They are self-explanatory. You may have noticed, they all accept an extra optional argument of type PosInfos, which is actually used for getting the method name, line number etc for printing the test result. We should simply ignore it and the compiler will automatically fill in the value.

Notice that the test methods have to be named with prefix “test”. We can create utility functions, without the “test” prefix, and they will be ignored by TestRunner.

To run the tests, we created a TestRunner in the main entry function. The main function can of course be put into another class, but since we’ve only one TestCase in this example, let’s just put it into our TestCase. When we call runner.run(), it will test all the TestCase objects that are added to the TestRunner, and immediately print the test result, which for our example, it would be:

Class: TestStringTools ..
OK 2 tests, 0 failed, 2 success

Lastly, based on the return value of runner.run(), which is “all tests success or not”, we exit the program properly as a best practice. It is used by many CI softwares, for example TravisCI, in order to get back the test result.

There exist more advanced unit testing frameworks, like munit and utest, but the structure and concept is somewhat similar. Anyway, writing unit test is easy and the benefit is huge: It will enables us to discover regression that may caused by refactoring, adding new features, changes in 3rd party library (or Haxe itself) as soon as possible. Let’s start doing it today if you haven’t!


jQueryExtern 2.0.0-alpha.1

May 14th, 2013  |  Published in Uncategorized

It took longer than expected, but jQueryExtern for Haxe 2.0.0-alpha.1 was released to haxelib!

The cool parts:

  • Supports jQuery version 1.9.1/2.0.0! Note that 2.0.0 has the same API of 1.9.1, but removed support of IE 6,7,8.
  • jQueryExtern is now generated from the official jQuery documentation in xml format. It means it will be updated faster, more accurate in the future!
  • Fine grained configuration of the extern via… macros! e.g. Select specific jQuery support version, switching between the use of “$” or “jQuery” in generated code etc.
  • Macro based Plugin extern system! Writing jQuery plugin extern is much easier.

You can find out the details at the github wiki page.

Tags: ,

Automated unit-testing for Haxe project using Travis-CI

March 19th, 2013  |  Published in Uncategorized

What is Travis-CI?

Travis-CI is “a hosted continuous integration service for the open source community”. It is tightly integrated with github, once we enabled its commit hook, whenever there is a new commit, or a pull request, on any branch, it will automatically build and run the unit test and notify us any problem respecting to certain commits.

Why use it?

It gives us an extra level of safety, which safety is what we Haxe users love, after all that’s one of the reasons to use a strictly typed language over a dynamic one. Travis-CI’s unit test on pull request is particularly useful, which we can instantly identify on the github pull request page any incoming changes that breaks our specification.

And did I mention this great hosted service is in fact free for open source projects?

How to use it?

All we have to do is to toggle the repo on in the Travis-CI accounts control panel, and then commit a .travis.yml in the root directory.

Here is an example .travis.yml that test C++, Neko and PHP targets:

# The first thing is to tell which VM environment we want the test to be run on.
# It dosen't quite matter for Haxe, just choose one of the targets our project support (e.g. PHP),
# and than apt-get install the others (e.g. Neko, C++).
# For more info, see http://about.travis-ci.org/docs/user/ci-environment/
language: php
# Install Haxe before running the test.
  - sudo apt-get update                                # run update before installing anything
  - sudo apt-get install python-software-properties -y # for the next command
  - sudo add-apt-repository ppa:eyecreate/haxe -y      # add the ubuntu ppa that contains haxe
  - sudo apt-get update                                # pull info from ppa
  - sudo apt-get install haxe -y                       # install haxe (and neko)
  - sudo apt-get install gcc-multilib g++-multilib -y  # VM is 64bit but hxcpp builds 32bit
  - mkdir ~/haxelib                                    # create a folder for installing haxelib
  - haxelib setup ~/haxelib
  - haxelib install hxcpp                              # install hxcpp to test C++ target
  - mkdir bin                                          # create an output folder if needed
# Run the test!
  - haxe travis.hxml

Note that at the time of writing, Travis-CI is running 64bit Ubuntu 12.4 VMs, and the ppa we used above will install Haxe 3.0RC and Neko 2.0.

Every command specified in the “script” section is actual test and should exit with code 0 if it pass or non-0 if fail. The above example simply try to compile the project. We can specify subsequent command to run a Haxe written test case, which we can use Sys.exit(allPass ? 0 : 1) to properly inform the test result.

Finally, we can check the repo page on Travis-CI for the test result. By default, if the test failed, an email will be sent to the commit author and the committer.

Existing Haxe project using Travis-CI

Some Haxe projects have been using the Travis-CI service for some time, for example flambeHaxePunk and Ash-HaXe. We will soon re-enabled the TravisCI test of NME too! Hope it will help Haxe to become more solid every day, every commit ;)