download: package; code: explore

Firetest is my own afford to create a unit testing framework for JavaScript. I am not the kind of person who does projects like this but when the need arose and there were not suitable solutions that could fit my needs I decided to give it a go.

Firetest is based on Furebug or, more specifically, FirebugLite, if you are running a browser other then Mozilla Firefox. The reason for this decision is because Firebug is probably the most mature JavaScript debugging console available at the time of releasing this project. I thought that it might be a good idea to leave the Firebug developers concentrate on their stuff while I concentrate on mine. This way, I don’t need to reinvent the wheel.

Firetest was mainly build because I needed to perform tests on AttackAPI 2.x branch, which is kick-ass. Firetest became a standard part of AttackAPI unit testing. That means that you will find a copy of the project inside the attack package.

If you are familiar with Firebug you are most definitely familiar with Firetest. In practice you can use all Firebug functions such as: console.log, console.error, console.dir, etc. To start with Firetesting your application you have to create a testing document. In AttackAPI, there are two testing documents: firetest-interactive.htm and firetest-autoamtic.htm. firetest-interactive.htm is a very simple file primarily used for interactive testing. That involves a lot of typing in the Firebug console. The interactive testing file looks like the following:

<html debug="true">
	<head>
		<title>Interactive Firetest</title>
		<script src="firetest/firebug.js" type="text/javascript"></script>
		<script src="firetest/firetest.js" type="text/javascript"></script>
		<script src="../build/AttackAPI-standalone.js" type="text/javascript"></script>
	</head>
</html>

Notice the debug=”true” attribute declared inside the html element. This declaration instructs Firebug to start debugging as soon as you open the page in the browser. The following lines load firebug.js, firetest.js and AttackAPI-standalone.js. Both firebug.js and firetest.js are essential so don’t forget to load them first. After the document is loaded you can press F12 or Ctrl+Shift+L (or ⌘+Shift+L on Mac) and begin testing.

We mentioned earlier that you can do automatic tests as well. Let’s have a look how firetest-automatic.htm looks like:

<html debug="true">
	<head>
		<title>Automatic Firetest</title>
		<script src="firetest/firebug.js" type="text/javascript"></script>
		<script src="firetest/firetest.js" type="text/javascript"></script>
		<script src="../build/AttackAPI-standalone.js" type="text/javascript"></script>
	</head>
	<body>
		<script type="text/javascript">
			function testBuildDomain() {
				var d1 = $A.utils.buildDomain({tld: 'com'});
				var d2 = $A.utils.buildDomain({name: 'example'});
				var d3 = $A.utils.buildDomain({subdomain: 'sub'});
				var d4 = $A.utils.buildDomain({subdomain: 'sub', name: 'example'});
				var d5 = $A.utils.buildDomain({subdomain: 'sub', tld: 'com'});
				var d6 = $A.utils.buildDomain({name: 'example', tld: 'com'});
				
				assert(
					'function utils.buildDomain',
					d1 == 'com' && d2 == 'example' && d3 == 'sub' && d4 == 'sub.example' && d5 == 'sub.com' && d6 == 'example.com',
					d1, d2, d3, d4, d5, d6);
			}
			
			function testBuildQuery() {
				var q1 = $A.utils.buildQuery({q1:''});
				var q2 = $A.utils.buildQuery({q1:'', q2:''});
				var q3 = $A.utils.buildQuery({name:'q1', value:'q2'});
				var q4 = $A.utils.buildQuery({name:'q1', value:'='});
				
				assert(
					'function utils.buildQuery',
					q1 == 'q1=' && q2 == 'q1=&q2=' && q3 == 'name=q1&value=q2' && q4 == 'name=q1&value=%3D',
					q1, q2, q3, q4);
			}
			
			function testScanHistory() {
				var results = {};
				$A.dom.scanHistory({
					urls: [document.location],
					
					onfound: function (url) {
						results[url] = true
					},
					
					oncomplete: function () {
						if (results[document.location])
							success('function dom.historyScan');
						else {
							failure('function dom.historyScan');
							log(results);
						}
					}
				});
			}
		</script>
		<input type="button" value="Start Firetesting" onclick="start()"/>
	</body>
</html>

Notice that every test function name starts with test. As long as you follow this convention everything will be OK. Also, notice that each testing function calls one or more Firetest primitives such as: success, failure, assert, etc. These primitives are defined in the global scope if not previously declared. It is safe to use Firetest.assert and Firetest.success instead of assert and success. I am not doing that since I know that there are no name collisions inside my current testing document.

The following table summarizes all Firetest primitives:

functiondescriptionusage
Firetest.start; start starts the Firetest engine. Although this sounds very complicated, in reality, it is very simple. Firetest.start(); start()
Firetest.success; success declare a successful test Firetest.success(’testname’); success(’testing function foo()’)
Firetest.failure; failure declare a failed test Firetest.failure(’testname’); failure(’testing function foo()’)
Firetest.assert; assert check if expression is valid and based on that declare a successful on not successful test. Everything behind the first two function arguments will be logged by using the Firetest.log function. Firetest.assert(’testname’, expression); assert(’testing function foo()’, foo() == true, foo())
Firetest.log; log log data to the console. This function calls Firebug console.log function. Firetest.log(data), log(data1, data2, data3)

Enjoy testing!