How to Write a Drill Bit Test - LemontechSA-backup/TideSDK GitHub Wiki

Introduction

Drillbit is a Titanium unit test framework. Drillbit resembles a JSSpec test and uses some of their convention. To define a test, create a folder with the name of the test and a file with the same name as the folder ending with js. For example, if your test is named 'foo', you would have a folder named 'foo' with a 'foo.js' file inside it.

Inside your test file, define the following:

describe("description of your test", {
});

The first parameter is the description for your test. The second parameter is your test spec.

There are a number of magic properties that can be defined (optional):

before_all : function is called before all tests are run
after_all : function is called after all tests are run
before : function is called before each and every test method
after : function is called after each and every test method
timeout : property in milliseconds for the max time the test should take

All other properties that are functions will be considered tests. If the test is asynchronous, the test should end in the name "_as_async" and will receive one argument for the callback object.

The callback objective has 2 main functions to control test completion:

passed : called to indicate that the test passed
failed : called to indicate that the test failed. the arg is the exception or message

Async Example:

describe("test", {
  "test_as_async": function(callback) {
    setTimeout(function() {
      callback.passed();
    }, 1000);
  }
});

Sync Example:

describe("test", {
  "before":function() {
    this.abc = '123';
  },
  "after": function() {
    this.abc = null;
  },
  "test":function() {
    value_of(this.abc).should_be('123');
  }
});

Assertions

To make test assertions, wrap your values in a 'value_of' method and then you'll have a bunch of convenience methods (all starting with 'should_').

Here's a few examples, the rest can be found in drillbit_func.js:

should_be : equality test
should_be_exactly : exact match test
should_not_be : negative test
should_be_true : value must be true (boolean)
should_be_false : value must be false (boolean)
should_be_null : value must be null
should_not_be_null : value must not be null
should_be_undefined : value must be undefined
should_not_be_undefined : value must not be undefined
should_be_function : value must be a function
should_be_object : value must be an object
should_be_number : value must be a number
should_contain : value must be contained (indexof)
should_be_one_of : value must be found in array
should_be_zero : value must be 0 (number)

Examples:

value_of(Titanium.App.getVersion()).should_be_number();
value_of(Titanium.userAgent).should_contain('Titanium/');
value_of('a').should_be_one_of(['a','b','c']);

Special cases for async:

If you run async, you must catch exceptions inside code that isn't part of the test execution path. For example, if you're inside a method such as:

setTimeout(function() {
  try {
    value_of('a').should_be('b');
    callback.passed();
  } catch(e) {
    callback.failed(e);
  }
}, 100);

You'll need to surround any value_of tests around a try/catch and call the appropriate passed/failed yourself.

Testing with special files

You can test with special files like tiapp.xml and manifest. To create your own file, use the following naming convention:

<testname>.xml 			- special tiapp.xml will be renamed and used
<testname>.manifest		- special manifest will be renamed and used
<testname>.js			- main js test
<testname>.html			- main index.html to be used
<testname>.usjs			- user script to be renamed and used

All other files not matching the convention above will be copied into the Resources folder before starting the test.

If you don't include an HTML file, the test will be run non-visual (it will be hidden).

Results from your test

The following files will be written into the Resources/test_results folder:

<testname>.json		- json result for test
<testname>.log		- application log for test
<testname>.prof		- application profile results for test